-
Notifications
You must be signed in to change notification settings - Fork 324
Add RPC migration doc #3224
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Add RPC migration doc #3224
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
413bf2b
Add RPC migration doc
trask 844ac4a
fix metric descriptions
trask d3f9296
Merge remote-tracking branch 'upstream/main' into rpc-migration-doc
trask dc7ec75
updates
trask d6cc2b9
More deprecated metrics
trask dc468b7
Merge remote-tracking branch 'upstream/main' into rpc-migration-doc
trask e055083
updates
trask File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 ] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,188 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| linkTitle: RPC migration | ||
| ---> | ||
|
|
||
| # 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 | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| | 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.<key>` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.request.metadata.<key>` | | ||
| | `rpc.grpc.response.metadata.<key>` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.response.metadata.<key>` | | ||
| | `rpc.connect_rpc.request.metadata.<key>` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.request.metadata.<key>` | | ||
| | `rpc.connect_rpc.response.metadata.<key>` | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169) | Replaced by `rpc.response.metadata.<key>` | | ||
| | `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` | | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| 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) | ||
trask marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### `rpc.system.name` values | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| | 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) | | | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| 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) | ||
trask marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### 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 | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| | 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) | | | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| 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) | ||
trask marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### 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 | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| | 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) | | | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| 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) | ||
trask marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### Deprecated events | ||
|
|
||
| The `rpc.message` event and its associated attributes have been deprecated with no replacement: | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| | 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) | | ||
| <!-- prettier-ignore-end --> | ||
|
|
||
| ### Deprecated metrics | ||
|
|
||
| The following metrics have been deprecated with no replacement: | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| | 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) | | ||
| <!-- prettier-ignore-end --> | ||
lmolkova marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.