[JAVA-6159] Micrometer feedback by nhachicha · Pull Request #1940 · mongodb/mongo-java-driver

nhachicha · 2026-04-13T11:03:34Z

AI Usage Summary

Claude-Caude with Opus 4.6 1M Model

What AI did well

Research & synthesis — Fetched and synthesized feedback from 3 external sources (Jonatan's gist, Spring Boot issue, Spring Data ContextProviderFactory) into a structured plan
Test-first approach — Wrote failing tests before implementing fixes, following the user's guidance
Mechanical refactoring — Renaming imports, splitting enums, updating call sites across multiple files
Cross-referencing open source — Researched Lettuce, R2DBC, and Spring WebFlux patterns for reactive context propagation
Explaining concepts — Broke down Micrometer Observation vs Tracing API, scope mechanics, Reactor context propagation

Where the user corrected or pushed back

Situation	What happened
Reducing tag duplication	AI implemented a `CommonLowCardinalityKeyNames` refactor; user asked for suggestion only, not implementation — had to revert
Removing imperative tagging	AI initially kept both imperative tags AND context fields (duplication); user spotted the redundancy and pushed to remove all imperative calls
`tagHighCardinality` in InternalStreamConnection	AI claimed the remaining imperative calls were necessary; user pointed out they could go through `getMongodbContext()` instead
Scope in TransactionSpan	AI put `openScope()` in the constructor (shared by sync+reactive); user asked why scope is public — led to discovering it should only be called from sync
Reactive context propagation	AI spent multiple iterations trying `contextWrite`, `contextCapture`, `AtomicReference` patterns — all failed due to `Mono.from(subscriber -> ...)` pattern. User questioned
each attempt
`Hooks.enableAutomaticContextPropagation`	AI assumed version alignment would fix it; user actually tried it and reported the hang, forcing deeper investigation
Reactive driver refactor scope	After extensive async work, user asked if `context-propagation=auto` alone would suffice — AI confirmed, user decided to stash reactive changes and keep it simple
commit transaction reactive failure	AI tried to skip the test; user rejected and demanded root cause investigation — led to finding the OTel bridge scope leak from `TransactionSpan` constructor
Modifying stopped observations	AI removed parent cursor_id mutation; user showed Zipkin traces proving it broke nesting — led to reverting, then user suggested removing it properly since parenting
works via `operationSpan.context()`
Test validation gaps	User commented out `contextWrite` and `contextCapture` to prove tests still passed — exposed that tests weren't actually validating the code they claimed to test
CheckStyle/SpotBugs	AI fixed checkstyle issues; user asked to revert since they only wanted suggestions, not implementation

The driver used a single observation name ("mongodb") for both operation-level and command-level spans, which have different sets of low-cardinality tag keys. Prometheus requires all meters sharing a name to have identical tag key sets, causing the second observation type to be silently dropped. Split MongodbObservation.MONGODB_OBSERVATION into MONGODB_OPERATION (name "mongodb.operation") and MONGODB_COMMAND (name "mongodb.command"), each declaring its own low-cardinality key set. Updated Tracer and TracingManager to pass the observation type through span creation.

Connection IDs, cursor IDs, session IDs, transaction numbers, and exception details were tagged as low-cardinality, causing unbounded Prometheus metric cardinality since their values change per-connection, per-cursor, or per-error. Moved CLIENT_CONNECTION_ID, SERVER_CONNECTION_ID, CURSOR_ID,TRANSACTION_NUMBER, SESSION_ID, EXCEPTION_MESSAGE, EXCEPTION_TYPE, and EXCEPTION_STACKTRACE from CommandLowCardinalityKeyNames to HighCardinalityKeyNames so they appear only in traces, not in metrics. Added tagHighCardinality(KeyValue) and tagHighCardinality(KeyValues) to the Span interface to support string-valued high-cardinality tags alongside the existing BsonDocument overload.

The query text max length configuration constant was stored in every Observation.Context and extracted back in the MicrometerSpan constructor. This value never changes between observations and is not output as any signal. Pass it directly via constructor parameter instead.

Observations were created with Micrometer's generic SenderContext, preventing users from filtering or customizing MongoDB observations by context type. This blocks the ObservationConvention pattern that Spring Boot needs for tag alignment. Introduced MongodbContext extending SenderContext<Object> with Kind.CLIENT, giving users a MongoDB-specific type to register ObservationHandler<MongodbContext> or ObservationConvention<MongodbContext> instances scoped to only MongoDB observations.

…f TracingManager Replaced all imperative tagLowCardinality/tagHighCardinality calls with a convention-based approach. TracingManager and InternalStreamConnection now populate domain fields on MongodbContext, and DefaultMongodbObservationConvention reads those fields at stop time to produce the final key-values. This decouples tag naming from span creation, enabling users to register a GlobalObservationConvention<MongodbContext> to customize tag names for their environment (e.g. Spring Boot tag alignment with their existing DefaultMongoCommandTagsProvider). Added domain fields to MongodbContext: observationType, commandName, databaseName, collectionName, serverAddress, connectionId, cursorId, transactionNumber, sessionId, queryText, responseStatusCode. Removed tagLowCardinality/tagHighCardinality from the Span interface as they are no longer used.

Update attribute name for OpenTelemetry

The driver called observation.start()/stop() but never openScope()/ closeScope(). Without scopes, registry.getCurrentObservation() returned null during MongoDB operations, breaking context propagation for any downstream code (Spring interceptors, user observations, MDC logging). For example, in withTransaction, a user observation created inside the callback would attach to the Spring HTTP parent instead of the MongoDB transaction span, because the transaction observation was never made "current" on the thread. Added openScope()/closeScope() to the Span interface with scope lifecycle management in MongoClusterImpl (operation spans), InternalStreamConnection (command spans), and TransactionSpan.

When a getMore command arrived, the cursor_id was being set on the parent operation span's MongodbContext even though the parent observation was already stopped. Modifying an observation after stop() is undefined behavior in Micrometer

Copilot

Pull request overview

Refactors Micrometer-based tracing to align better with OpenTelemetry/Micrometer conventions by separating operation vs command observations, moving tag production into an ObservationConvention, and introducing explicit span scope management in sync execution paths.

Changes:

Split MongoDB observations into distinct operation- and command-level observation types to avoid tag-keyset collisions (e.g., Prometheus restrictions).
Replace imperative tagging with a MongodbContext + DefaultMongodbObservationConvention that derives tags from populated domain fields.
Add explicit openScope() / closeScope() lifecycle handling for spans in sync execution code paths and update unified test modifications accordingly.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTestModifications.java	Updates unified test skip rules for OpenTelemetry/Micrometer-related specs.
driver-sync/src/test/functional/com/mongodb/client/unified/Entities.java	Minor formatting adjustment in Micrometer observability settings setup.
driver-sync/src/test/functional/com/mongodb/client/observability/SpanTree.java	Updates test tag-key imports to match new low/high-cardinality key enums.
driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java	Opens/closes span scope around sync operation execution.
driver-sync/src/main/com/mongodb/client/internal/ClientSessionImpl.java	Opens transaction-span scope when starting a transaction (sync).
driver-core/src/main/com/mongodb/internal/observability/micrometer/TransactionSpan.java	Ensures transaction span scope is closed before ending in finalization paths; adds `openScope()` API.
driver-core/src/main/com/mongodb/internal/observability/micrometer/TracingManager.java	Switches span creation to operation vs command observation types and populates `MongodbContext` fields for conventions.
driver-core/src/main/com/mongodb/internal/observability/micrometer/Tracer.java	Updates tracer API to accept an observation type when creating spans.
driver-core/src/main/com/mongodb/internal/observability/micrometer/Span.java	Replaces tag APIs with scope management + query-text setting + context access.
driver-core/src/main/com/mongodb/internal/observability/micrometer/MongodbObservation.java	Splits key names into operation vs command low-cardinality sets and reorganizes high-cardinality keys.
driver-core/src/main/com/mongodb/internal/observability/micrometer/MongodbContext.java	Introduces a MongoDB-specific Micrometer `SenderContext` to hold domain fields used by conventions.
driver-core/src/main/com/mongodb/internal/observability/micrometer/MicrometerTracer.java	Uses `MongodbContext`, registers the default convention, and implements new `Span` API.
driver-core/src/main/com/mongodb/internal/observability/micrometer/DefaultMongodbObservationConvention.java	New default global convention that emits tags from `MongodbContext` fields (including errors).
driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnection.java	Uses new `Span` API, populates query text/status code via `MongodbContext`, and opens/closes scope around command spans.
config/checkstyle/suppressions.xml	Moves the `printStackTrace` suppression to the new convention class.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Move openScope() calls after code that can throw to prevent scope leaks on early exceptions in MongoClusterImpl (binding creation) and InternalStreamConnection (command setup). Update createTracingSpan Javadoc to reflect convention-based tagging.

…ntion - Renamed MongodbContext to MongodbObservationContext and moved it along with DefaultMongodbObservationConvention to the public package com.mongodb.observability.micrometer - Added observationConvention() to MicrometerObservabilitySettings so users can provide a custom convention - Added testCustomObservationConvention to AbstractMicrometerProseTest validating that a user-provided convention fully controls tag output

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ervationContext

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

rozza

Its getting there - I've reiterated the copilot blockers.

rozza · 2026-04-20T14:41:35Z

    @Override
-    public Span nextSpan(final String name, @Nullable final TraceContext parent, @Nullable final MongoNamespace namespace) {
-        Observation observation = getObservation(name);
+    public Span nextSpan(final MongodbObservation observationType, final String name,


This leaks the internal MongodbObservation which means we should either have an alternative enum or we move that enum into the public API.

Can that be made public?

Fixed by moving MongodbObservation to com.mongodb.observability.micrometer.

…ction observation type - Include maxQueryTextLength in equals/hashCode - Move MongodbObservation enum to public package - Remove unused import, use FQN in Javadoc - Add MONGODB_TRANSACTION observation type with dedicated key set - Wrap span lifecycle in outer try/finally for binding failures - Reset ENV_OBSERVABILITY_ENABLED in custom convention test - Add MongodbObservation to Scala API test exclusions

…n the nested try/finally approach

rozza

Looking good - a couple of nits (more belt and braces).

Main change is to handle context.getObservationType() == null.

rozza · 2026-04-21T09:55:31Z

+@Beta(Reason.CLIENT)
+public class MongodbObservationContext extends SenderContext<Object> {
+
+    private MongodbObservation observationType;


Suggested change

private MongodbObservation observationType;

@Nullable

private MongodbObservation observationType;

rozza · 2026-04-21T09:58:13Z

+        if (context.getObservationType() == MongodbObservation.MONGODB_TRANSACTION) {
+            return KeyValues.of(MongodbObservation.TransactionLowCardinalityKeyNames.SYSTEM.withValue("mongodb"));
+        } else if (context.getObservationType() == MongodbObservation.MONGODB_OPERATION) {
+            return getOperationLowCardinalityKeyValues(context);
+        } else {
+            return getCommandLowCardinalityKeyValues(context);
+        }


Handle null values for observationType

Suggested change

if (context.getObservationType() == MongodbObservation.MONGODB_TRANSACTION) {

return KeyValues.of(MongodbObservation.TransactionLowCardinalityKeyNames.SYSTEM.withValue("mongodb"));

} else if (context.getObservationType() == MongodbObservation.MONGODB_OPERATION) {

return getOperationLowCardinalityKeyValues(context);

} else {

return getCommandLowCardinalityKeyValues(context);

}

MongodbObservation observationType = context.getObservationType();

if (observationType == null) {

return KeyValues.empty();

} else if (observationType == MongodbObservation.MONGODB_TRANSACTION) {

return KeyValues.of(MongodbObservation.TransactionLowCardinalityKeyNames.SYSTEM.withValue("mongodb"));

} else if (observationType == MongodbObservation.MONGODB_OPERATION) {

return getOperationLowCardinalityKeyValues(context);

} else {

return getCommandLowCardinalityKeyValues(context);

}

rozza · 2026-04-21T10:05:30Z

+            if (span != null) {
+                span.openScope();
+            }
            try {


Code review tool flagged: if openScope() throws, binding (obtained at line 427) is never released because the finally block hasn't been entered. Consider moving span.openScope() inside the try block:

Suggested change

if (span != null) {

span.openScope();

}

try {

try {

if (span != null) {

span.openScope();

}

Not sure if its a realistic scenario or just belt and braces.

rozza · 2026-04-21T10:07:03Z

                    actualClientSession.getTransactionSpan(), operationContext, operation.getCommandName(), operation.getNamespace());
-            WriteBinding binding = getWriteBinding(actualClientSession, isImplicitSession(session));
-
+            if (span != null) {


Suggested change

if (span != null) {

try {

if (span != null) {

span.openScope();

}

return operation.execute(binding, operationContext);

Same scenario as above.

nhachicha self-assigned this Apr 13, 2026

nhachicha added 4 commits April 13, 2026 12:28

nhachicha force-pushed the nh/micrometer_spring_feedback branch from 9b4b0ad to bf91627 Compare April 14, 2026 09:48

nhachicha added 4 commits April 14, 2026 11:54

Fixes JAVA-6094

da4a3c1

Update attribute name for OpenTelemetry

Fixing tests

db5387c

nhachicha changed the title ~~WIP Micrometer feedback~~ [JAVA-6159] Micrometer feedback Apr 16, 2026

nhachicha marked this pull request as ready for review April 16, 2026 14:58

nhachicha requested a review from a team as a code owner April 16, 2026 14:58

nhachicha requested review from Copilot and rozza April 16, 2026 14:58

Copilot started reviewing on behalf of nhachicha April 16, 2026 16:33 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

nhachicha added 3 commits April 17, 2026 10:29

Bumping Micrometer APIs to @beta

31c4ce2

nhachicha requested a review from Copilot April 17, 2026 12:21

Copilot started reviewing on behalf of nhachicha April 17, 2026 12:21 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread ...-core/src/main/com/mongodb/observability/micrometer/DefaultMongodbObservationConvention.java

Comment thread ...-core/src/main/com/mongodb/observability/micrometer/DefaultMongodbObservationConvention.java

nhachicha requested a review from Copilot April 17, 2026 12:45

Copilot started reviewing on behalf of nhachicha April 17, 2026 12:45 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread ...-core/src/main/com/mongodb/observability/micrometer/DefaultMongodbObservationConvention.java Outdated

Comment thread driver-core/src/main/com/mongodb/observability/micrometer/MongodbObservationContext.java

nhachicha added 2 commits April 17, 2026 14:54

Add new public observability classes to Scala API test exclusions

777c326

Fix null-safety in DefaultMongodbObservationConvention and MongodbObs…

be3108e

…ervationContext

nhachicha requested a review from Copilot April 17, 2026 14:11

Copilot started reviewing on behalf of nhachicha April 17, 2026 14:56 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java

Comment thread driver-sync/src/main/com/mongodb/client/internal/ClientSessionImpl.java

nhachicha requested a review from Copilot April 17, 2026 15:34

Copilot started reviewing on behalf of nhachicha April 17, 2026 15:34 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/internal/observability/micrometer/TracingManager.java

Comment thread driver-core/src/main/com/mongodb/observability/micrometer/MicrometerObservabilitySettings.java

nhachicha requested a review from Copilot April 17, 2026 15:50

Copilot started reviewing on behalf of nhachicha April 17, 2026 15:50 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-sync/src/test/functional/com/mongodb/client/AbstractMicrometerProseTest.java

Comment thread driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java

nhachicha requested a review from Copilot April 17, 2026 17:03

Copilot started reviewing on behalf of nhachicha April 17, 2026 17:03 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/observability/micrometer/MicrometerObservabilitySettings.java

nhachicha requested a review from Copilot April 17, 2026 17:22

Copilot started reviewing on behalf of nhachicha April 17, 2026 17:22 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

nhachicha requested a review from Copilot April 17, 2026 19:18

Copilot started reviewing on behalf of nhachicha April 17, 2026 19:18 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/observability/micrometer/MongodbObservationContext.java

nhachicha requested a review from Copilot April 17, 2026 19:48

Copilot started reviewing on behalf of nhachicha April 17, 2026 19:49 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/observability/micrometer/MongodbObservationContext.java

nhachicha requested a review from Copilot April 17, 2026 19:58

Copilot started reviewing on behalf of nhachicha April 17, 2026 19:59 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/observability/micrometer/MicrometerObservabilitySettings.java

nhachicha requested a review from Copilot April 17, 2026 20:19

Copilot started reviewing on behalf of nhachicha April 17, 2026 20:19 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread ...-core/src/main/com/mongodb/observability/micrometer/DefaultMongodbObservationConvention.java Outdated

Comment thread driver-sync/src/test/functional/com/mongodb/client/AbstractMicrometerProseTest.java

rozza requested changes Apr 20, 2026

View reviewed changes

nhachicha added 2 commits April 20, 2026 15:52

moved span creation after getReadBinding/getWriteBinding. Simpler tha…

257516e

…n the nested try/finally approach

rozza reviewed Apr 21, 2026

View reviewed changes

	private MongodbObservation observationType;
	@Nullable
	private MongodbObservation observationType;

Conversation

nhachicha commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude-Caude with Opus 4.6 1M Model

What AI did well

Where the user corrected or pushed back

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!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

rozza left a comment

Choose a reason for hiding this comment

Uh oh!

nhachicha commented Apr 13, 2026 •

edited

Loading