Cosmos: Add user agent tracking for azure-cosmos-encryption SDK#48505
Open
kushagraThapar wants to merge 4 commits intoAzure:mainfrom
Open
Cosmos: Add user agent tracking for azure-cosmos-encryption SDK#48505kushagraThapar wants to merge 4 commits intoAzure:mainfrom
kushagraThapar wants to merge 4 commits intoAzure:mainfrom
Conversation
The azure-cosmos-encryption library wraps the core CosmosAsyncClient
without appending its own identifier to the user agent string, making
it impossible to track encryption SDK adoption through telemetry.
Changes:
- Add azure-cosmos-encryption.properties resource file with
artifactId and version (Maven-filtered at build time)
- Add USER_AGENT_SUFFIX constant in Constants.java that reads the
properties via CoreUtils.getProperties() (same pattern as Kafka
connector)
- Add appendUserAgentSuffix() method to AsyncDocumentClient interface
and RxDocumentClientImpl to allow appending to the UserAgentContainer
after client construction
- Call appendUserAgentSuffix() in CosmosEncryptionAsyncClient
constructor to append 'azure-cosmos-encryption/{version}' to the
existing user agent
The resulting user agent will look like:
azsdk-java-cosmos/4.x.x OS/ver JRE/ver <customer-suffix> azure-cosmos-encryption/2.x.y
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add 3 unit tests in CosmosEncryptionAsyncClientUnitTest verifying user agent suffix append, properties loading, and graceful failure - Add unit test in UserAgentContainerTest for append suffix behavior - Add changelog entries for azure-cosmos and azure-cosmos-encryption - GA deleteAllItemsByPartitionKey in CosmosEncryptionAsyncContainer and CosmosEncryptionContainer (core SDK API is already public) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds telemetry-friendly user-agent suffixing so azure-cosmos-encryption usage/version can be tracked even when wrapping an already-constructed CosmosAsyncClient.
Changes:
- Add an
appendUserAgentSuffix(String)API on the internalAsyncDocumentClientand implement it inRxDocumentClientImpl. - Add Maven-filtered
azure-cosmos-encryption.propertiesand constants to deriveazure-cosmos-encryption/{version}at runtime. - Append the encryption SDK user-agent suffix when
CosmosEncryptionAsyncClientis constructed.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java | Implements appendUserAgentSuffix by appending onto UserAgentContainer suffix. |
| sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/AsyncDocumentClient.java | Adds new appendUserAgentSuffix(String) method to the internal client interface. |
| sdk/cosmos/azure-cosmos-encryption/src/main/resources/azure-cosmos-encryption.properties | Adds filtered name/version resource used to build the encryption UA suffix. |
| sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/implementation/Constants.java | Loads name/version from properties and builds USER_AGENT_SUFFIX. |
| sdk/cosmos/azure-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionAsyncClient.java | Appends encryption UA suffix to the wrapped Cosmos client during construction. |
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java
Outdated
Show resolved
Hide resolved
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java
Outdated
Show resolved
Hide resolved
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/AsyncDocumentClient.java
Outdated
Show resolved
Hide resolved
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java
Show resolved
Hide resolved
...cosmos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionAsyncClient.java
Show resolved
Hide resolved
- Make appendUserAgentSuffix a default no-op method on AsyncDocumentClient interface for binary compatibility - Add de-duplication check to prevent suffix growth when multiple encryption clients wrap the same CosmosAsyncClient - Preserve feature flags (|F...) by re-applying them via addUserAgentSuffix after setSuffix overwrites the user agent - Enhance UserAgentContainerTest to cover feature flag preservation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Member
|
@sdkReviewAgent-2 |
Member
|
⏳ PR Review Agent — Starting review... |
xinlian12
reviewed
Mar 21, 2026
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java
Outdated
Show resolved
Hide resolved
xinlian12
reviewed
Mar 21, 2026
...mos-encryption/src/main/java/com/azure/cosmos/encryption/CosmosEncryptionAsyncContainer.java
Show resolved
Hide resolved
xinlian12
reviewed
Mar 21, 2026
...re-cosmos-encryption/src/main/java/com/azure/cosmos/encryption/implementation/Constants.java
Outdated
Show resolved
Hide resolved
…geFeed - Fix dedup: use token-based matching instead of substring contains() to avoid false positives (e.g. 2.28.0 matching 2.28.0-beta.1) - Cache properties map and use getOrDefault() for defensive fallback if properties file is missing at runtime - GA queryChangeFeed in CosmosEncryptionAsyncContainer and CosmosEncryptionContainer (core SDK API is already public) - Update changelog to include queryChangeFeed GA Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
azure-cosmos-encryptionlibrary currently wraps the coreCosmosAsyncClientwithout appending its own identifier to the user agent string. This makes it impossible to track encryption SDK adoption, version distribution, or customer usage through telemetry (e.g.,ComputeRequest5M,DailyUserAgentSummary).This PR adds user agent tracking by appending
azure-cosmos-encryption/{version}to the existing user agent suffix when the encryption client is constructed. It also GA's thedeleteAllItemsByPartitionKeyAPI.Changes
azure-cosmos-encryption:
azure-cosmos-encryption.propertiesresource file (Maven-filterednameandversion, same pattern asazure-cosmos-kafka-connect.properties)PROPERTIES_FILE_NAME,CURRENT_VERSION,CURRENT_NAME, andUSER_AGENT_SUFFIXconstants inConstants.javausingCoreUtils.getProperties()CosmosEncryptionAsyncClientconstructor, append the encryption SDK suffix viaCosmosBridgeInternal.getAsyncDocumentClient().appendUserAgentSuffix()deleteAllItemsByPartitionKeyAPI inCosmosEncryptionAsyncContainerandCosmosEncryptionContainer— the core SDK API has been public, but the encryption wrappers were still package-privateazure-cosmos:
appendUserAgentSuffix(String)method toAsyncDocumentClientinterface andRxDocumentClientImpl— appends to the existingUserAgentContainersuffix, preserving any customer-set suffixResulting User Agent
Why This Approach
The encryption SDK takes an already-built
CosmosAsyncClient— it doesn't own theCosmosClientBuilder. Unlike Spark/Kafka/Spring which callCosmosClientBuilder.userAgentSuffix()before building, we need to append to theUserAgentContainerafter construction. This is non-breaking — existing customers get tracking automatically with no code changes.Testing
CosmosEncryptionAsyncClientUnitTest:encryptionClientAppendsUserAgentSuffix— verifiesappendUserAgentSuffixis called with the correct suffix during constructionencryptionUserAgentSuffixContainsVersionInfo— verifies properties file is loaded and suffix format is correctencryptionClientHandlesAppendFailureGracefully— verifies client construction succeeds even if UA append failsUserAgentContainerTest:appendUserAgentSuffix— verifies suffix append behavior with empty and existing suffixes