From 74454cda08b5b6d60fe32568cdee0398dcc3a009 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Thu, 4 Jan 2024 02:29:56 +0000 Subject: [PATCH 1/9] Link to proposal for gRPC metrics --- docs/rpc/grpc.md | 81 ----------------------------------------- docs/rpc/rpc-metrics.md | 6 +-- 2 files changed, 3 insertions(+), 84 deletions(-) delete mode 100644 docs/rpc/grpc.md diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md deleted file mode 100644 index 100f17dc4b..0000000000 --- a/docs/rpc/grpc.md +++ /dev/null @@ -1,81 +0,0 @@ - - -# 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. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`rpc.grpc.request.metadata.`](../attributes-registry/rpc.md) | string[] | gRPC request metadata, `` 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.`](../attributes-registry/rpc.md) | string[] | gRPC response metadata, `` 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 | -| [`rpc.grpc.status_code`](../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` | Required | - -**[1]:** 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]:** 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` 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 | - - -## gRPC Status - -The table below describes when -the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.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.26.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://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 106e2e6c4a..72e4775601 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,6 +61,8 @@ metrics can be filtered for finer grain analysis. > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. +Maintainers of gRPC have decided to create a different [spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to limitations on what information can be recorded by the various implementations of gRPC and differences in concepts such as a `call` and an `attempt` compared to other RPC systems. + ## Metric instruments The following metric instruments MUST be used to describe RPC operations. They @@ -223,7 +225,7 @@ measurements. | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | | [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `connect_rpc` | Required | | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | @@ -263,7 +265,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | |---|---| -| `grpc` | gRPC | | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | @@ -285,7 +286,6 @@ One process can expose multiple RPC endpoints and thus have multiple RPC service More specific Semantic Conventions are defined for the following RPC technologies: * [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/tree/v1.26.0/specification/document-status.md From d911230316ced35490dddd2fccfc36866b9d2db3 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Thu, 4 Jan 2024 02:39:15 +0000 Subject: [PATCH 2/9] Update CHANGELOG.md and cleanup --- CHANGELOG.md | 2 ++ docs/rpc/rpc-metrics.md | 6 +++- model/registry/rpc.yaml | 74 ----------------------------------------- 3 files changed, 7 insertions(+), 75 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b62c84eb6..1bfddb6557 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ release. - Rename `system.processes.*` namespace to `system.process.*` ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) +- Link to proposal for gRPC metrics + ([#627](https://github.com/open-telemetry/semantic-conventions/pull/627)) ### Features diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 72e4775601..53a41fa1a2 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,7 +61,11 @@ metrics can be filtered for finer grain analysis. > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. -Maintainers of gRPC have decided to create a different [spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to limitations on what information can be recorded by the various implementations of gRPC and differences in concepts such as a `call` and an `attempt` compared to other RPC systems. +Maintainers of gRPC have decided to create a different +[spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to +limitations on what information can be recorded by the various implementations +of gRPC and differences in concepts such as a `call` and an `attempt` compared +to other RPC systems. ## Metric instruments diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index 64f1f9a667..91c37ea23c 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -56,77 +56,6 @@ groups: 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. examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] - - id: grpc.status_code - type: - members: - - id: ok - brief: OK - value: 0 - - id: cancelled - brief: CANCELLED - value: 1 - - id: unknown - brief: UNKNOWN - value: 2 - - id: invalid_argument - brief: INVALID_ARGUMENT - value: 3 - - id: deadline_exceeded - brief: DEADLINE_EXCEEDED - value: 4 - - id: not_found - brief: NOT_FOUND - value: 5 - - id: already_exists - brief: ALREADY_EXISTS - value: 6 - - id: permission_denied - brief: PERMISSION_DENIED - value: 7 - - id: resource_exhausted - brief: RESOURCE_EXHAUSTED - value: 8 - - id: failed_precondition - brief: FAILED_PRECONDITION - value: 9 - - id: aborted - brief: ABORTED - value: 10 - - id: out_of_range - brief: OUT_OF_RANGE - value: 11 - - id: unimplemented - brief: UNIMPLEMENTED - value: 12 - - id: internal - brief: INTERNAL - value: 13 - - id: unavailable - brief: UNAVAILABLE - value: 14 - - id: data_loss - brief: DATA_LOSS - value: 15 - - id: unauthenticated - brief: UNAUTHENTICATED - value: 16 - brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." - - id: grpc.request.metadata - type: template[string[]] - brief: > - gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. - note: > - 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. - examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] - - id: grpc.response.metadata - type: template[string[]] - brief: > - gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. - note: > - 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. - examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] - id: jsonrpc.error_code type: int brief: "`error.code` property of response if it is an error response." @@ -173,9 +102,6 @@ groups: type: allow_custom_values: true members: - - id: grpc - value: 'grpc' - brief: 'gRPC' - id: java_rmi value: 'java_rmi' brief: 'Java RMI' From 476e5bb66ab0e8af7abd7bdb6d58ae445ac17e43 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 30 Jan 2024 01:13:51 +0000 Subject: [PATCH 3/9] Formatting --- docs/rpc/README.md | 5 ++++- docs/rpc/rpc-metrics.md | 15 ++++++++++----- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/rpc/README.md b/docs/rpc/README.md index c7810685b4..a30f41d372 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -20,7 +20,10 @@ Semantic conventions for RPC are defined for the following signals: 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*. +Specifications defined by maintainers of RPC systems: + +* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*. + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 53a41fa1a2..e5ca8bf191 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,11 +61,12 @@ metrics can be filtered for finer grain analysis. > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. -Maintainers of gRPC have decided to create a different -[spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to -limitations on what information can be recorded by the various implementations -of gRPC and differences in concepts such as a `call` and an `attempt` compared -to other RPC systems. +> [!NOTE] +> Maintainers of gRPC have decided to create a different +> [spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to +> limitations on what information can be recorded by the various implementations +> of gRPC and differences in concepts such as a `call` and an `attempt` compared +> to other RPC systems. ## Metric instruments @@ -292,5 +293,9 @@ More specific Semantic Conventions are defined for the following RPC technologie * [Connect](connect-rpc.md): Semantic Conventions for *Connect RPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. +Specifications defined by maintainers of RPC systems: + +* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*. + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md [MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended From 389d8d3eab1863373e5e9955dd6c9cd892f98ef9 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 30 Jan 2024 01:22:47 +0000 Subject: [PATCH 4/9] Revert changes to grpc.md --- docs/rpc/grpc.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/rpc/grpc.md diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md new file mode 100644 index 0000000000..100f17dc4b --- /dev/null +++ b/docs/rpc/grpc.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. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`rpc.grpc.request.metadata.`](../attributes-registry/rpc.md) | string[] | gRPC request metadata, `` 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.`](../attributes-registry/rpc.md) | string[] | gRPC response metadata, `` 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 | +| [`rpc.grpc.status_code`](../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` | Required | + +**[1]:** 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]:** 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` 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 | + + +## gRPC Status + +The table below describes when +the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.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.26.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://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md From e763c850d9ef427e44589f5caf0b5e55366413d0 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 30 Jan 2024 01:26:55 +0000 Subject: [PATCH 5/9] Revert changes to model --- model/registry/rpc.yaml | 74 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index 91c37ea23c..64f1f9a667 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -56,6 +56,77 @@ groups: 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. examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: grpc.status_code + type: + members: + - id: ok + brief: OK + value: 0 + - id: cancelled + brief: CANCELLED + value: 1 + - id: unknown + brief: UNKNOWN + value: 2 + - id: invalid_argument + brief: INVALID_ARGUMENT + value: 3 + - id: deadline_exceeded + brief: DEADLINE_EXCEEDED + value: 4 + - id: not_found + brief: NOT_FOUND + value: 5 + - id: already_exists + brief: ALREADY_EXISTS + value: 6 + - id: permission_denied + brief: PERMISSION_DENIED + value: 7 + - id: resource_exhausted + brief: RESOURCE_EXHAUSTED + value: 8 + - id: failed_precondition + brief: FAILED_PRECONDITION + value: 9 + - id: aborted + brief: ABORTED + value: 10 + - id: out_of_range + brief: OUT_OF_RANGE + value: 11 + - id: unimplemented + brief: UNIMPLEMENTED + value: 12 + - id: internal + brief: INTERNAL + value: 13 + - id: unavailable + brief: UNAVAILABLE + value: 14 + - id: data_loss + brief: DATA_LOSS + value: 15 + - id: unauthenticated + brief: UNAUTHENTICATED + value: 16 + brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: grpc.request.metadata + type: template[string[]] + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + 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. + examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: grpc.response.metadata + type: template[string[]] + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + 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. + examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] - id: jsonrpc.error_code type: int brief: "`error.code` property of response if it is an error response." @@ -102,6 +173,9 @@ groups: type: allow_custom_values: true members: + - id: grpc + value: 'grpc' + brief: 'gRPC' - id: java_rmi value: 'java_rmi' brief: 'Java RMI' From 932275ed5e2ff6003a0e49f79f29e615bc886190 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 30 Jan 2024 01:46:39 +0000 Subject: [PATCH 6/9] Following contribution guidelines --- CHANGELOG.md | 2 +- docs/attributes-registry/rpc.md | 3 +-- docs/rpc/rpc-metrics.md | 4 ++-- docs/rpc/rpc-spans.md | 3 +-- model/registry/rpc.yaml | 3 --- 5 files changed, 5 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index da12f12bb1..d4bfaed417 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,7 @@ release. - Rename attributes for `process.paging.faults` - `type` to `process.paging.fault_type` - Link to proposal for gRPC metrics - ([#627](https://github.com/open-telemetry/semantic-conventions/pull/627)) + ([#627](https://github.com/open-telemetry/semantic-conventions/pull/627)) ### Features diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md index fd112b1d2b..f348a5d6ab 100644 --- a/docs/attributes-registry/rpc.md +++ b/docs/attributes-registry/rpc.md @@ -22,7 +22,7 @@ RPC attributes are intended to be used in the context of events related to remot | `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [5] | `exampleMethod` | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` | -| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | +| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `java_rmi` | **[1]:** 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. @@ -83,7 +83,6 @@ RPC attributes are intended to be used in the context of events related to remot | Value | Description | |---|---| -| `grpc` | gRPC | | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index e5ca8bf191..2dc7f7efe2 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -60,7 +60,7 @@ metrics can be filtered for finer grain analysis. > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. - +> > [!NOTE] > Maintainers of gRPC have decided to create a different > [spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to @@ -230,7 +230,7 @@ measurements. | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | | [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `connect_rpc` | Required | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `java_rmi` | Required | | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c3a9554350..26dde428bd 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -88,7 +88,7 @@ Examples of span names: | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | | [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `java_rmi` | Required | | [`server.address`](../attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | @@ -130,7 +130,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | |---|---| -| `grpc` | gRPC | | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index 64f1f9a667..cae9fafbcc 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -173,9 +173,6 @@ groups: type: allow_custom_values: true members: - - id: grpc - value: 'grpc' - brief: 'gRPC' - id: java_rmi value: 'java_rmi' brief: 'Java RMI' From d49c1b454dd574c61e915495b90adbff063b4817 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 30 Jan 2024 01:50:47 +0000 Subject: [PATCH 7/9] Fix formatting --- docs/rpc/rpc-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 2dc7f7efe2..3836275cd2 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -61,7 +61,7 @@ metrics can be filtered for finer grain analysis. > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. > -> [!NOTE] +> **Note** > Maintainers of gRPC have decided to create a different > [spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to > limitations on what information can be recorded by the various implementations From eb773fecdf6c8f2dcb283ca664db5a718b54bcf9 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 20 Feb 2024 11:55:26 +0000 Subject: [PATCH 8/9] Revert breaking changes --- CHANGELOG.md | 2 -- docs/attributes-registry/rpc.md | 3 ++- docs/rpc/README.md | 1 + docs/rpc/rpc-metrics.md | 11 +++-------- docs/rpc/rpc-spans.md | 3 ++- model/registry/rpc.yaml | 3 +++ 6 files changed, 11 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d4bfaed417..86d2bb5ec2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,8 +29,6 @@ release. - `type` to `process.context_switch_type` - Rename attributes for `process.paging.faults` - `type` to `process.paging.fault_type` - - Link to proposal for gRPC metrics - ([#627](https://github.com/open-telemetry/semantic-conventions/pull/627)) ### Features diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md index f348a5d6ab..fd112b1d2b 100644 --- a/docs/attributes-registry/rpc.md +++ b/docs/attributes-registry/rpc.md @@ -22,7 +22,7 @@ RPC attributes are intended to be used in the context of events related to remot | `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [5] | `exampleMethod` | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` | -| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `java_rmi` | +| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | **[1]:** 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. @@ -83,6 +83,7 @@ RPC attributes are intended to be used in the context of events related to remot | Value | Description | |---|---| +| `grpc` | gRPC | | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | diff --git a/docs/rpc/README.md b/docs/rpc/README.md index a30f41d372..303e1f3145 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -20,6 +20,7 @@ Semantic conventions for RPC are defined for the following signals: 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*. Specifications defined by maintainers of RPC systems: diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 3836275cd2..1c4f96a00a 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -60,13 +60,6 @@ metrics can be filtered for finer grain analysis. > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. -> -> **Note** -> Maintainers of gRPC have decided to create a different -> [spec](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) due to -> limitations on what information can be recorded by the various implementations -> of gRPC and differences in concepts such as a `call` and an `attempt` compared -> to other RPC systems. ## Metric instruments @@ -230,7 +223,7 @@ measurements. | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | | [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `java_rmi` | Required | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | @@ -270,6 +263,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | |---|---| +| `grpc` | gRPC | | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | @@ -291,6 +285,7 @@ One process can expose multiple RPC endpoints and thus have multiple RPC service More specific Semantic Conventions are defined for the following RPC technologies: * [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*. Specifications defined by maintainers of RPC systems: diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 26dde428bd..c3a9554350 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -88,7 +88,7 @@ Examples of span names: | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | | [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `java_rmi` | Required | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`server.address`](../attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | @@ -130,6 +130,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Value | Description | |---|---| +| `grpc` | gRPC | | `java_rmi` | Java RMI | | `dotnet_wcf` | .NET WCF | | `apache_dubbo` | Apache Dubbo | diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index cae9fafbcc..64f1f9a667 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -173,6 +173,9 @@ groups: type: allow_custom_values: true members: + - id: grpc + value: 'grpc' + brief: 'gRPC' - id: java_rmi value: 'java_rmi' brief: 'Java RMI' From 7570de5a77e95994bef219e9348d27c3a4603168 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Fri, 22 Mar 2024 01:56:20 +0000 Subject: [PATCH 9/9] Add changelog --- .chloggen/627.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100755 .chloggen/627.yaml diff --git a/.chloggen/627.yaml b/.chloggen/627.yaml new file mode 100755 index 0000000000..1e96d83745 --- /dev/null +++ b/.chloggen/627.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: rpc + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add link to specification for metrics defined by gRPC community. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [627] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: