Update to latest messaging semantic conventions, part 1

[trask]

First part of #19254

Follow-up PRs can migrate each instrumentation family to this shared contract without redefining its semantics. Once those migrations are complete, a final activation PR will make common v3 preview select the latest messaging semconv globally. The old and dual-output paths will then be removed in 3.0.

This PR also migrates the Kafka production instrumentation (kafka-clients and kafka-connect) to the shared messaging contract: send/receive spans use the operation-first send/poll names and stable operation attributes, receive spans become CLIENT under messaging preview, and the process path routes through the shared MessagingProcessInstrumenterFactory. The accompanying Kafka test changes keep existing assertions compatible with both the old and new contracts. The Pulsar change connects its existing process instrumentation to the new process-duration metric because Pulsar already uses the shared messaging metrics implementation.

With the latest messaging semconv selected, Kafka receive spans are emitted regardless of otel.instrumentation.messaging.experimental.receive-telemetry.enabled; legacy semconv behavior is unchanged. This option originally existed because the old semconv modeled receive telemetry as a separate consumer trace linked to the producer, while disabling it preserved producer-to-process parenting. The latest semconv preserves producer-to-process parenting while modeling poll/receive as a CLIENT span, so the original reason for the option no longer applies. Any future requirement to suppress only receive spans should start with a newly designed configuration contract.

[Copilot]

Pull request overview

Pins the shared messaging semantic-conventions contract to semantic-conventions v1.43.0 behind the semconv stability selectors, keeping the existing (legacy/V0) behavior as the default while enabling v1.43 output (and dual-emit) via preview/opt-in configuration. It also connects Pulsar “process” spans to the new shared process-duration metric and adds a staged v3-preview test task.

Changes:

• Introduces mode-aware (legacy vs v1.43 vs dual) shared messaging naming, span-kind selection, attribute extraction, and metrics (producer/consumer/process).
• Expands test coverage for messaging semconv selection and for the new messaging span naming/span-kind/metrics behavior across modes.
• Adds a staged testV3Preview task and aligns SqlQueryAnalyzer.isCached() cache selection with the v3-preview analyze path.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
instrumentation/pulsar/pulsar-2.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/pulsar/v2_8/telemetry/PulsarSingletons.java	Wires Pulsar consumer “process” instrumenter to shared messaging process metrics.
instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/internal/SemconvStabilityTest.java	Adds a parameterized messaging selection matrix test.
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/SemconvStability.java	Clarifies semantics of emitStableMessagingSemconv() via updated Javadoc.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingSpanNameExtractorTest.java	Updates span-name tests to cover legacy vs v1.43 naming and operation-name overrides.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingSpanKindExtractorTest.java	Adds tests for legacy vs v1.43 span kind selection.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingProducerMetricsTest.java	Updates producer metrics tests for conditional legacy/v1.43 metrics emission and batch counting.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingProcessMetricsTest.java	Adds tests for the v1.43 process-duration metric behavior.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingConsumerMetricsTest.java	Adds tests for legacy vs v1.43 consumer metrics and batch counting.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractorTest.java	Updates attribute-extractor tests for conditional legacy/v1.43 attribute sets.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingSpanNameExtractor.java	Implements v1.43 operation-first span naming, with optional operation-name override.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingSpanKindExtractor.java	Adds mode-aware span-kind selection (including CLIENT for receive in v1.43).
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingProducerMetrics.java	Adds v1.43 producer metrics (duration + sent messages) while preserving legacy metrics by default.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingProcessMetrics.java	Introduces the v1.43 process-duration metric implementation.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingOperation.java	Adds an internal wrapper to model operation name/type and support overrides.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingMetricsAdvice.java	Splits and builds per-metric attribute advice for legacy vs v1.43 metric sets.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingConsumerMetrics.java	Adds v1.43 consumer metrics (duration + consumed messages) while preserving legacy metrics by default.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractorBuilder.java	Allows nullable operation handling via the new MessagingOperation wrapper.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractor.java	Emits legacy and/or v1.43 messaging attributes depending on selected mode (including dual emit).
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessageOperation.java	Updates legacy operation-name docs and positions it as the default for v1.43 unless overridden.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlQueryAnalyzer.java	Aligns isCached() cache selection with v3-preview behavior used by analyze().
instrumentation-api-incubator/build.gradle.kts	Adds preview/dual-preview args to existing semconv test tasks and introduces testV3Preview.

