DRIVERS-719 OpenTelemetry specification #1826

nhachicha · 2025-08-08T16:04:07Z

DRIVERS-719

Update schema to 1.26
Added invalid test to unified test runner
Added nominal valid tests for the 3 tracing grouping (Operation, Cursor and Transaction)
Update description of the new field observeTracingMessages and expectTracingMessages
Merge back the draft spec into this

…logy. Adding toplogy requirements for transaction tests

source/open-telemetry/open-telemetry.md

source/unified-test-format/tests/invalid/expectedTracingSpans-spanMalformedMissingName.yml

source/unified-test-format/tests/invalid/expectedTracingSpans-spanMalformedTagsMustBeObject.yml

jmikola · 2025-08-14T00:34:23Z

source/unified-test-format/unified-test-format.md

+        - `enableCommandPayload`: Optional boolean. When set to `true`, enables capturing of command payload details in
+            tracing spans.
+            - If `true`, the test runner SHOULD capture detailed command payload information in tracing spans.
+            - If `false` or omitted, the test runner SHOULD exclude command payload details.


I realize this impacts the test runner, but should it also refer to configuring the MongoClient to enable tracing?

This point is similar to #1826 (comment) ?
This option is both configured via the test runner and should be available to toggle on/off via MongoClient. This should be covered by a prose test 👍

Prose test added

Co-authored-by: Jeremy Mikola <[email protected]>

…TracingMessages-additionalProperties.yml Co-authored-by: Jeremy Mikola <[email protected]>

…spanMalformedTagsMustBeObject.yml Co-authored-by: Jeremy Mikola <[email protected]>

…TracingMessages-additionalPropertyType.yml Co-authored-by: Jeremy Mikola <[email protected]>

…missingPropertySpans.yml Co-authored-by: Jeremy Mikola <[email protected]>

…spanMalformedMissingName.yml Co-authored-by: Jeremy Mikola <[email protected]>

…spanMalformedTagsMustBeObject.yml Co-authored-by: Jeremy Mikola <[email protected]>

…summary with examples - Adding test for abortTransaction - Renaming transaction test to core_api

source/open-telemetry/open-telemetry.md

ShaneHarvey · 2025-09-10T17:02:11Z

source/open-telemetry/open-telemetry.md

+- **MongoClient Level**: Drivers SHOULD provide a configuration option for `MongoClient`'s Configuration/Settings that
+    enables or disables tracing for operations and commands executed with this client. This option MUST override
+    settings on higher levels. This configuration can be implemented with a `MongoClient` option, for example,
+    `tracing.enabled`.


Agreed. We usually call out if an option should be URI, MongoClient settings, or both. Like for versioned api:
https://github.com/mongodb/specifications/blob/master/source/versioned-api/versioned-api.md#no-uri-options

Also can you clarify how tracing.enabled is supposed to be translated into code? Is it MongoClient(tracing=True), MongoClient(tracing="enabled"), or something else?

source/open-telemetry/open-telemetry.md

ShaneHarvey · 2025-09-10T17:25:46Z

source/open-telemetry/open-telemetry.md

+| `abortTransaction`       | [tests/transaction/transaction.yml](tests/transaction/transaction.yml)               |
+| `createCollection`       | [tests/transaction/create_collection.yml](tests/operation/create_collection.yml)     |
+| `createIndexes`          | [tests/transaction/create_indexes.yml](tests/operation/create_indexes.yml)           |
+| `createView`             | [tests/transaction/create_view.yml](tests/operation/create_view.yml)                 |


createView is not a spec method. I don't think it should be included here or in the unified tests.

It's a fair point, my understanding is that some operations predate the spec ex createView defined in https://jira.mongodb.org/browse/DRIVERS-309 or createCollection only defined in unified tests. To your point in #1826 (comment) We should aim to cover the majority of operations that will help the developer trace and troubleshoot their application

So are we going to remove createView here? Or mention that it's not standard?

It's included (with its corresponding test) https://github.com/mongodb/specifications/blob/DRIVERS-719/source/open-telemetry/open-telemetry.md#covered-operations 👍

The problem is that createView doesn't exist in any specs. I don't think this PR should introduce it as if it's a spec method that exists in all drivers.

I removed tests for the createView, and the row in this table.

source/open-telemetry/open-telemetry.md

jmikola · 2025-09-12T12:44:14Z

source/open-telemetry/open-telemetry.md

+- **MongoClient Level**: Drivers SHOULD provide a configuration option for `MongoClient`'s Configuration/Settings that
+    enables or disables tracing for operations and commands executed with this client. This option MUST override
+    settings on higher levels. This configuration can be implemented with a `MongoClient` option, for example,
+    `tracing.enabled`.


