RPC semantic convention stability migration guide

RPC spans and call duration metrics, including the gRPC and Apache Dubbo conventions, are stable. Connect RPC, JSON-RPC, and exception events remain in development.

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.

The following recommendations summarize the migration guidance in Semantic conventions for RPC. 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, span kind, and unit of measure.
  • SHOULD introduce an environment variable OTEL_SEMCONV_STABILITY_OPT_IN in their existing major version as a comma-separated list of category-specific values. The list of values includes:
    • rpc - emit the stable RPC conventions, and stop emitting the experimental RPC conventions that the instrumentation emitted previously.
    • rpc/dup - emit both the experimental and 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 experimental RPC conventions the instrumentation was emitting previously.
    • rpc/dup takes precedence over rpc if both values are present.
  • SHOULD 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.

Summary of changes

This section summarizes the changes made to the RPC semantic conventions from v1.37.0 to TODO (latest).

Common RPC attribute changes

The following changes apply to RPC spans and call duration metrics:

ChangePRComments
rpc.system → rpc.system.name#3176See below for changes to the values
rpc.method#3223Now the fully-qualified logical name of the method from the RPC interface perspective. See method and span name changes.
rpc.service#3223Deprecated, use fully-qualified rpc.method instead.
network.transport#3350Removed
network.type#2857Removed
New: error.type#2852

RPC span attributes

In addition to the common attribute changes:

ChangePRComments
rpc.system.name, rpc.method#3203Now marked as sampling-relevant
rpc.grpc.status_code → rpc.status_code#2920, #3921Changed from int to string (e.g., 0 → "OK")
rpc.connect_rpc.error_code → rpc.status_code#2920, #3921
rpc.grpc.request.metadata.<key>#3169, #3924Replaced by rpc.request.header.<key>
rpc.grpc.response.metadata.<key>#3169, #3924Split into rpc.response.header.<key> (sent before the response payload) and rpc.response.trailer.<key> (sent after it)
rpc.connect_rpc.request.metadata.<key>#3169, #3924Replaced by rpc.request.header.<key>
rpc.connect_rpc.response.metadata.<key>#3169, #3924Split into rpc.response.header.<key> (sent before the response payload) and rpc.response.trailer.<key> (sent after it)
server.address#3203, #3317, #3257, #3919Now sampling-relevant. Required → Conditionally Required if available on client spans; Required → Recommended when available on server spans.
server.port#3203, #3317, #3919Now sampling-relevant. Still Conditionally Required, but the condition changed from the transport supporting ports to the port being applicable and server.address being set.
New: rpc.method_original#3223The original name of the method used by the client. See method and span name changes.
client.address#3488Removed
client.port#3488Removed

For client spans, server.address identifies a group of RPC server instances. It may contain a DNS name, a service-registry target, a local socket name, or an IP address.

For server spans, server.address and server.port describe the address the client used to reach this server, as reported by the transport or RPC framework. Instrumentations SHOULD NOT use actual network-level connection information to populate these attributes. If the address used by the client is unavailable, instrumentations SHOULD NOT set these attributes.

Individual RPC systems can override the general requirement levels in the table. See RPC system-specific changes for overrides and address sourcing.

References:

RPC methods and span names

On spans and metrics, methods that are unrecognized or cannot reliably be identified as predefined MUST be recorded as _OTHER. Instrumentations SHOULD support configuring recognized methods if valid methods could otherwise become _OTHER. See the method cardinality rules.

On spans, rpc.method_original is Conditionally Required if and only if it’s different than rpc.method.

