RPC semantic convention stability migration guide

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.

Summary of changes

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

RPC span attributes

ChangePRComments
rpc.system → rpc.system.name#3176, #3203See below for changes to the values, also now marked as sampling-relevant
rpc.method#3223, #3203Now contains fully-qualified method name (e.g., com.example.ExampleService/exampleMethod), also now marked as sampling-relevant
rpc.service#3223Removed, integrated into rpc.method
network.transport#3350Removed
network.type#2857Removed
rpc.grpc.status_code → rpc.response.status_code#2920Changed from int to string (e.g., 0 → "OK")
rpc.connect_rpc.error_code → rpc.response.status_code#2920
rpc.grpc.request.metadata.<key>#3169Replaced by rpc.request.metadata.<key>
rpc.grpc.response.metadata.<key>#3169Replaced by rpc.response.metadata.<key>
rpc.connect_rpc.request.metadata.<key>#3169Replaced by rpc.request.metadata.<key>
rpc.connect_rpc.response.metadata.<key>#3169Replaced by rpc.response.metadata.<key>
server.address#3203, #3317Now marked as sampling-relevant;
Now it’s taken from static configuration and can be any string identifying a group of server instances.
server.port#3203, #3317Now marked as sampling-relevant;
>Now it’s taken from static configuration.
New: error.type#2852
New: rpc.method_original#3223Original method name when rpc.method is set to _OTHER

References:

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
New: jsonrpc#2503

References:

RPC server call duration metric

Metric changes:

  • Name: rpc.server.duration → rpc.server.call.duration (#2961)
  • Unit: ms → s (#2961)
  • Description: Measures the duration of inbound RPC. → Measures the duration of inbound remote procedure calls (RPC). (#2961)
  • Histogram buckets: boundaries updated to reflect change from milliseconds to seconds (#2961)
  • Requirement level: Made required (#3284)
  • Attributes: see table below
Attribute changePRComments
rpc.system → rpc.system.name#3176See above for changes to the values
rpc.method#3223Now contains fully-qualified method name (e.g., com.example.ExampleService/exampleMethod)
rpc.service#3223Removed, integrated into rpc.method
network.transport#3350Removed
network.type#2857Removed
server.address#3197Changed from Recommended to Opt-In
server.port#3197Changed from Recommended to Opt-In
New: rpc.response.status_code#2920
New: error.type#2852

References:

RPC client call duration metric

Metric changes:

  • Name: rpc.client.duration → rpc.client.call.duration (#2961)
  • Unit: ms → s (#2961)
  • Description: Measures the duration of outbound RPC. → Measures the duration of outbound remote procedure calls (RPC). (#2961)
  • Histogram buckets: boundaries updated to reflect change from milliseconds to seconds (#2961)
  • Requirement level: Made required (#3284)
  • Attributes: see table below
Attribute changePRComments
rpc.system → rpc.system.name#3176See above for changes to the values
rpc.method#3223Now contains fully-qualified method name (e.g., com.example.ExampleService/exampleMethod)
rpc.service#3223Removed, integrated into rpc.method
network.transport#3350Removed
network.type#2857Removed
server.address#3197Changed from Recommended to Required
server.port#3197Changed from Recommended to Conditionally Required
New: rpc.response.status_code#2920
New: error.type#2852

References:

RPC exception events

Exceptions that prevent the call from completing successfully are recorded as rpc.client.call.exception and rpc.server.call.exception log-based events (#3426).

Deprecated events

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

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:

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