Add Connect RPC to semantic conventions (open-telemetry#3116)

* Add connect_rpc to rpc.yaml * Add connect rpc into rpc-metrics and rpc markdown * Add Connect RPC change to CHANGELOG.md * Update CHANGELOG.md --------- Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
jsuereth · Feb 28, 2023 · 831a045 · 831a045
1 parent 77137f0
commit 831a045
Show file tree

Hide file tree

Showing 4 changed files with 150 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -28,6 +28,8 @@ release.
   ([#3209](https://github.com/open-telemetry/opentelemetry-specification/pull/3209))
 - BREAKING: Change faas.max_memory units to Bytes instead of MB
   ([#3209](https://github.com/open-telemetry/opentelemetry-specification/pull/3209))
+- Add Connect RPC specific conventions
+  ([#3116](https://github.com/open-telemetry/opentelemetry-specification/pull/3116))
 
 ### Compatibility
 

diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml
@@ -23,6 +23,9 @@ groups:
             - id: apache_dubbo
               value: 'apache_dubbo'
               brief: 'Apache Dubbo'
+            - id: connect_rpc
+              value: 'connect_rpc'
+              brief: 'Connect RPC'
       - id: service
         type: string
         requirement_level: recommended
@@ -210,3 +213,48 @@ groups:
       - id: uncompressed_size
         type: int
         brief: "Uncompressed size of the message in bytes."
+
+  - id: rpc.connect_rpc
+    prefix: rpc.connect_rpc
+    type: span
+    extends: rpc
+    brief: 'Tech-specific attributes for Connect RPC.'
+    attributes:
+      - id: error_code
+        type:
+          members:
+            - id: cancelled
+              value: cancelled
+            - id: unknown
+              value: unknown
+            - id: invalid_argument
+              value: invalid_argument
+            - id: deadline_exceeded
+              value: deadline_exceeded
+            - id: not_found
+              value: not_found
+            - id: already_exists
+              value: already_exists
+            - id: permission_denied
+              value: permission_denied
+            - id: resource_exhausted
+              value: resource_exhausted
+            - id: failed_precondition
+              value: failed_precondition
+            - id: aborted
+              value: aborted
+            - id: out_of_range
+              value: out_of_range
+            - id: unimplemented
+              value: unimplemented
+            - id: internal
+              value: internal
+            - id: unavailable
+              value: unavailable
+            - id: data_loss
+              value: data_loss
+            - id: unauthenticated
+              value: unauthenticated
+        requirement_level:
+          conditionally_required: If response is not successful and if error code available.
+        brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values."
diff --git a/specification/metrics/semantic_conventions/rpc-metrics.md b/specification/metrics/semantic_conventions/rpc-metrics.md
@@ -23,6 +23,8 @@ metrics can be filtered for finer grain analysis.
   * [Service name](#service-name)
 - [gRPC conventions](#grpc-conventions)
   * [gRPC Attributes](#grpc-attributes)
+- [Connect RPC conventions](#connect-rpc-conventions)
+  * [Connect RPC Attributes](#connect-rpc-attributes)
 
 <!-- tocstop -->
 
@@ -100,6 +102,7 @@ measurements.
 | `java_rmi` | Java RMI |
 | `dotnet_wcf` | .NET WCF |
 | `apache_dubbo` | Apache Dubbo |
+| `connect_rpc` | Connect RPC |
 <!-- endsemconv -->
 
 To avoid high cardinality, implementations should prefer the most stable of `net.peer.name` or
@@ -158,3 +161,42 @@ Below is a table of attributes that SHOULD be included on client and server RPC
 <!-- endsemconv -->
 
 [gRPC]: https://grpc.io/
+
+## Connect RPC conventions
+
+For remote procedure calls via [connect](http://connect.build), additional conventions are described in this section.
+
+`rpc.system` MUST be set to `"connect_rpc"`.
+
+### Connect RPC Attributes
+
+Below is a table of attributes that SHOULD be included on client and server RPC measurements when `rpc.system` is `"connect_rpc"`.
+
+<!-- semconv rpc.connect_rpc -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`rpc.connect_rpc.error_code`](../../trace/semantic_conventions/rpc.md) | 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 -->
diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md
@@ -20,6 +20,10 @@ This document defines how to describe remote procedure calls
   * [gRPC Attributes](#grpc-attributes)
   * [gRPC Status](#grpc-status)
   * [gRPC Request and Response Metadata](#grpc-request-and-response-metadata)
+- [Connect RPC conventions](#connect-rpc-conventions)
+  * [Connect RPC Attributes](#connect-rpc-attributes)
+  * [Connect RPC Status](#connect-rpc-status)
+  * [Connect RPC Request and Response Metadata](#connect-rpc-request-and-response-metadata)
 - [JSON RPC](#json-rpc)
   * [JSON RPC Attributes](#json-rpc-attributes)
 
@@ -92,6 +96,7 @@ Examples of span names:
 | `java_rmi` | Java RMI |
 | `dotnet_wcf` | .NET WCF |
 | `apache_dubbo` | Apache Dubbo |
+| `connect_rpc` | Connect RPC |
 <!-- endsemconv -->
 
 For client-side spans `net.peer.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).
@@ -213,6 +218,59 @@ The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC stat
 **[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.
 
+## Connect RPC conventions
+
+For remote procedure calls via [connect](http://connect.build), additional conventions are described in this section.
+
+`rpc.system` MUST be set to `"connect_rpc"`.
+
+### Connect RPC Attributes
+
+Below is a table of attributes that SHOULD be included on client and server RPC measurements when `rpc.system` is `"connect_rpc"`.
+
+<!-- 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](../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.
+
 ## JSON RPC
 
 Conventions specific to [JSON RPC](https://www.jsonrpc.org/).