From ab30f520524b33c086430d98aa6020a3baac2a55 Mon Sep 17 00:00:00 2001 From: joshcarp Date: Thu, 19 Jan 2023 13:34:18 -0500 Subject: [PATCH 1/4] Add connect_rpc to rpc.yaml --- semantic_conventions/trace/rpc.yaml | 48 +++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index ecd6386d6c4..d1993312a92 100644 --- 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." From c43d462a6e7a5f6c534099011783327dbe3b275f Mon Sep 17 00:00:00 2001 From: joshcarp Date: Thu, 19 Jan 2023 13:45:09 -0500 Subject: [PATCH 2/4] Add connect rpc into rpc-metrics and rpc markdown --- .../semantic_conventions/rpc-metrics.md | 42 ++++++++++++++ .../trace/semantic_conventions/rpc.md | 58 +++++++++++++++++++ 2 files changed, 100 insertions(+) diff --git a/specification/metrics/semantic_conventions/rpc-metrics.md b/specification/metrics/semantic_conventions/rpc-metrics.md index ad5b8b87a73..6508a2af271 100644 --- 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) @@ -100,6 +102,7 @@ measurements. | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | +| `connect_rpc` | Connect RPC | 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 [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"`. + + +| 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 | + diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index c46a255dd1d..017ddd73062 100644 --- 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 | 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"`. + + +| 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 | + + +### 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.` | string[] | Connect request metadata, `` 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.` | string[] | Connect response metadata, `` 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/). From 99c331c6b2c87b87a762c5544c97b1acb6008dfe Mon Sep 17 00:00:00 2001 From: Joshua Carpeggiani <32605850+joshcarp@users.noreply.github.com> Date: Thu, 19 Jan 2023 13:59:53 -0500 Subject: [PATCH 3/4] Add Connect RPC change to CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 640bf155f37..c665b18bebe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ release. ### Resource ### Semantic Conventions +- Add Connect RPC specific conventions (#3116). ### Compatibility From 3a25559bc454506e6a5a2333d1249e1ac62fb83a Mon Sep 17 00:00:00 2001 From: Joshua Carpeggiani <32605850+joshcarp@users.noreply.github.com> Date: Thu, 19 Jan 2023 14:24:44 -0500 Subject: [PATCH 4/4] Update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c665b18bebe..62a1b0e3cd5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ release. ### Resource ### Semantic Conventions + - Add Connect RPC specific conventions (#3116). ### Compatibility