[opentelemetry-pr-dashboard]

Pull request dashboard status

• Status: Closed.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 55 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 59 out of 59 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 66 out of 66 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 66 out of 66 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 86 out of 86 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 86 out of 86 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkInstrumenterFactory.java:181

• [General] This copies only the Span from the SQS creation context. When setUseConfiguredPropagatorForMessaging(true) is used, that context can also contain baggage or custom values extracted by the configured TextMapPropagator; those values are discarded before the process callback, so downstream code no longer observes the full propagated context. Extract onto parentContext (as the generic messaging process customizer does) rather than copying only Span.fromContext(...).

[Copilot]

Pull request overview

Copilot reviewed 86 out of 86 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractor.java:73

• [General] This same-name overload makes MessagingAttributesExtractor.create(getter, null) ambiguous for source callers, even though both overloads explicitly advertise a nullable operation. The updated tests already need typed null locals to work around this. Please use a distinct entry-point name for the MessagingOperationType variant (or another design that keeps existing null calls source-compatible).

  /** Creates the messaging attributes extractor for the given operation type. */
  public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
      MessagingAttributesGetter<REQUEST, RESPONSE> getter,
      @Nullable MessagingOperationType operationType) {
    return builder(getter, operationType).build();

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractor.java:93

• [General] The new builder overload has the same nullable-overload ambiguity: MessagingAttributesExtractor.builder(getter, null) no longer compiles because Java cannot choose between MessageOperation and MessagingOperationType. Since null is explicitly supported here, please expose the new variant under a distinct name or otherwise preserve unqualified null calls.

  public static <REQUEST, RESPONSE> MessagingAttributesExtractorBuilder<REQUEST, RESPONSE> builder(
      MessagingAttributesGetter<REQUEST, RESPONSE> getter,
      @Nullable MessagingOperationType operationType) {
    return new MessagingAttributesExtractorBuilder<>(getter, operationType);

[Copilot]

Pull request overview

Copilot reviewed 86 out of 86 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingSpanNameExtractor.java:78

• Temporary and anonymous destinations must be checked before using a destination template. For example, the NATS getter returns _INBOX. as a template while marking the destination temporary, so messaging preview currently emits a high-cardinality name such as publish _INBOX. instead of omitting the destination. Only consult the template/name when neither flag is set.

      String destinationName = getter.getDestinationTemplate(request);
      if (destinationName == null
          && !getter.isTemporaryDestination(request)
          && !getter.isAnonymousDestination(request)) {
        destinationName = getter.getDestination(request);
      }

[Copilot]

Pull request overview

Copilot reviewed 86 out of 86 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractor.java:73

• [General] This overload breaks source compatibility for the supported no-operation call create(getter, null): the deprecated MessageOperation overload remains, so Java can no longer choose between the two unrelated enum parameter types. The updated test has to introduce a typed null for exactly this reason. Since MessageOperation is only deprecated until 3.0, please expose the new operation-type entry point under a distinct name (or otherwise use a parameter hierarchy that leaves the old overload more specific) so existing callers still compile.

  public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
      MessagingAttributesGetter<REQUEST, RESPONSE> getter,
      @Nullable MessagingOperationType operationType) {
    return builder(getter, operationType).build();

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractor.java:93

• [General] The same overload ambiguity affects existing builder(getter, null) callers: both the retained MessageOperation overload and this new MessagingOperationType overload are applicable, so previously valid source no longer compiles before the announced 3.0 removal. Please give the new builder entry point a distinct name or introduce a common parameter abstraction that preserves an unambiguous deprecated overload.

  public static <REQUEST, RESPONSE> MessagingAttributesExtractorBuilder<REQUEST, RESPONSE> builder(
      MessagingAttributesGetter<REQUEST, RESPONSE> getter,
      @Nullable MessagingOperationType operationType) {
    return new MessagingAttributesExtractorBuilder<>(getter, operationType);

[trask]

Superseded by the reviewer-sized draft stack #19266 through #19276. Shared ownership moved to #19266 (contract), #19267 (metrics), and #19268 (process topology); family migrations are #19269-#19275, with final activation in #19276. This branch remains available as source reference b342f524db416765f221b0828b74a10d5ef8229f.