Semantic conventions for gRPC
Status: Stable, 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.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.status_code | | Required | string | The string representation of the status code returned by the server or generated by the client. [2] | OK; DEADLINE_EXCEEDED; UNAVAILABLE |
rpc.system.name | | Required | string | The Remote Procedure Call (RPC) system. [3] | grpc |
server.address | | Required | string | A string identifying a group of RPC server instances request is sent to. [4] | 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. [5] | UNKNOWN; DEADLINE_EXCEEDED; UNIMPLEMENTED; INTERNAL; UNAVAILABLE; DATA_LOSS |
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 [6] | int | Server port number. [7] | 50051 |
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.header.<key> |  | Opt-In | string[] | gRPC request headers, also called request metadata. [9] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.header.<key> | | Opt-In | string[] | gRPC response headers, also called initial metadata. [10] | ["attribute_value"] |
rpc.response.trailer.<key> | | Opt-In | string[] | gRPC response trailers, also called trailing metadata. [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.
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.status_code: All status codes except OK SHOULD be considered errors.
Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors.
[3] rpc.system.name: MUST be set to grpc.
[4] 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 DNS 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
[5] 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 status code is returned and it indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.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.
[6] server.port: If and only if the port is available and server.address is set.
[7] server.port: See the server.address for details on parsing the target string.
[8] network.peer.address: If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used.
[9] rpc.request.header.<key>: <key> is the normalized header name (lowercase), the value is the header values.
Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information.
For example, a header my-custom-key with value ["1.2.3.4", "1.2.3.5"] SHOULD be recorded
as the rpc.request.header.my-custom-key attribute with value ["1.2.3.4", "1.2.3.5"].
The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[10] rpc.response.header.<key>: <key> is the normalized header name (lowercase), the value is the header values.
Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information.
For example, a header my-custom-key with value ["attribute_value"] SHOULD be recorded
as the rpc.response.header.my-custom-key attribute with value ["attribute_value"].
The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[11] rpc.response.trailer.<key>: <key> is the normalized trailer name (lowercase), the value is the trailer values.
Instrumentations SHOULD require an explicit configuration of which trailers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information.
For example, a trailer my-custom-key with value ["attribute_value"] SHOULD be recorded
as the rpc.response.trailer.my-custom-key attribute with value ["attribute_value"].
The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to trailers.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
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.status_code attribute
for the details on which values classify as errors.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.status_code | | Required | string | The string representation of the status code returned by the server. [1] | OK; DEADLINE_EXCEEDED; UNAVAILABLE |
rpc.system.name | | Required | string | The Remote Procedure Call (RPC) system. [2] | grpc |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | UNKNOWN; DEADLINE_EXCEEDED; UNIMPLEMENTED; INTERNAL; UNAVAILABLE; DATA_LOSS |
rpc.method | | Conditionally Required if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | 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.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 |
server.address | | Recommended when available. | string | A string identifying a group of RPC server instances request is sent to. [8] | example.com; 10.1.2.80; /tmp/my.sock |
rpc.request.header.<key> | | Opt-In | string[] | gRPC request headers, also called request metadata. [9] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.header.<key> | | Opt-In | string[] | gRPC response headers, also called initial metadata. [10] | ["attribute_value"] |
rpc.response.trailer.<key> | | Opt-In | string[] | gRPC response trailers, also called trailing metadata. [11] | ["attribute_value"] |
[1] rpc.status_code: The following status codes SHOULD be considered errors:
UNKNOWNDEADLINE_EXCEEDEDUNIMPLEMENTEDINTERNALUNAVAILABLEDATA_LOSS
Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors.
[2] rpc.system.name: MUST be set to grpc.
[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 status code is returned and it indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.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] 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.
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.
[5] server.port: If server.address is set and the port is present in :authority.
[6] server.port: Instrumentations SHOULD populate server.port from the port
component of the HTTP/2 :authority pseudo-header the client used to
reach this server.
Instrumentations SHOULD NOT use actual network-level connection information for this purpose.
[7] network.peer.address: If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used.
[8] server.address: Instrumentations SHOULD populate server.address from the host
component of the HTTP/2 :authority pseudo-header the client used to
reach this server.
Instrumentations SHOULD NOT use actual network-level connection information for this purpose.
[9] rpc.request.header.<key>: <key> is the normalized header name (lowercase), the value is the header values.
Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information.
For example, a header my-custom-key with value ["1.2.3.4", "1.2.3.5"] SHOULD be recorded
as the rpc.request.header.my-custom-key attribute with value ["1.2.3.4", "1.2.3.5"].
The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[10] rpc.response.header.<key>: <key> is the normalized header name (lowercase), the value is the header values.
Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information.
For example, a header my-custom-key with value ["attribute_value"] SHOULD be recorded
as the rpc.response.header.my-custom-key attribute with value ["attribute_value"].
The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[11] rpc.response.trailer.<key>: <key> is the normalized trailer name (lowercase), the value is the trailer values.
Instrumentations SHOULD require an explicit configuration of which trailers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information.
For example, a trailer my-custom-key with value ["attribute_value"] SHOULD be recorded
as the rpc.response.trailer.my-custom-key attribute with value ["attribute_value"].
The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to trailers.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
Metrics
gRPC instrumentations SHOULD collect metrics according to the general Semantic Conventions for RPC Metrics.
rpc.system.name MUST be set to "grpc".
The call-duration bucket recommendations below match those used by gRPC’s existing OpenTelemetry metrics.
Metric: rpc.server.call.duration (gRPC)
This metric is recommended.
This metric follows the common rpc.server.call.duration
definition.
This metric SHOULD be specified with
ExplicitBucketBoundaries
of [ 0, 0.00001, 0.00005, 0.0001, 0.0003, 0.0006, 0.0008, 0.001, 0.002, 0.003, 0.004, 0.005, 0.006, 0.008, 0.01, 0.013, 0.016, 0.02, 0.025, 0.03, 0.04, 0.05, 0.065, 0.08, 0.1, 0.13, 0.16, 0.2, 0.25, 0.3, 0.4, 0.5, 0.65, 0.8, 1, 2, 5, 10, 20, 50, 100 ]
in seconds, instead of the general RPC bucket boundaries.
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
|---|---|---|---|---|---|
rpc.server.call.duration | Histogram | s | Measures the duration of an incoming gRPC call. [1] | |
[1]: When this metric is reported alongside an RPC server span, the metric value SHOULD be the same as the RPC server span duration.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.status_code | | Required | string | The string representation of the status code returned by the server. [1] | OK; DEADLINE_EXCEEDED; UNAVAILABLE |
rpc.system.name | | Required | string | The Remote Procedure Call (RPC) system. [2] | grpc |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | UNKNOWN; DEADLINE_EXCEEDED; UNIMPLEMENTED; INTERNAL; UNAVAILABLE; DATA_LOSS |
rpc.method | | Conditionally Required if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
server.address | | Opt-In | string | A string identifying a group of RPC server instances request is sent to. [5] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Opt-In | int | Server port number. [6] | 50051 |
[1] rpc.status_code: The following status codes SHOULD be considered errors:
UNKNOWNDEADLINE_EXCEEDEDUNIMPLEMENTEDINTERNALUNAVAILABLEDATA_LOSS
Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors.
[2] rpc.system.name: MUST be set to grpc.
[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 status code is returned and it indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.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] 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.
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.
[5] server.address: Instrumentations SHOULD populate server.address from the host
component of the HTTP/2 :authority pseudo-header the client used to
reach this server.
Instrumentations SHOULD NOT use actual network-level connection information for this purpose.
[6] server.port: Instrumentations SHOULD populate server.port from the port
component of the HTTP/2 :authority pseudo-header the client used to
reach this server.
Instrumentations SHOULD NOT use actual network-level connection information for this purpose.
Metric: rpc.client.call.duration (gRPC)
This metric is recommended.
This metric follows the common rpc.client.call.duration
definition.
This metric SHOULD be specified with
ExplicitBucketBoundaries
of [ 0, 0.00001, 0.00005, 0.0001, 0.0003, 0.0006, 0.0008, 0.001, 0.002, 0.003, 0.004, 0.005, 0.006, 0.008, 0.01, 0.013, 0.016, 0.02, 0.025, 0.03, 0.04, 0.05, 0.065, 0.08, 0.1, 0.13, 0.16, 0.2, 0.25, 0.3, 0.4, 0.5, 0.65, 0.8, 1, 2, 5, 10, 20, 50, 100 ]
in seconds, instead of the general RPC bucket boundaries.
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
|---|---|---|---|---|---|
rpc.client.call.duration | Histogram | s | Measures the duration of an outgoing gRPC call. [1] | |
[1]: When this metric is reported alongside an RPC client span, the metric value SHOULD be the same as the RPC client span duration.
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.status_code | | Required | string | The string representation of the status code returned by the server or generated by the client. [2] | OK; DEADLINE_EXCEEDED; UNAVAILABLE |
rpc.system.name | | Required | string | The Remote Procedure Call (RPC) system. [3] | grpc |
server.address | | Required | string | A string identifying a group of RPC server instances request is sent to. [4] | 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. [5] | UNKNOWN; DEADLINE_EXCEEDED; UNIMPLEMENTED; INTERNAL; UNAVAILABLE; DATA_LOSS |
server.port | | Conditionally Required [6] | int | Server port number. [7] | 50051 |
[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.
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.status_code: All status codes except OK SHOULD be considered errors.
Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors.
[3] rpc.system.name: MUST be set to grpc.
[4] 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 DNS 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
[5] 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 status code is returned and it indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.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.
[6] server.port: If and only if the port is available and server.address is set.
[7] server.port: See the server.address for details on parsing the target string.
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!