Semantic Conventions for gRPC

Status: Experimental

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.

AttributeTypeDescriptionExamplesRequirement LevelStability
rpc.grpc.status_codeintThe numeric status code of the gRPC request.0; 1; 2RequiredExperimental
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-InExperimental
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-InExperimental

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

ValueDescriptionStability
0OKExperimental
1CANCELLEDExperimental
2UNKNOWNExperimental
3INVALID_ARGUMENTExperimental
4DEADLINE_EXCEEDEDExperimental
5NOT_FOUNDExperimental
6ALREADY_EXISTSExperimental
7PERMISSION_DENIEDExperimental
8RESOURCE_EXHAUSTEDExperimental
9FAILED_PRECONDITIONExperimental
10ABORTEDExperimental
11OUT_OF_RANGEExperimental
12UNIMPLEMENTEDExperimental
13INTERNALExperimental
14UNAVAILABLEExperimental
15DATA_LOSSExperimental
16UNAUTHENTICATEDExperimental

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.

gRPC Status CodeSpanKind.SERVER Span StatusSpanKind.CLIENT Span Status
OKunsetunset
CANCELLEDunsetError
UNKNOWNErrorError
INVALID_ARGUMENTunsetError
DEADLINE_EXCEEDEDErrorError
NOT_FOUNDunsetError
ALREADY_EXISTSunsetError
PERMISSION_DENIEDunsetError
RESOURCE_EXHAUSTEDunsetError
FAILED_PRECONDITIONunsetError
ABORTEDunsetError
OUT_OF_RANGEunsetError
UNIMPLEMENTEDErrorError
INTERNALErrorError
UNAVAILABLEErrorError
DATA_LOSSErrorError
UNAUTHENTICATEDunsetError