# Semantic conventions for gRPC LLMS index: [llms.txt](/llms.txt) --- **Status**: [Release Candidate][DocumentStatus], unless otherwise specified The Semantic Conventions for [gRPC](https://grpc.io/) extend and override the [RPC Semantic Conventions](README.md). > [!NOTE] > The gRPC project defines its own conventions for [metrics](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) > and [spans](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md). > > Details on how OpenTelemetry spans and metrics defined in this repository > relate to the native gRPC conventions are documented in the > [gRPC compatibility](/docs/specs/semconv/non-normative/compatibility/grpc.md) document. ## Spans ### Client **Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) This span represents an outgoing Remote Procedure Call (RPC). `rpc.system.name` MUST be set to `"grpc"` and SHOULD be provided **at span creation time.** **Span name:** refer to the [Span Name](/docs/specs/semconv/rpc/rpc-spans.md#name) section. **Span kind** MUST be `CLIENT`. **Span status**: refer to the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document for details on how to record span status. See also `rpc.response.status_code` attribute for the details on which values classify as errors. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server or generated by the client. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | A string identifying a group of RPC server instances request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`rpc.method_original`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | Server port number. [6] | `50051` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. [7] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`rpc.request.metadata.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [8] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [9] | `["attribute_value"]` | **[1] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library. When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. **[2] `rpc.response.status_code`:** All status codes except `OK` SHOULD be considered errors. **[3] `server.address`:** Instrumentations SHOULD populate `server.address` (along with `server.port`) based on the configuration used when creating the gRPC channel and SHOULD NOT use actual network-level connection information for this purpose to ensure low cardinality. Instrumentations MAY parse address and port from the gRPC target string according to the [gRPC Name Resolution specification](https://grpc.github.io/grpc/core/md_doc_naming.html), depending on the scheme used. Or, they MAY use gRPC client APIs that provide this information. If the instrumentation cannot determine a server domain name or another suitable low-cardinality identifier for a group of server instances from the target string, it SHOULD set `server.address` to the entire target string and SHOULD NOT set `server.port`. When the address is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain a DNS name and SHOULD set `server.address` to the IP address provided. Examples: - Given the target string `grpc.io:50051`, expected attributes: - `server.address`: `"grpc.io"` - `server.port`: `50051` - Given the target string `dns://1.2.3.4/grpc.io:50051`, expected attributes: - `server.address`: `"grpc.io"` - `server.port`: `50051` - Given the target string `unix:///run/containerd/containerd.sock`, expected attributes: - `server.address`: `"/run/containerd/containerd.sock"` - `server.port`: not set - Given the target string `zk://zookeeper:2181/my-server`, expected attributes: - `server.address`: `"zk://zookeeper:2181/my-server"` - `server.port`: not set - Given the target string `ipv4:198.51.100.123:50051,198.51.100.124:50051`, expected attributes: - `server.address`: `"ipv4:198.51.100.123:50051,198.51.100.124:50051"` - `server.port`: not set **[4] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. If a response status code is returned and status indicates an error, `error.type` SHOULD be set to that status code. Check system-specific conventions for the details on which values of `rpc.response.status_code` are considered errors. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. **[5] `server.port`:** If and only if the port is available and `server.address` is set. **[6] `server.port`:** See the `server.address` for details on parsing the target string. **[7] `network.peer.address`:** If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. **[8] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` **[9] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_value"]` The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Server **Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) This span represents an incoming Remote Procedure Call (RPC). `rpc.system.name` MUST be set to `"grpc"` and SHOULD be provided **at span creation time.** **Span name:** refer to the [Span Name](/docs/specs/semconv/rpc/rpc-spans.md#name) section. **Span kind** MUST be `SERVER`. **Span status**: refer to the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document for details on how to record span status. See also `rpc.response.status_code` attribute for the details on which values classify as errors. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.response.status_code`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | The string representation of the [status code](https://github.com/grpc/grpc/blob/v1.75.0/doc/statuscodes.md) returned by the server. [1] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.method_original`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | A string identifying a group of RPC server instances request is sent to. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if applicable and if `server.address` is set. | int | Server port number. [5] | `80`; `8080`; `443` | | [`client.address`](/docs/specs/semconv/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [6] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`client.port`](/docs/specs/semconv/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [7] | `65123` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. [8] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`rpc.request.metadata.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC request metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [9] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPC response metadata, `` being the normalized RPC metadata key (lowercase), the value being the metadata values. [10] | `["attribute_value"]` | **[1] `rpc.response.status_code`:** The following status codes SHOULD be considered errors: - `UNKNOWN` - `DEADLINE_EXCEEDED` - `UNIMPLEMENTED` - `INTERNAL` - `UNAVAILABLE` - `DATA_LOSS` **[2] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. If a response status code is returned and status indicates an error, `error.type` SHOULD be set to that status code. Check system-specific conventions for the details on which values of `rpc.response.status_code` are considered errors. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. **[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library. When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. In such cases, tracing instrumentations MUST also set `rpc.method_original` attribute to the original method value. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. **[4] `server.address`:** May contain a DNS name, an endpoint and path in the service registry, local socket name or an IP address. Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. **[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[6] `client.address`:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. **[7] `client.port`:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. **[8] `network.peer.address`:** If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. **[9] `rpc.request.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as `rpc.request.metadata.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]` **[10] `rpc.response.metadata.`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a property `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_value"]` The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Metrics gRPC instrumentations SHOULD collect metrics according to the general [Semantic Conventions for RPC Metrics](/docs/specs/semconv/rpc/rpc-metrics.md). `rpc.system.name` MUST be set to `"grpc"`. [DocumentStatus]: /docs/specs/otel/document-status