Semantic conventions for gRPC
Status: Development
The Semantic Conventions for gRPC extend and override the RPC spans and RPC metrics Semantic Conventions that describe common RPC operations attributes in addition to the Semantic Conventions described on this page.
Client Span
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 |
error.type |  | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | 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.address | | Conditionally Required If available. | string | RPC server host name. [4] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Conditionally Required [5] | int | Server port number. [6] | 80; 8080; 443 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or Unix domain socket name. | 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 |
network.protocol.name | | Recommended | string | OSI application layer or non-OSI equivalent. [7] | http |
network.protocol.version | | Recommended | string | The actual version of the protocol used for network communication. [8] | 1.1; 2 |
network.transport | | Recommended | string | OSI transport layer or inter-process communication method. [9] | tcp; udp |
rpc.request.metadata.<key> | | Opt-In | string[] | RPC request metadata, <key> being the normalized RPC metadata key (lowercase), the value being the metadata values. [10] | ["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. [11] | ["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] 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.
[4] server.address: May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set server.address to the IP address provided in the host component.
[5] server.port: if server.address is set and if the port is supported by the network transport used for communication.
[6] 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.
[7] network.protocol.name: The value SHOULD be normalized to lowercase.
[8] network.protocol.version: If protocol version is subject to negotiation (for example using ALPN), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
[9] network.transport: The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.
[10] 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"]
[11] 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. | |
network.transport 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 |
|---|---|---|
pipe | Named or anonymous pipe. | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix domain socket | |
Server Span
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 | RPC server host name. [4] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Conditionally Required [5] | int | Server port number. [6] | 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. [7] | client.example.com; 10.1.2.80; /tmp/my.sock |
client.port | | Recommended | int | Client port number. [8] | 65123 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or Unix domain socket name. | 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 |
network.protocol.name | | Recommended | string | OSI application layer or non-OSI equivalent. [9] | http |
network.protocol.version | | Recommended | string | The actual version of the protocol used for network communication. [10] | 1.1; 2 |
network.transport | | Recommended | string | OSI transport layer or inter-process communication method. [11] | tcp; udp |
rpc.request.metadata.<key> | | Opt-In | string[] | RPC request metadata, <key> being the normalized RPC metadata key (lowercase), the value being the metadata values. [12] | ["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. [13] | ["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 server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set server.address to the IP address provided in the host component.
[5] server.port: if server.address is set and if the port is supported by the network transport used for communication.
[6] 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.
[7] 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.
[8] 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.
[9] network.protocol.name: The value SHOULD be normalized to lowercase.
[10] network.protocol.version: If protocol version is subject to negotiation (for example using ALPN), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.
[11] network.transport: The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.
[12] 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"]
[13] 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. | |
network.transport 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 |
|---|---|---|
pipe | Named or anonymous pipe. | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix domain socket | |
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!