diff --git a/.chloggen/rpc-migration-doc.yaml b/.chloggen/rpc-migration-doc.yaml new file mode 100644 index 0000000000..8331274956 --- /dev/null +++ b/.chloggen/rpc-migration-doc.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: rpc + +note: Add RPC migration guide documenting changes from v1.37.0 to latest version. + +issues: [ 3204 ] diff --git a/docs/non-normative/rpc-migration.md b/docs/non-normative/rpc-migration.md new file mode 100644 index 0000000000..54e36dc5f9 --- /dev/null +++ b/docs/non-normative/rpc-migration.md @@ -0,0 +1,188 @@ + + +# RPC semantic convention stability migration guide + +> [!WARNING] +> This document is a work in progress as the RPC semantic conventions +> have not been marked stable yet and changes are still being made. + +Due to the significant number of modifications and the extensive user base +affected by them, existing RPC instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable RPC semantic conventions. + +Specifically, when existing RPC instrumentations published by OpenTelemetry are +updated to the stable RPC semantic conventions, they: + +- SHOULD NOT change the version of the RPC conventions that they emit by + default in their existing major version. Conventions include (but are not + limited to) attributes, metric and span names, and unit of measure. +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `rpc` - emit the stable RPC conventions, and stop emitting + the old RPC conventions that the instrumentation emitted previously. + - `rpc/dup` - emit both the old and the stable RPC conventions, + allowing for a phased rollout of the stable semantic conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old RPC conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable RPC conventions. + +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + +## Summary of changes + +This section summarizes the changes made to the RPC semantic conventions +from +[v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/README.md) +to +TODO (latest). + +### RPC span attributes + + +| Change | PR | Comments | +| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `rpc.system` → `rpc.system.name` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176), [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203) | See [below](#rpcsystemname-values) for changes to the values, also now marked as sampling-relevant | +| `rpc.method` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223), [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203) | Now contains fully-qualified method name (e.g., `com.example.ExampleService/exampleMethod`), also now marked as sampling-relevant | +| `rpc.service` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | Removed, integrated into `rpc.method` | +| `network.type` | [#2857](https://github.com/open-telemetry/semantic-conventions/pull/2857) | Removed | +| `rpc.grpc.status_code` → `rpc.response.status_code` | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920) | Changed from int to string (e.g., `0` → `"OK"`) | +| `rpc.connect_rpc.error_code` → `rpc.response.status_code` | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920) | | +| `rpc.grpc.request.metadata.` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.request.metadata.` | +| `rpc.grpc.response.metadata.` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.response.metadata.` | +| `rpc.connect_rpc.request.metadata.` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.request.metadata.` | +| `rpc.connect_rpc.response.metadata.` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.response.metadata.` | +| `server.address` | [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203) | Now marked as sampling-relevant | +| `server.port` | [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203) | Now marked as sampling-relevant | +| New: `error.type` | [#2852](https://github.com/open-telemetry/semantic-conventions/pull/2852) | | +| New: `network.protocol.name` | [#2767](https://github.com/open-telemetry/semantic-conventions/pull/2767) | | +| New: `network.protocol.version` | [#2767](https://github.com/open-telemetry/semantic-conventions/pull/2767) | | +| New: `rpc.method_original` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | Original method name when `rpc.method` is set to `_OTHER` | + + +References: + +- [RPC spans v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md) +- [RPC spans (TODO)](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-spans.md) + +### `rpc.system.name` values + + +| Change | PR | Comments | +| --------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ | +| `apache_dubbo` → `dubbo` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | | +| `connect_rpc` → `connectrpc` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | | +| `java_rmi` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | Removed, but can still be used as a custom value | +| `dotnet_wcf` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | Removed, but can still be used as a custom value | +| New: `jsonrpc` | [#2503](https://github.com/open-telemetry/semantic-conventions/pull/2503) | | + + +References: + +- [RPC spans v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md) +- [RPC spans (TODO)](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-spans.md) + +### RPC server call duration metric + +Metric changes: + +- **Name**: `rpc.server.duration` → `rpc.server.call.duration` ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Unit**: `ms` → `s` ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Description**: `Measures the duration of inbound RPC.` → + `Measures the duration of inbound remote procedure calls (RPC).` ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Histogram buckets**: boundaries updated to reflect change from milliseconds + to seconds ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Requirement level**: Made required ([#3284](https://github.com/open-telemetry/semantic-conventions/pull/3284)) +- **Attributes**: see table below + + +| Attribute change | PR | Comments | +| ------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| `rpc.system` → `rpc.system.name` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | See [above](#rpcsystemname-values) for changes to the values | +| `rpc.method` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | Now contains fully-qualified method name (e.g., `com.example.ExampleService/exampleMethod`) | +| `rpc.service` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | Removed, integrated into `rpc.method` | +| `network.type` | [#2857](https://github.com/open-telemetry/semantic-conventions/pull/2857) | Removed | +| `server.address` | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | Changed from Recommended to Opt-In | +| `server.port` | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | Changed from Recommended to Opt-In | +| New: `rpc.response.status_code` | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920) | | +| New: `error.type` | [#2852](https://github.com/open-telemetry/semantic-conventions/pull/2852) | | +| New: `network.protocol.name` | [#2767](https://github.com/open-telemetry/semantic-conventions/pull/2767) | | +| New: `network.protocol.version` | [#2767](https://github.com/open-telemetry/semantic-conventions/pull/2767) | | + + +References: + +- [Metric `rpc.server.duration` v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-metrics.md#metric-rpcserverduration) +- [Metric `rpc.server.call.duration` (TODO)](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#metric-rpcservercallduration) + +### RPC client call duration metric + +Metric changes: + +- **Name**: `rpc.client.duration` → `rpc.client.call.duration` ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Unit**: `ms` → `s` ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Description**: `Measures the duration of outbound RPC.` → + `Measures the duration of outbound remote procedure calls (RPC).` ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Histogram buckets**: boundaries updated to reflect change from milliseconds + to seconds ([#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)) +- **Requirement level**: Made required ([#3284](https://github.com/open-telemetry/semantic-conventions/pull/3284)) +- **Attributes**: see table below + + +| Attribute change | PR | Comments | +| ------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| `rpc.system` → `rpc.system.name` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | See [above](#rpcsystemname-values) for changes to the values | +| `rpc.method` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | Now contains fully-qualified method name (e.g., `com.example.ExampleService/exampleMethod`) | +| `rpc.service` | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | Removed, integrated into `rpc.method` | +| `network.type` | [#2857](https://github.com/open-telemetry/semantic-conventions/pull/2857) | Removed | +| `server.address` | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | Changed from Recommended to Required | +| `server.port` | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | Changed from Recommended to Conditionally Required | +| New: `rpc.response.status_code` | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920) | | +| New: `error.type` | [#2852](https://github.com/open-telemetry/semantic-conventions/pull/2852) | | +| New: `network.protocol.name` | [#2767](https://github.com/open-telemetry/semantic-conventions/pull/2767) | | +| New: `network.protocol.version` | [#2767](https://github.com/open-telemetry/semantic-conventions/pull/2767) | | + + +References: + +- [Metric `rpc.client.duration` v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-metrics.md#metric-rpcclientduration) +- [Metric `rpc.client.call.duration` (TODO)](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#metric-rpcclientcallduration) + +### Deprecated events + +The `rpc.message` event and its associated attributes have been deprecated with no replacement: + + +| Deprecated Event/Attribute | PR | +| ------------------------------ | ------------------------------------------------------------------------- | +| `rpc.message` event | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) | +| `rpc.message.type` | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) | +| `rpc.message.id` | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) | +| `rpc.message.compressed_size` | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) | +| `rpc.message.uncompressed_size`| [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) | + + +### Deprecated metrics + +The following metrics have been deprecated with no replacement: + + +| Deprecated Metric | PR | +| ------------------------------ | ------------------------------------------------------------------------- | +| `rpc.server.requests_per_rpc` | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) | +| `rpc.server.responses_per_rpc` | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) | +| `rpc.client.requests_per_rpc` | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) | +| `rpc.client.responses_per_rpc` | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) | +| `rpc.server.request.size` | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) | +| `rpc.server.response.size` | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) | +| `rpc.client.request.size` | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) | +| `rpc.client.response.size` | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) | +