@ShaneHarvey: thanks for bringing up the typing. If this really is just a boolean type, I think tracing or enableTracing (more active language than tracingEnabled) with a default value of false would be most consistent with other driver option names in PHP. But since these aren't URI options there should be more naming flexibility available for drivers.

It looks like @comandeo-mongo is talking about this in a comment below, too: https://github.com/mongodb/specifications/pull/1826/files#r2339648026

source/open-telemetry/open-telemetry.md

source/open-telemetry/tests/cursor/cursor.yml

source/open-telemetry/tests/operation/aggregate.yml

source/open-telemetry/tests/operation/atlas_search.yml

Co-authored-by: Jeremy Mikola <[email protected]>

source/open-telemetry/open-telemetry.md

jmikola · 2025-09-18T17:00:37Z

source/open-telemetry/open-telemetry.md

+- **MongoClient Level**: Drivers SHOULD provide a configuration option for `MongoClient`'s Configuration/Settings that
+    enables or disables tracing for operations and commands executed with this client. This option MUST override
+    settings on higher levels. This configuration can be implemented with a `MongoClient` option, for example,
+    `tracing.enabled`.


@nhachicha: Do you want to chime in here?

source/open-telemetry/open-telemetry.md

jmikola · 2025-09-18T17:04:53Z

source/open-telemetry/open-telemetry.md

+
+Drivers MUST take care to avoid exposing sensitive information (e.g. authentication credentials) in traces.
+
+## Future Work


@comandeo-mongo: Did you want to add a concise mention of "query parameterization" under this section? Doesn't need to be explained in detail, but just something to capture our original exchange in the earlier comment thread, which you can resolve.

Added some clarification, I hope I understand correctly what you suggested.

ShaneHarvey · 2025-09-18T17:51:36Z

source/open-telemetry/open-telemetry.md

 | `db.mongodb.server_connection_id` | `int64`  | Server connection id                                                                                                                                     | Required if available        |
 | `db.mongodb.driver_connection_id` | `int64`  | Local connection id                                                                                                                                      | Required if available        |
 | `db.query.text`                   | `string` | Database command that was sent to the server. Content should be equivalent to the `document` field of the CommandStartedEvent of the command monitoring. | Conditional                  |
 | `db.mongodb.cursor_id`            | `int64`  | If a cursor is created or used in the operation                                                                                                          | Required if available        |
+| `db.mongodb.lsid`                 | `string` | Logical session id                                                                                                                                       | Required is available        |
+| `db.mongodb.txn_number`           | `int64`  | Transaction number                                                                                                                                       | Required is available        |


for lsid and txn_number: is -> if

Fixed, thanks!

ShaneHarvey · 2025-09-18T17:56:20Z

source/open-telemetry/open-telemetry.md

+##### Exceptions
+
+If the driver operation fails with an exception, drivers MUST record an exception to the current operation span. When
+recording an exception, drivers SHOULD add the following attributes to the span, when the content for the attribute if


This typo still exists.

ShaneHarvey · 2025-09-18T17:58:22Z

source/open-telemetry/open-telemetry.md

+| `abortTransaction`       | [tests/transaction/transaction.yml](tests/transaction/transaction.yml)               |
+| `createCollection`       | [tests/transaction/create_collection.yml](tests/operation/create_collection.yml)     |
+| `createIndexes`          | [tests/transaction/create_indexes.yml](tests/operation/create_indexes.yml)           |
+| `createView`             | [tests/transaction/create_view.yml](tests/operation/create_view.yml)                 |


The problem is that createView doesn't exist in any specs. I don't think this PR should introduce it as if it's a spec method that exists in all drivers.

nhachicha added 5 commits July 11, 2025 18:57

added first tracing tests

97d8a5b

using unsetOrMatches for txNumber, since it's not set for single topo…

c82a6a2

…logy. Adding toplogy requirements for transaction tests

updating tests

61270d6

Tests and schema update for the upcoming Otel spec

581faa1

Merge branch 'nh/tracing'

c447d10

nhachicha self-assigned this Aug 8, 2025

nhachicha and others added 5 commits August 8, 2025 16:05

Update generated files

3a578ee

update schema to latest (1.26)

dbb1a9c

update tests

29e25a1

DRIVERS-719 OpenTelementry specification

f801d78

Cursor operations

9d66a8a

nhachicha changed the title ~~OpenTelemetry~~ DRIVERS-719 OpenTelementry specification Aug 8, 2025

