Add RPC semantic convention stable opt-in support by zeitlinger · Pull Request #15932 · open-telemetry/opentelemetry-java-instrumentation

zeitlinger · 2026-01-19T16:46:06Z

First part of #15879

This adds support for the stable RPC semantic conventions via the otel.semconv-stability.opt-in=rpc configuration option.

Key changes:

Add emitOldRpcSemconv()/emitStableRpcSemconv() to SemconvStability
Add stableRpcSystemName() mapping (apache_dubbo→dubbo, connect_rpc→connectrpc)
Add RpcAttributesGetter.getFullMethod() for "service/method" format
Update RpcCommonAttributesExtractor for dual semconv emission
Update RpcClientMetrics/RpcServerMetrics for dual histogram (ms→s unit change)

linux-foundation-easycla · 2026-01-19T16:46:16Z

The committers listed above are authorized under a signed CLA.

✅ login: zeitlinger / name: Gregor Zeitlinger (345ab82, 8213ba4)

zeitlinger · 2026-01-19T17:33:57Z

@trask this is now the first PR for rpc

...c/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcClientMetrics.java

trask · 2026-01-19T18:01:10Z

...ain/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcAttributesGetter.java

+  default String getFullMethod(REQUEST request) {
+    String service = getService(request);
+    String method = getMethod(request);
+    if (service == null || method == null) {
+      return null;
+    }
+    return service + "/" + method;
+  }


rename to getRpcMethod() matching convention of other getters

can we just return null from default method? (requiring choice in each RPC implementation how to structure method)

also, how to handle:

When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to _OTHER. In such cases, tracing instrumentations MUST also set rpc.method_original attribute to the original method value.

...ain/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcAttributesGetter.java

laurit · 2026-01-21T13:24:26Z

...c/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcClientMetrics.java

