open-telemetry · reyang · Jul 3, 2023 · Jul 1, 2023
@@ -12,6 +12,7 @@ Semantic Conventions are defined for the following areas:
 * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
 * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
 * [Database](database/README.md): Semantic Conventions for database operations.
+* [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations.
 * [System](system/README.md): System Semantic Conventions.
 * *Other areas can be found in the signal specific Semantic Conventions below*
 

@@ -23,9 +23,9 @@ with the naming guidelines for RPC client spans.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `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 |
-| [`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 |
-| [`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 |
-| [`rpc.system`](../trace/semantic_conventions/rpc.md) | string | The value `aws-api`. | `aws-api` | Required |
+| [`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 |
+| [`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 |
+| [`rpc.system`](../rpc/rpc-spans.md) | string | The value `aws-api`. | `aws-api` | Required |
 
 **[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).
 

@@ -20,7 +20,7 @@
 The following semantic conventions surrounding metrics are defined:
 
 * [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics.
-* [RPC](/specification/metrics/semantic_conventions/rpc-metrics.md): For RPC client and server metrics.
+* [RPC](/specification/rpc/rpc-metrics.md): For RPC client and server metrics.
 * [Database](/specification/database/database-metrics.md): For SQL and NoSQL client metrics.
 * [FaaS](/specification/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics.
 * **System metrics**

@@ -18,7 +18,7 @@ The following semantic conventions for spans are defined:
 * [General](general-attributes.md): General semantic attributes that may be used in describing different kinds of operations.
 * [HTTP](/specification/http/http-spans.md): For HTTP client and server spans.
 * [Database](/specification/database/database-spans.md): For SQL and NoSQL client call spans.
-* [RPC/RMI](/specification/trace/semantic_conventions/rpc.md): For remote procedure call (e.g., gRPC) spans.
+* [RPC/RMI](/specification/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans.
 * [Messaging](/specification/trace/semantic_conventions/messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans.
 * [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.
 * [Exceptions](/specification/exceptions/exceptions-spans.md): For recording exceptions associated with a span.

@@ -0,0 +1,19 @@
+# Semantic conventions for RPC
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for remote procedure calls (RPC)
+, also called "remote method invocations" (RMI).
+
+Semantic conventions for RPC are defined for the following signals:
+
+* [RPC Spans](rpc-spans.md): Semantic Conventions for RPC client and server *spans*.
+* [RPC Metrics](rpc-metrics.md): Semantic Conventions for RPC *metrics*.
+
+Technology specific semantic conventions are defined for the following RPC systems:
+
+* [Connect](connect-rpc.md): Semantic Conventions for *Connect RPC*.
+* [gRPC](grpc.md): Semantic Conventions for *gRPC*.
+* [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
@@ -0,0 +1,58 @@
+# Semantic Conventions for Connect RPC
+
+**Status**: [Experimental][DocumentStatus]
+
+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
+that describe common RPC operations attributes in addition to the Semantic Conventions
+described on this page.
+
+## Connect RPC Attributes
+
+`rpc.system` MUST be set to `"connect_rpc"`.
+
+Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements.
+
+<!-- semconv rpc.connect_rpc -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `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] |
+
+**[1]:** If response is not successful and if error code available.
+
+`rpc.connect_rpc.error_code` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `cancelled` | cancelled |
+| `unknown` | unknown |
+| `invalid_argument` | invalid_argument |
+| `deadline_exceeded` | deadline_exceeded |
+| `not_found` | not_found |
+| `already_exists` | already_exists |
+| `permission_denied` | permission_denied |
+| `resource_exhausted` | resource_exhausted |
+| `failed_precondition` | failed_precondition |
+| `aborted` | aborted |
+| `out_of_range` | out_of_range |
+| `unimplemented` | unimplemented |
+| `internal` | internal |
+| `unavailable` | unavailable |
+| `data_loss` | data_loss |
+| `unauthenticated` | unauthenticated |
+<!-- endsemconv -->
+
+## Connect RPC Status
+
+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.
+
+## Connect RPC Request and Response Metadata
+
+| Attribute                                 | Type     | Description                                                                                                                                                             | Examples                                                                   | Requirement Level |
+|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
+| `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          |
+| `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          |
+
+**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
+Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
@@ -0,0 +1,81 @@
+# 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 rpc.grpc -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `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 |
+
+`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 |
+<!-- endsemconv -->
+
+## gRPC Status
+
+The table below describes when
+the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.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.21.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` |
+
+## gRPC Request and Response Metadata
+
+| Attribute                     | Type     | Description                                                                                                                                                       | Examples                                                                   | Requirement Level |
+|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
+| `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            |
+| `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            |
+
+**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
+Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md
@@ -0,0 +1,25 @@
+# Semantic Conventions for gRPC
+
+**Status**: [Experimental][DocumentStatus]
+
+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
+that describe common RPC operations attributes in addition to the Semantic Conventions
+described on this page.
+
+## JSON RPC Attributes
+
+`rpc.system` MUST be set to `"jsonrpc"`.
+
+<!-- semconv rpc.jsonrpc -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `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`) |
+| `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 |
+| `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. |
+| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended |
+| [`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 |
+
+**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md