nhachicha assigned comandeo-mongo Aug 8, 2025

nhachicha mentioned this pull request Aug 8, 2025

DRIVERS-719 OpenTelementry specification #1821

Closed

3 tasks

GromNaN reviewed Aug 8, 2025

View reviewed changes

source/open-telemetry/open-telemetry.md Outdated Show resolved Hide resolved

source/open-telemetry/open-telemetry.md Show resolved Hide resolved

nhachicha added 6 commits August 9, 2025 16:54

update doc

269221c

moved tests under open-telemtry directroy

452696d

Fixing formatting

9f05c59

update formatting using pre-commit mdformat

0523751

Adding Test README

8466c1b

Adding retries test, fixing duplicate exception tag

18ad723

jmikola reviewed Aug 14, 2025

View reviewed changes

nhachicha and others added 8 commits August 14, 2025 17:48

Update source/open-telemetry/open-telemetry.md

04b947a

Co-authored-by: Jeremy Mikola <[email protected]>

Update source/open-telemetry/open-telemetry.md

88c7be0

Co-authored-by: Jeremy Mikola <[email protected]>

Update source/unified-test-format/tests/invalid/entity-client-observe…

ced82eb

…TracingMessages-additionalProperties.yml Co-authored-by: Jeremy Mikola <[email protected]>

Update source/unified-test-format/tests/invalid/expectedTracingSpans-…

f1804c3

…spanMalformedTagsMustBeObject.yml Co-authored-by: Jeremy Mikola <[email protected]>

Update source/unified-test-format/tests/invalid/entity-client-observe…

03d4e3c

…TracingMessages-additionalPropertyType.yml Co-authored-by: Jeremy Mikola <[email protected]>

Update source/unified-test-format/tests/invalid/expectedTracingSpans-…

3c69ed5

…missingPropertySpans.yml Co-authored-by: Jeremy Mikola <[email protected]>

Update source/unified-test-format/tests/invalid/expectedTracingSpans-…

240d009

…spanMalformedMissingName.yml Co-authored-by: Jeremy Mikola <[email protected]>

Update source/unified-test-format/tests/invalid/expectedTracingSpans-…

6a4d217

…spanMalformedTagsMustBeObject.yml Co-authored-by: Jeremy Mikola <[email protected]>

nhachicha requested review from a team as code owners September 10, 2025 12:24

nhachicha requested review from alcaeus, jmikola, GromNaN and blink1073 and removed request for a team and blink1073 September 10, 2025 12:24

- Clarifying rules for db.namespace, db.collection.name and db.query.…

52974c0

…summary with examples - Adding test for abortTransaction - Renaming transaction test to core_api

ShaneHarvey requested changes Sep 10, 2025

View reviewed changes

jmikola reviewed Sep 15, 2025

View reviewed changes

comandeo-mongo and others added 6 commits September 16, 2025 10:24

Update source/open-telemetry/open-telemetry.md

00c1dc3

Co-authored-by: Jeremy Mikola <[email protected]>

Respond to code review remarks

cafe19c

Update source/open-telemetry/tests/operation/atlas_search.yml

99f7ed3

Co-authored-by: Jeremy Mikola <[email protected]>

Tests formating

50966dd

Merge remote-tracking branch 'origin/master' into DRIVERS-719

1ca2881

Fix linting

39863b0

nhachicha force-pushed the DRIVERS-719 branch from 1a4c85c to 39863b0 Compare September 17, 2025 11:57

kevinAlbs changed the title ~~DRIVERS-719 OpenTelementry specification~~ DRIVERS-719 OpenTelemetry specification Sep 17, 2025

nhachicha and others added 6 commits September 18, 2025 10:33

Adding prose tests description

92bea10

Folding find_reties test under find

e2d5ead

Clarify configuration options

80ae25f

Address code review remarks

682d6b8

Add tests for client configuration

5fa16fa

Remove non compliats tests

0895547

jmikola reviewed Sep 18, 2025

View reviewed changes

ShaneHarvey requested changes Sep 18, 2025

View reviewed changes

comandeo-mongo added 3 commits September 18, 2025 19:03

Fix typos

d8ecaf0

Address code review remarks

c9f1e94

Clarify query parametrization

b6e0eb9


		Drivers MUST take care to avoid exposing sensitive information (e.g. authentication credentials) in traces.

		## Future Work

DRIVERS-719 OpenTelemetry specification #1826

Are you sure you want to change the base?

DRIVERS-719 OpenTelemetry specification #1826

Uh oh!

Conversation

nhachicha commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nhachicha commented Aug 8, 2025 •

edited

Loading