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.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
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 |
rpc.grpc.status_code | int | The numeric status code of the gRPC request. | 0 | Required |
[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 MUST be one of the following:
| Value | Description |
|---|---|
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.
| gRPC Status Code | SpanKind.SERVER Span Status | SpanKind.CLIENT Span Status |
|---|---|---|
| OK | unset | unset |
| CANCELLED | unset | Error |
| UNKNOWN | Error | Error |
| INVALID_ARGUMENT | unset | Error |
| DEADLINE_EXCEEDED | Error | Error |
| NOT_FOUND | unset | Error |
| ALREADY_EXISTS | unset | Error |
| PERMISSION_DENIED | unset | Error |
| RESOURCE_EXHAUSTED | unset | Error |
| FAILED_PRECONDITION | unset | Error |
| ABORTED | unset | Error |
| OUT_OF_RANGE | unset | Error |
| UNIMPLEMENTED | Error | Error |
| INTERNAL | Error | Error |
| UNAVAILABLE | Error | Error |
| DATA_LOSS | Error | Error |
| UNAUTHENTICATED | unset | Error |