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.

gRPC Attributes

rpc.system MUST be set to "grpc".

Below is a table of attributes that SHOULD be included on client and server gRPC measurements.

Attribute	Type	Description	Examples	Requirement Level	Stability
rpc.grpc.status_code	int	The numeric status code of the gRPC request.	0; 1; 2	Required
rpc.grpc.request.metadata.<key>	string[]	gRPC request metadata, <key> being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [1]	rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]	Opt-In
rpc.grpc.response.metadata.<key>	string[]	gRPC response metadata, <key> being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [2]	rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]	Opt-In

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

[2] rpc.grpc.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.

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.