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 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 Should be set based on the grpc status code. A mapping is defined in the grpc status section.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
rpc.grpc.status_code		Required	int	The numeric status code of the gRPC request.	0; 1; 2
rpc.method		Required	string	This is the logical name of the method from the RPC interface perspective. [1]	exampleMethod
rpc.service		Required	string	The full (logical) name of the service being called, including its package name, if applicable. [2]	myservice.EchoService
server.address		Required	string	RPC server host name. [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]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
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.grpc.request.metadata.<key>		Opt-In	string[]	gRPC request metadata, <key> being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [10]	["1.2.3.4", "1.2.3.5"]
rpc.grpc.response.metadata.<key>		Opt-In	string[]	gRPC response metadata, <key> being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [11]	["attribute_value"]

[1] rpc.method: This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The code.function.name attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).

[2] rpc.service: This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The code.namespace attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).

[3] 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.

[4] error.type: The error.type SHOULD be predictable, and SHOULD have low cardinality.

When error.type is set to a type (e.g., an exception type), its canonical class name identifying the type within the artifact SHOULD be used.

Instrumentations SHOULD document the list of errors they report.

The cardinality of error.type within one instrumentation library SHOULD be low. Telemetry consumers that aggregate data from multiple instrumentation libraries and applications should be prepared for error.type to have high cardinality at query time when no additional filters are applied.

If the operation has completed successfully, instrumentations SHOULD NOT set error.type.

If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it’s RECOMMENDED to:

• Use a domain-specific attribute
• Set error.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[5] server.port: 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.grpc.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.grpc.request.metadata.my-custom-key attribute with value ["1.2.3.4", "1.2.3.5"]

[11] rpc.grpc.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.grpc.response.metadata.my-custom-key attribute with value ["attribute_value"]

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

rpc.grpc.status_code 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
0	OK
1	CANCELLED
2	UNKNOWN
3	INVALID_ARGUMENT
4	DEADLINE_EXCEEDED
5	NOT_FOUND
6	ALREADY_EXISTS
7	PERMISSION_DENIED
8	RESOURCE_EXHAUSTED
9	FAILED_PRECONDITION
10	ABORTED
11	OUT_OF_RANGE
12	UNIMPLEMENTED
13	INTERNAL
14	UNAVAILABLE
15	DATA_LOSS
16	UNAUTHENTICATED

Server Span

Status:

This span represents an incoming Remote Procedure Call (RPC).

rpc.system 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 Should be set based on the grpc status code. A mapping is defined in the grpc status section.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
rpc.grpc.status_code		Required	int	The numeric status code of the gRPC request.	0; 1; 2
server.address		Required	string	RPC server host name. [1]	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. [2]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
server.port		Conditionally Required [3]	int	Server port number. [4]	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. [5]	client.example.com; 10.1.2.80; /tmp/my.sock
client.port		Recommended	int	Client port number. [6]	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. [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.method		Recommended	string	This is the logical name of the method from the RPC interface perspective. [10]	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable. [11]	myservice.EchoService
rpc.grpc.request.metadata.<key>		Opt-In	string[]	gRPC request metadata, <key> being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [12]	["1.2.3.4", "1.2.3.5"]
rpc.grpc.response.metadata.<key>		Opt-In	string[]	gRPC response metadata, <key> being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [13]	["attribute_value"]

[1] 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.

[2] error.type: The error.type SHOULD be predictable, and SHOULD have low cardinality.

When error.type is set to a type (e.g., an exception type), its canonical class name identifying the type within the artifact SHOULD be used.

Instrumentations SHOULD document the list of errors they report.

The cardinality of error.type within one instrumentation library SHOULD be low. Telemetry consumers that aggregate data from multiple instrumentation libraries and applications should be prepared for error.type to have high cardinality at query time when no additional filters are applied.

If the operation has completed successfully, instrumentations SHOULD NOT set error.type.

If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it’s RECOMMENDED to:

• Use a domain-specific attribute
• Set error.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[3] server.port: if the port is supported by the network transport used for communication.

[4] 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.

[5] 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.

[6] 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.

[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.method: This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The code.function.name attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).

[11] rpc.service: This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The code.namespace attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).

[12] rpc.grpc.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.grpc.request.metadata.my-custom-key attribute with value ["1.2.3.4", "1.2.3.5"]

[13] rpc.grpc.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.grpc.response.metadata.my-custom-key attribute with value ["attribute_value"]

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

rpc.grpc.status_code 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
0	OK
1	CANCELLED
2	UNKNOWN
3	INVALID_ARGUMENT
4	DEADLINE_EXCEEDED
5	NOT_FOUND
6	ALREADY_EXISTS
7	PERMISSION_DENIED
8	RESOURCE_EXHAUSTED
9	FAILED_PRECONDITION
10	ABORTED
11	OUT_OF_RANGE
12	UNIMPLEMENTED
13	INTERNAL
14	UNAVAILABLE
15	DATA_LOSS
16	UNAUTHENTICATED

gRPC Status

The table below describes when the Span Status MUST be set to Error or remain unset depending on the gRPC status code and Span Kind.