Fixing OpenTelemetryTraces to include the GA V1 semantic conventionttributes #45929

FabianMeiswinkel · 2025-07-07T11:48:03Z

Description

The original version of OpenTelemetry tracing was based off of a pre-V1 semantic convention spec. This PR ensures that by default the attributes for both the Pre-V1 spec as well as the V1 spec are emitted. Optionally via the environment variable COSMOS_OTEL_SPAN_ATTRIBUTE_NAMING_SCHEME or system property COSMOS.OTEL_SPAN_ATTRIBUTE_NAMING_SCHEME the behavior can also be changed to only emit the Pre-V1 or only the V1 attributes (for slightly better efficiency). Valid values are ALL, V1 and PRE_V1_RELEASE.

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

…ttributes

Copilot

Pull Request Overview

This PR enhances OpenTelemetry tracing in the Azure Cosmos SDK by emitting both Pre-V1 and GA V1 semantic convention attributes by default and making this behavior configurable via an environment variable.

Introduce AttributeNamingScheme and integrate it into CosmosClientTelemetryConfig.
Refactor tracer creation to use LibraryTelemetryOptions.
Extend DiagnosticsProvider to conditionally emit span attributes according to the selected naming scheme.
Add configuration support in Configs for the new environment variable and update tests accordingly.

Reviewed Changes

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

Show a summary per file

File	Description
`CosmosClientTelemetryConfig.java`	Added `attributeNamingSchemes`, `getOrCreateTracer` refactor, and new getter/setter for naming scheme.
`AttributeNamingScheme.java`	New enum to parse and represent Pre-V1 and V1 schemes.
`AttributeNamesV1.java`	New enum listing GA V1 semantic convention attribute names.
`AttributeNamesPreV1.java`	New enum listing Pre-V1 semantic convention attribute names.
`AttributeNamesCommon.java`	New enum listing common attribute names.
`ImplementationBridgeHelpers.java`	Extended accessor interface to include naming-scheme methods.
`DiagnosticsProvider.java`	Updated span construction to emit attributes by naming scheme.
`Configs.java`	Added environment variable support for `OTEL_SPAN_ATTRIBUTE_NAMING_SCHEME`.
`CosmosTracerTest.java`	Updated tests to cover and validate the new naming-scheme behavior.

Comments suppressed due to low confidence (3)

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/ImplementationBridgeHelpers.java:1643

