-
Notifications
You must be signed in to change notification settings - Fork 183
/
grpc.md
93 lines (75 loc) · 5.59 KB
/
grpc.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
<!--- Hugo front matter used to generate the website version of this page:
linkTitle: gRPC
--->
# Semantic Conventions for gRPC
**Status**: [Experimental][DocumentStatus]
The Semantic Conventions for [gRPC](https://grpc.io/) extend and override the [RPC spans](rpc-spans.md) and [RPC metrics](rpc-metrics.md) 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.
<!-- semconv span.rpc.grpc(tag=grpc-tech-specific) -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`rpc.grpc.status_code`](/docs/attributes-registry/rpc.md) | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0`; `1`; `2` | `Required` |  |
| [`rpc.grpc.request.metadata.<key>`](/docs/attributes-registry/rpc.md) | 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>`](/docs/attributes-registry/rpc.md) | 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 |  |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
## gRPC Status
The table below describes when
the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set
to `Error` or remain unset
depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md)
and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#spankind).
| 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` |
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status