Skip to content

Commit 8690be7

Browse files
AlexanderWertAlexanderWert
authored
Moved RPC semantic conventions (open-telemetry#145)
1 parent 676d53a commit 8690be7

File tree

11 files changed

+412
-452
lines changed

11 files changed

+412
-452
lines changed

‎specification/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Semantic Conventions are defined for the following areas:
1212
* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
1313
* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
1414
* [Database](database/README.md): Semantic Conventions for database operations.
15+
* [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations.
1516
* [System](system/README.md): System Semantic Conventions.
1617
* *Other areas can be found in the signal specific Semantic Conventions below*
1718

‎specification/cloud-providers/aws-sdk.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ with the naming guidelines for RPC client spans.
2323
| Attribute | Type | Description | Examples | Requirement Level |
2424
|---|---|---|---|---|
2525
| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended |
26-
| [`rpc.method`](../trace/semantic_conventions/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended |
27-
| [`rpc.service`](../trace/semantic_conventions/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended |
28-
| [`rpc.system`](../trace/semantic_conventions/rpc.md) | string | The value `aws-api`. | `aws-api` | Required |
26+
| [`rpc.method`](../rpc/rpc-spans.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended |
27+
| [`rpc.service`](../rpc/rpc-spans.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended |
28+
| [`rpc.system`](../rpc/rpc-spans.md) | string | The value `aws-api`. | `aws-api` | Required |
2929

3030
**[1]:** 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` 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).
3131

‎specification/general/metrics-general.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
The following semantic conventions surrounding metrics are defined:
2121

2222
* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics.
23-
* [RPC](/specification/metrics/semantic_conventions/rpc-metrics.md): For RPC client and server metrics.
23+
* [RPC](/specification/rpc/rpc-metrics.md): For RPC client and server metrics.
2424
* [Database](/specification/database/database-metrics.md): For SQL and NoSQL client metrics.
2525
* [FaaS](/specification/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics.
2626
* **System metrics**

‎specification/general/trace-general.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ The following semantic conventions for spans are defined:
1818
* [General](general-attributes.md): General semantic attributes that may be used in describing different kinds of operations.
1919
* [HTTP](/specification/http/http-spans.md): For HTTP client and server spans.
2020
* [Database](/specification/database/database-spans.md): For SQL and NoSQL client call spans.
21-
* [RPC/RMI](/specification/trace/semantic_conventions/rpc.md): For remote procedure call (e.g., gRPC) spans.
21+
* [RPC/RMI](/specification/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans.
2222
* [Messaging](/specification/trace/semantic_conventions/messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans.
2323
* [FaaS](/specification/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans.
2424
* [Exceptions](/specification/exceptions/exceptions-spans.md): For recording exceptions associated with a span.

‎specification/rpc/README.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Semantic conventions for RPC
2+
3+
**Status**: [Experimental][DocumentStatus]
4+
5+
This document defines semantic conventions for remote procedure calls (RPC)
6+
, also called "remote method invocations" (RMI).
7+
8+
Semantic conventions for RPC are defined for the following signals:
9+
10+
* [RPC Spans](rpc-spans.md): Semantic Conventions for RPC client and server *spans*.
11+
* [RPC Metrics](rpc-metrics.md): Semantic Conventions for RPC *metrics*.
12+
13+
Technology specific semantic conventions are defined for the following RPC systems:
14+
15+
* [Connect](connect-rpc.md): Semantic Conventions for *Connect RPC*.
16+
* [gRPC](grpc.md): Semantic Conventions for *gRPC*.
17+
* [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
18+
19+
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

‎specification/rpc/connect-rpc.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Semantic Conventions for Connect RPC
2+
3+
**Status**: [Experimental][DocumentStatus]
4+
5+
The Semantic Conventions for [Connect](http://connect.build) extend and override the [RPC spans](rpc-spans.md) and [RPC metrics](rpc-metrics.md) Semantic Conventions
6+
that describe common RPC operations attributes in addition to the Semantic Conventions
7+
described on this page.
8+
9+
## Connect RPC Attributes
10+
11+
`rpc.system` MUST be set to `"connect_rpc"`.
12+
13+
Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements.
14+
15+
<!-- semconv rpc.connect_rpc -->
16+
| Attribute | Type | Description | Examples | Requirement Level |
17+
|---|---|---|---|---|
18+
| `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] |
19+
20+
**[1]:** If response is not successful and if error code available.
21+
22+
`rpc.connect_rpc.error_code` MUST be one of the following:
23+
24+
| Value | Description |
25+
|---|---|
26+
| `cancelled` | cancelled |
27+
| `unknown` | unknown |
28+
| `invalid_argument` | invalid_argument |
29+
| `deadline_exceeded` | deadline_exceeded |
30+
| `not_found` | not_found |
31+
| `already_exists` | already_exists |
32+
| `permission_denied` | permission_denied |
33+
| `resource_exhausted` | resource_exhausted |
34+
| `failed_precondition` | failed_precondition |
35+
| `aborted` | aborted |
36+
| `out_of_range` | out_of_range |
37+
| `unimplemented` | unimplemented |
38+
| `internal` | internal |
39+
| `unavailable` | unavailable |
40+
| `data_loss` | data_loss |
41+
| `unauthenticated` | unauthenticated |
42+
<!-- endsemconv -->
43+
44+
## Connect RPC Status
45+
46+
If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases.
47+
48+
## Connect RPC Request and Response Metadata
49+
50+
| Attribute | Type | Description | Examples | Requirement Level |
51+
|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
52+
| `rpc.connect_rpc.request.metadata.<key>` | string[] | Connect request metadata, `<key>` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional |
53+
| `rpc.connect_rpc.response.metadata.<key>` | string[] | Connect response metadata, `<key>` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional |
54+
55+
**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
56+
Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
57+
58+
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

‎specification/rpc/grpc.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Semantic Conventions for gRPC
2+
3+
**Status**: [Experimental][DocumentStatus]
4+
5+
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
6+
that describe common RPC operations attributes in addition to the Semantic Conventions
7+
described on this page.
8+
9+
## gRPC Attributes
10+
11+
`rpc.system` MUST be set to `"grpc"`.
12+
13+
Below is a table of attributes that SHOULD be included on client and server gRPC measurements.
14+
15+
<!-- semconv rpc.grpc -->
16+
| Attribute | Type | Description | Examples | Requirement Level |
17+
|---|---|---|---|---|
18+
| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required |
19+
20+
`rpc.grpc.status_code` MUST be one of the following:
21+
22+
| Value | Description |
23+
|---|---|
24+
| `0` | OK |
25+
| `1` | CANCELLED |
26+
| `2` | UNKNOWN |
27+
| `3` | INVALID_ARGUMENT |
28+
| `4` | DEADLINE_EXCEEDED |
29+
| `5` | NOT_FOUND |
30+
| `6` | ALREADY_EXISTS |
31+
| `7` | PERMISSION_DENIED |
32+
| `8` | RESOURCE_EXHAUSTED |
33+
| `9` | FAILED_PRECONDITION |
34+
| `10` | ABORTED |
35+
| `11` | OUT_OF_RANGE |
36+
| `12` | UNIMPLEMENTED |
37+
| `13` | INTERNAL |
38+
| `14` | UNAVAILABLE |
39+
| `15` | DATA_LOSS |
40+
| `16` | UNAUTHENTICATED |
41+
<!-- endsemconv -->
42+
43+
## gRPC Status
44+
45+
The table below describes when
46+
the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#set-status) MUST be set
47+
to `Error` or remain unset
48+
depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md)
49+
and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/trace/api.md#spankind).
50+
51+
| gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status |
52+
|---|---|---|
53+
| OK | unset | unset |
54+
| CANCELLED | unset | `Error` |
55+
| UNKNOWN | `Error` | `Error` |
56+
| INVALID_ARGUMENT | unset | `Error` |
57+
| DEADLINE_EXCEEDED | `Error` | `Error` |
58+
| NOT_FOUND | unset | `Error` |
59+
| ALREADY_EXISTS | unset | `Error` |
60+
| PERMISSION_DENIED | unset | `Error` |
61+
| RESOURCE_EXHAUSTED | unset| `Error` |
62+
| FAILED_PRECONDITION | unset | `Error` |
63+
| ABORTED | unset | `Error` |
64+
| OUT_OF_RANGE | unset | `Error` |
65+
| UNIMPLEMENTED | `Error` | `Error` |
66+
| INTERNAL | `Error` | `Error` |
67+
| UNAVAILABLE | `Error` | `Error` |
68+
| DATA_LOSS | `Error` | `Error` |
69+
| UNAUTHENTICATED | unset | `Error` |
70+
71+
## gRPC Request and Response Metadata
72+
73+
| Attribute | Type | Description | Examples | Requirement Level |
74+
|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
75+
| `rpc.grpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), 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 |
76+
| `rpc.grpc.response.metadata.<key>` | string[] | gRPC response metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In |
77+
78+
**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
79+
Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
80+
81+
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

‎specification/rpc/json-rpc.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Semantic Conventions for gRPC
2+
3+
**Status**: [Experimental][DocumentStatus]
4+
5+
The Semantic Conventions for [JSON-RPC](https://www.jsonrpc.org/) extend and override the [RPC spans](rpc-spans.md) and [RPC metrics](rpc-metrics.md) Semantic Conventions
6+
that describe common RPC operations attributes in addition to the Semantic Conventions
7+
described on this page.
8+
9+
## JSON RPC Attributes
10+
11+
`rpc.system` MUST be set to `"jsonrpc"`.
12+
13+
<!-- semconv rpc.jsonrpc -->
14+
| Attribute | Type | Description | Examples | Requirement Level |
15+
|---|---|---|---|---|
16+
| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) |
17+
| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended |
18+
| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. |
19+
| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended |
20+
| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required |
21+
22+
**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.
23+
<!-- endsemconv -->
24+
25+
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

0 commit comments

Comments
 (0)