+    } else {
+      oldClientDurationHistogram = null;


by default fields are initialized to null, is there anything to gain from explicitly assigning the null here?

this allows the field to be final

...c/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcClientMetrics.java

laurit · 2026-01-21T13:33:37Z

...io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcCommonAttributesExtractor.java

+      internalSet(
+          attributes,
+          RPC_SYSTEM_NAME,
+          system == null ? null : SemconvStability.stableRpcSystemName(system));


maybe it would be better to handle null in SemconvStability.stableRpcSystemName

the param would need to be nullable - which I'd like to avoid

laurit · 2026-01-21T13:37:27Z

...c/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcMetricsAdvice.java

+    keys.add(RpcCommonAttributesExtractor.RPC_METHOD);
+
+    // Add status code key
+    if (SemconvStability.emitStableRpcSemconv()) {


should this use stable instead?

method is in both stable and old

...c/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcMetricsAdvice.java

...in/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcSpanNameExtractor.java

laurit · 2026-01-21T13:50:16Z

...tation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/SemconvStability.java

+
+  // virtual key to avoid clash with stable rpc.method
+  private static final AttributeKey<String> RPC_METHOD_OLD =
+      AttributeKey.stringKey("rpc.method.deprecated");


makes me wonder whether we should bother with this at all since it is such a corner case, might as well let the attributes clash

you mean not supporting rpc/dup?

under rpc/dup, stable semconv takes priority when there's a conflict like this (no need for adding this extra unspec'd attribute)

this is never emitted - it's only kept in memory and gets renamed before being added as rpc.method

this is how this virtual attribute gets used:

opentelemetry-java-instrumentation/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/SemconvStability.java

Lines 165 to 171 in f25c3ad

public static Attributes getOldRpcMetricAttributes(Attributes attributes) {

if (emitStableRpcSemconv()) {

// need to copy attributes

return attributes.toBuilder().put(RPC_METHOD, attributes.get(RPC_METHOD_OLD)).build();

}

return attributes;

}

This adds support for the stable RPC semantic conventions via the `otel.semconv-stability.opt-in=rpc` configuration option. Key changes: - Add emitOldRpcSemconv()/emitStableRpcSemconv() to SemconvStability - Add stableRpcSystemName() mapping (apache_dubbo→dubbo, connect_rpc→connectrpc) - Add RpcAttributesGetter.getFullMethod() for "service/method" format - Update RpcCommonAttributesExtractor for dual semconv emission - Update RpcClientMetrics/RpcServerMetrics for dual histogram (ms→s unit change)

trask · 2026-02-05T21:21:39Z

I think this could be broken up into smaller PRs which would make reviews go faster, here's an AI generated suggestion that seems reasonable, though I haven't looked at it too closely:

Plan: Break PR #15932 into Smaller PRs

PR: Add RPC semantic convention stable opt-in support #15932

TL;DR: PR #15932 adds RPC stable semconv opt-in support across 25 files with +1,076/-350 changes. It can be decomposed into 5 incremental PRs that each deliver value independently while preserving backward compatibility. The key insight is that the RpcAttributesGetter interface change can be made non-breaking initially by adding a second type parameter with defaults, allowing the extractors and metrics to be updated separately from the instrumentation implementations.

PR 1: Add RPC SemconvStability infrastructure (foundation)

Files:

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/SemconvStability.java
instrumentation-api-incubator/build.gradle.kts (test tasks only)

Changes:

Add emitOldRpcSemconv() / emitStableRpcSemconv() to SemconvStability
Add stableRpcSystemName() mapping function (apache_dubbo→dubbo, connect_rpc→connectrpc)
Add getOldRpcMethodAttributeKey() and getOldRpcMetricAttributes() helper methods
Add rpc and rpc/dup to test task JVM args

Impact: No behavioral change - just adds flags (defaults to old semconv only)

PR 2: Expand RpcAttributesGetter interface (backward-compatible API change)

Files:

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcAttributesGetter.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcClientAttributesExtractor.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcServerAttributesExtractor.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcSizeAttributesExtractor.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcSpanNameExtractor.java

Changes:

Add RESPONSE type parameter to RpcAttributesGetter<REQUEST, RESPONSE> with wildcard ? usage in extractors where response type isn't needed
Deprecate getMethod(REQUEST) and add new default methods: getRpcMethod(REQUEST), getErrorType(REQUEST, RESPONSE, Throwable), isPredefined(REQUEST)
Update extractor method signatures to accept RpcAttributesGetter<REQUEST, RESPONSE>

Impact: No behavioral change - default implementations return null/false preserving existing behavior

PR 3: Add dual-semconv support to RPC attributes extractors

Files:

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcCommonAttributesExtractor.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcSpanNameExtractor.java
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcAttributesExtractorTest.java
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcSpanNameExtractorTest.java

Changes:

Add stable attribute keys: rpc.system.name, rpc.method_original, error.type
Update onStart() to emit old/stable attributes based on stability flags
Update onEnd() to emit error.type for stable semconv
Update RpcSpanNameExtractor.extract() to use getRpcMethod() for stable semconv
Update tests to validate both semconv modes

PR 4: Add dual-semconv support to RPC metrics

Files:

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcClientMetrics.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcServerMetrics.java
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcMetricsAdvice.java
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcClientMetricsTest.java
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcServerMetricsTest.java

Changes:

Add new metrics: rpc.client.call.duration (s), rpc.server.call.duration (s)
Keep old metrics: rpc.client.duration (ms), rpc.server.duration (ms)
Update RpcMetricsAdvice with stable attribute key list (rpc.system.name, rpc.response.status_code)
Record to old/stable histograms based on stability flags
Update tests for both semconv modes

PR 5: Update instrumentation implementations

Files: All *RpcAttributesGetter implementations across instrumentation modules:

Instrumentation	File
apache-dubbo-2.7	`DubboRpcAttributesGetter.java`
aws-sdk-1.11	`AwsSdkRpcAttributesGetter.java`, `AwsSdkSpanNameExtractor.java`
aws-sdk-2.2	`AwsSdkRpcAttributesGetter.java`
grpc-1.6	`GrpcRpcAttributesGetter.java`
gwt-2.0	`GwtRpcAttributesGetter.java`
rmi	`RmiClientAttributesGetter.java`, `RmiServerAttributesGetter.java`
spring-rmi-4.0	`ClientAttributesGetter.java`, `ServerAttributesGetter.java`

Changes:

Update type signatures from RpcAttributesGetter<REQUEST> to RpcAttributesGetter<REQUEST, RESPONSE>
Add @Deprecated to existing getMethod() implementations
Optionally implement getRpcMethod(), getErrorType(), isPredefined() for richer stable semconv support
Add @SuppressWarnings("deprecation") to call sites like AwsSdkSpanNameExtractor

Verification

Build passes: ./gradlew build
Unit tests: ./gradlew :instrumentation-api-incubator:test
Test with stability flags: ./gradlew :instrumentation-api-incubator:testStableSemconv :instrumentation-api-incubator:testBothSemconv
Verify no public API breaks with japicmp

Design Decisions

Decision	Rationale
Incremental merging over atomic	Each PR delivers reviewable, testable value and can be merged independently
Interface change first	Changing `RpcAttributesGetter` signature early with backward-compatible defaults allows extractors and instrumentations to be updated in any order
Tests inline with implementation	Test updates go with their corresponding implementation PR rather than a separate test-only PR

Dependencies

PR 1 (SemconvStability)
  │
  ├── PR 2 (RpcAttributesGetter interface)
  │     │
  │     ├── PR 3 (Attributes extractors) ──┐
  │     │                                  │
  │     └── PR 4 (Metrics) ────────────────┤
  │                                        │
  └────────────────────────────────────────┴── PR 5 (Instrumentation implementations)

PR 1 must be merged first (provides the stability flags)
PR 2 must be merged before PRs 3, 4, or 5 (changes the interface)
PRs 3 and 4 can be merged in parallel after PR 2
PR 5 can be merged after PR 2 (doesn't depend on 3 or 4)

zeitlinger · 2026-02-06T10:50:23Z

here's an AI generated suggestion that seems reasonable

.. I'll let the AI do it 😄

When both old and stable RPC semconv are enabled, both use the rpc.method attribute key with different values. Previously this was solved with a virtual rpc.method.deprecated key in SemconvStability that leaked onto spans. Instead, register a ContextCustomizer that stores the old method value directly in context via a ContextKey. RpcClientMetrics/RpcServerMetrics read from context in onStart() and use the stored value when recording old metrics. This keeps the old method value off spans entirely.

zeitlinger self-assigned this Jan 19, 2026

zeitlinger requested a review from a team as a code owner January 19, 2026 16:46

zeitlinger mentioned this pull request Jan 19, 2026

RPC stable opt-in #15879

Draft

zeitlinger force-pushed the rpc-api-incubator branch from 8ada385 to 3bee40e Compare January 19, 2026 16:48

trask reviewed Jan 19, 2026

View reviewed changes

zeitlinger force-pushed the rpc-api-incubator branch 2 times, most recently from 2ede454 to 58a163f Compare January 20, 2026 13:30

laurit reviewed Jan 21, 2026

View reviewed changes

zeitlinger force-pushed the rpc-api-incubator branch from b9017d6 to 298b23c Compare January 27, 2026 10:30

zeitlinger added 14 commits February 4, 2026 14:11

check for well-known method

e141120

deprecate getMethod

ca84944

rename

1c26011

fix

58ba056

update descriptions

68a1522

pr review

7dff3a2

rename to old

d3512c9

pr review

1a1cdba

add getErrorType

ef9440e

add getErrorType

5d51fbb

system fallback for span name

25fd8e6

system fallback for span name

0a09fd5

add getErrorType

7690d20

zeitlinger force-pushed the rpc-api-incubator branch from 298b23c to 7690d20 Compare February 4, 2026 13:17

zeitlinger added 2 commits February 5, 2026 17:05

Merge branch 'main' into rpc-api-incubator

735b2e5

Merge branch 'main' into rpc-api-incubator

345ab82

zeitlinger mentioned this pull request Feb 6, 2026

Add RPC semantic convention stability infrastructure #16112

Merged

zeitlinger marked this pull request as draft February 9, 2026 10:38

zeitlinger mentioned this pull request Feb 9, 2026

Expand RpcAttributesGetter interface for stable RPC semconv support #16121

Merged

zeitlinger mentioned this pull request Feb 10, 2026

Add dual-semconv support to RPC attributes extractors #16130

Merged

This was referenced Feb 26, 2026

Add dual-semconv support to RPC metrics #16297

Closed

Add dual-semconv support to RPC metrics #16298

Merged

	public static Attributes getOldRpcMetricAttributes(Attributes attributes) {
	if (emitStableRpcSemconv()) {
	// need to copy attributes
	return attributes.toBuilder().put(RPC_METHOD, attributes.get(RPC_METHOD_OLD)).build();
	}
	return attributes;
	}

Conversation

zeitlinger commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linux-foundation-easycla bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeitlinger commented Jan 19, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trask commented Feb 5, 2026

Plan: Break PR #15932 into Smaller PRs

PR 1: Add RPC SemconvStability infrastructure (foundation)

PR 2: Expand RpcAttributesGetter interface (backward-compatible API change)

PR 3: Add dual-semconv support to RPC attributes extractors

PR 4: Add dual-semconv support to RPC metrics

PR 5: Update instrumentation implementations

Verification

Design Decisions

Dependencies

Uh oh!

zeitlinger commented Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zeitlinger commented Jan 19, 2026 •

edited

Loading

linux-foundation-easycla bot commented Jan 19, 2026 •

edited

Loading