The method name 'setOtelSpanAttributeNamingSchema' (and its getter) uses 'Schema' while the corresponding methods in CosmosClientTelemetryConfig use 'Scheme'. This mismatch will break the implementation bridge — rename to 'setOtelSpanAttributeNamingScheme' and 'getOtelSpanAttributeNamingScheme'.

            CosmosClientTelemetryConfig setOtelSpanAttributeNamingSchema(

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosClientTelemetryConfig.java:468

This setter is package-private, but it configures a public SDK behavior. Consider making it public to allow users to fluently configure the naming scheme on the client builder.

    CosmosClientTelemetryConfig setOtelSpanAttributeNamingScheme(String name) {

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosClientTelemetryConfig.java:474

[nitpick] Public-facing getters and setters for the new naming scheme should have JavaDoc explaining their purpose and valid values (e.g., 'All', 'Pre_V1_Release', 'V1').

    EnumSet<AttributeNamingScheme> getOtelSpanAttributeNamingScheme() {

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/DiagnosticsProvider.java

…ntation/DiagnosticsProvider.java Co-authored-by: Copilot <[email protected]>

FabianMeiswinkel · 2025-07-07T18:32:33Z

/azp run java - cosmos - tests

FabianMeiswinkel · 2025-07-07T18:33:02Z

/azp run java - cosmos - tests

azure-pipelines · 2025-07-07T18:33:14Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-07T18:33:39Z

Azure Pipelines successfully started running 1 pipeline(s).

FabianMeiswinkel · 2025-07-07T19:15:21Z

/azp run java - cosmos - tests

azure-pipelines · 2025-07-07T19:16:13Z

Azure Pipelines successfully started running 1 pipeline(s).

FabianMeiswinkel · 2025-07-07T21:57:43Z

/azp run java - cosmos - spark

FabianMeiswinkel · 2025-07-07T21:57:49Z

/azp run java - cosmos - kafka

azure-pipelines · 2025-07-07T21:57:52Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-07T21:58:07Z

Azure Pipelines successfully started running 1 pipeline(s).

FabianMeiswinkel · 2025-07-08T00:32:05Z

/azp run java - cosmos - tests

FabianMeiswinkel · 2025-07-08T00:32:22Z

/azp run java - cosmos - kafka

FabianMeiswinkel · 2025-07-08T00:32:31Z

/azp run java - cosmos - spark

azure-pipelines · 2025-07-08T00:32:37Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-08T00:32:39Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-08T00:32:49Z

Azure Pipelines successfully started running 1 pipeline(s).

...mos/src/main/java/com/azure/cosmos/implementation/clienttelemetry/AttributeNamingScheme.java

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Configs.java

FabianMeiswinkel · 2025-07-08T10:25:11Z

/azp run java - cosmos - tests

FabianMeiswinkel · 2025-07-08T10:25:20Z

/azp run java - cosmos - kafka

FabianMeiswinkel · 2025-07-08T10:25:26Z

/azp run java - cosmos - spark

azure-pipelines · 2025-07-08T10:25:35Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-08T10:25:36Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-08T10:25:51Z

Azure Pipelines successfully started running 1 pipeline(s).

...mos/src/main/java/com/azure/cosmos/implementation/clienttelemetry/AttributeNamingScheme.java

…ntation/clienttelemetry/AttributeNamingScheme.java Co-authored-by: Annie Liang <[email protected]>

xinlian12

LGTM, thanks

FabianMeiswinkel · 2025-07-08T21:54:06Z

/azp run java - cosmos - spark

FabianMeiswinkel · 2025-07-08T21:54:14Z

/azp run java - cosmos - kafka

azure-pipelines · 2025-07-08T21:54:16Z

Azure Pipelines successfully started running 1 pipeline(s).

FabianMeiswinkel · 2025-07-08T21:54:24Z

/azp run java - cosmos - tests

azure-pipelines · 2025-07-08T21:54:39Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2025-07-08T21:55:12Z

Azure Pipelines successfully started running 1 pipeline(s).

Fixing OpenTelemetryTraces to include the GA V1 semantic convention a…

9a2421a

…ttributes

Copilot AI review requested due to automatic review settings July 7, 2025 11:48

FabianMeiswinkel requested review from a team and kirankumarkolli as code owners July 7, 2025 11:48

github-actions bot added the Cosmos label Jul 7, 2025

Copilot AI reviewed Jul 7, 2025

View reviewed changes

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/DiagnosticsProvider.java Outdated Show resolved Hide resolved

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/DiagnosticsProvider.java Show resolved Hide resolved

FabianMeiswinkel and others added 2 commits July 7, 2025 11:53

Update CHANGELOG.md

3def90b

Update sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/impleme…

2f458c1

…ntation/DiagnosticsProvider.java Co-authored-by: Copilot <[email protected]>

Merge branch 'main' into users/fabianm/OTelTraceGAFix

e716a5d

jeet1995 approved these changes Jul 8, 2025

View reviewed changes

jeanbisutti reviewed Jul 8, 2025

View reviewed changes

FabianMeiswinkel added 2 commits July 8, 2025 10:20

Update AttributeNamingScheme.java

e84613f

Merge branch 'main' into users/fabianm/OTelTraceGAFix

bb212b8

tvaron3 approved these changes Jul 8, 2025

View reviewed changes

kushagraThapar approved these changes Jul 8, 2025

View reviewed changes

FabianMeiswinkel enabled auto-merge (squash) July 8, 2025 21:19

xinlian12 reviewed Jul 8, 2025

View reviewed changes

...mos/src/main/java/com/azure/cosmos/implementation/clienttelemetry/AttributeNamingScheme.java Outdated Show resolved Hide resolved

FabianMeiswinkel and others added 2 commits July 8, 2025 23:39

Merge branch 'main' into users/fabianm/OTelTraceGAFix

38d4c0a

Update sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/impleme…

069b058

…ntation/clienttelemetry/AttributeNamingScheme.java Co-authored-by: Annie Liang <[email protected]>

tvaron3 approved these changes Jul 8, 2025

View reviewed changes

xinlian12 approved these changes Jul 8, 2025

View reviewed changes

FabianMeiswinkel merged commit 0dca69d into Azure:main Jul 9, 2025
94 checks passed

Fixing OpenTelemetryTraces to include the GA V1 semantic conventionttributes #45929

Fixing OpenTelemetryTraces to include the GA V1 semantic conventionttributes #45929

Uh oh!

Conversation

FabianMeiswinkel commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

FabianMeiswinkel commented Jul 7, 2025

Uh oh!

FabianMeiswinkel commented Jul 7, 2025

Uh oh!

azure-pipelines bot commented Jul 7, 2025

Uh oh!

azure-pipelines bot commented Jul 7, 2025

Uh oh!

FabianMeiswinkel commented Jul 7, 2025

Uh oh!

azure-pipelines bot commented Jul 7, 2025

Uh oh!

FabianMeiswinkel commented Jul 7, 2025

Uh oh!

FabianMeiswinkel commented Jul 7, 2025

Uh oh!

azure-pipelines bot commented Jul 7, 2025

Uh oh!

azure-pipelines bot commented Jul 7, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

Uh oh!

xinlian12 left a comment

Choose a reason for hiding this comment

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 8, 2025

Uh oh!

azure-pipelines bot commented Jul 8, 2025

Uh oh!

FabianMeiswinkel commented Jul 7, 2025 •

edited

Loading