In v1.37.0, the span name MUST be the full RPC method name. It now SHOULD be {rpc.method}, falling back to {rpc.system.name} when the method is unavailable or _OTHER. Individual RPC systems MAY override these span naming rules (#3223).

JSON-RPC overrides the common method guidance for spans, as described below.

rpc.system.name values

ChangePRComments
apache_dubbo → dubbo#3176
connect_rpc → connectrpc#3176
java_rmi#3176Removed, but can still be used as a custom value
dotnet_wcf#3176Removed, but can still be used as a custom value

References:

RPC call duration metrics

Both duration metrics were renamed in #2961:

v1.37.0TODO (latest)
rpc.server.durationrpc.server.call.duration
rpc.client.durationrpc.client.call.duration

Shared changes:

  • Unit: ms → s (#2961).
  • Descriptions: Now Measures the duration of an incoming Remote Procedure Call (RPC). for the server metric and Measures the duration of an outgoing Remote Procedure Call (RPC). for the client metric (#3328).
  • Histogram buckets: Explicit boundaries are now recommended, in seconds, ranging from 0.0001 to 100. See the general RPC boundaries (#2961, #4185). gRPC uses a different set.

Both metrics remain Recommended, as in v1.37.0.

In addition to the common attribute changes, both metrics add rpc.status_code (#2920, #3921).

Address attributes were Recommended on both metrics in v1.37.0:

AttributeClient metric requirement (TODO)Server metric requirement (TODO)PR
server.addressConditionally Required if availableOpt-In#3197, #3257
server.portConditionally Required if applicable and server.address is setOpt-In#3197

See RPC system-specific changes for overrides and target port availability rules.

References:

RPC exception events

New rpc.client.call.exception and rpc.server.call.exception log-based events represent exceptions that occurred during an outgoing RPC call or incoming RPC call processing, respectively (#3426).

Deprecated events

The rpc.message event and its associated attributes have been deprecated with no replacement at this time:

Deprecated Event/AttributePR
rpc.message event#3283
rpc.message.type#3283
rpc.message.id#3283
rpc.message.compressed_size#3283
rpc.message.uncompressed_size#3283

Deprecated metrics

The following metrics have been deprecated with no replacement at this time:

Deprecated MetricPR
rpc.server.requests_per_rpc#2846
rpc.server.responses_per_rpc#2846
rpc.client.requests_per_rpc#2846
rpc.client.responses_per_rpc#2846
rpc.server.request.size#3267
rpc.server.response.size#3267
rpc.client.request.size#3267
rpc.client.response.size#3267

RPC system-specific changes

gRPC

For client spans and rpc.client.call.duration, server.address is Required. Client address attributes SHOULD come from the configured channel target, not the network connection. Server span address attributes SHOULD come from HTTP/2 :authority.

Both duration metrics SHOULD use the gRPC-specific bucket boundaries instead of the general RPC boundaries. These match gRPC’s existing OpenTelemetry metrics (#4185).

References:

Apache Dubbo

Client address attributes SHOULD come from the configured Dubbo target, not the network connection. For service discovery, server.address SHOULD contain the discovery target and server.port SHOULD NOT be set, since the registry port is not the RPC server port.

See Dubbo client conventions for target parsing and port requirements (#4120).

References:

JSON-RPC

JSON-RPC conventions remain in development. The system identifier jsonrpc is unchanged from v1.37.0, but the attribute names and error reporting have changed.

Attribute changePRComments
rpc.jsonrpc.version → jsonrpc.protocol.version#3176Still Conditionally Required if other than the default version (1.0)
rpc.jsonrpc.request_id → jsonrpc.request.id#3176Still Recommended. Previously, a null ID was recorded as an empty string. Instrumentations SHOULD NOT capture this attribute when the id is null or omitted.
rpc.jsonrpc.error_code → rpc.status_code#2920, #3921Changed from int to string (e.g., -32602 → "-32602")
rpc.jsonrpc.error_message#2920, #3308Deprecated, use the span status description when reporting JSON-RPC spans.
rpc.method#3223Changed from Required to Opt-In on JSON-RPC spans

JSON-RPC allows arbitrary method names, so general-purpose tracing instrumentations SHOULD NOT set rpc.method by default and SHOULD provide a way to configure recognized methods.

References: