Semantic conventions for gRPC
Status: Release Candidate, unless otherwise specified
The Semantic Conventions for gRPC extend and override the RPC Semantic Conventions.
The gRPC project defines its own conventions for metrics and spans.
Details on how OpenTelemetry spans and metrics defined in this repository relate to the native gRPC conventions are documented in the gRPC compatibility document.
Spans
Client
Status:
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 section.
Span kind MUST be CLIENT.
Span status: refer to the Recording Errors
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 | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.method |  | 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 | | Required | string | The string representation of the status code returned by the server or generated by the client. [2] | OK; DEADLINE_EXCEEDED; -32602 |
server.address |  | 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 | | 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 | | 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 | | Conditionally Required [5] | int | Server port number. [6] | 50051 |
network.peer.address | | 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 | | Recommended If network.peer.address is set. | int | Peer port number of the network connection. | 65123 |
rpc.request.metadata.<key> |  | Opt-In | string[] | RPC request metadata, <key> 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.<key> | | Opt-In | string[] | RPC response metadata, <key> 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, 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.<key>: 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.<key>: 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):
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. | |
Server
Status:
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 section.
Span kind MUST be SERVER.
Span status: refer to the Recording Errors
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 | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.response.status_code | | Required | string | The string representation of the status code returned by the server. [1] | OK; DEADLINE_EXCEEDED; -32602 |
error.type | | 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 | | 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 | | 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 | | 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 | | Conditionally Required if applicable and if server.address is set. | int | Server port number. [5] | 80; 8080; 443 |
client.address | | 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 | | Recommended | int | Client port number. [7] | 65123 |
network.peer.address | | 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 | | Recommended If network.peer.address is set. | int | Peer port number of the network connection. | 65123 |
rpc.request.metadata.<key> | | Opt-In | string[] | RPC request metadata, <key> 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.<key> | | Opt-In | string[] | RPC response metadata, <key> 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:
UNKNOWNDEADLINE_EXCEEDEDUNIMPLEMENTEDINTERNALUNAVAILABLEDATA_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.<key>: 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.<key>: 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):
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. | |
Metrics
gRPC instrumentations SHOULD collect metrics according to the general Semantic Conventions for RPC Metrics.
rpc.system.name MUST be set to "grpc".
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!