DRIVERS-3598 Specify and test getMore span nesting in the OpenTelemetry spec

[blink1073]

Please complete the following before merging:

• Is the relevant DRIVERS ticket in the PR title?

• Update changelog.
• Test changes in at least one language driver.
• Test these changes against all server versions and topologies (including standalone, replica set, and sharded
  clusters). PyMongo implementation: PYTHON-5993 Add OpenTelemetry operation spans for cursor getMores mongo-python-driver#2994 — Evergreen patch, 24/24
  tasks green across standalone, replica set and sharded cluster:
  https://spruce.corp.mongodb.com/version/6a84b1a8f492900007096dd6

---

Context

Command spans must nest under "the corresponding driver operation span", which is unambiguous only while an operation sends a single command. For a cursor, the spec never said which operation span a getMore belongs to, and no fixture exercised getMore — so both readings passed the suite, and db.mongodb.cursor_id was asserted absent in all 25 places it appeared.

That ambiguity was not hypothetical. PyMongo had implemented one reading (a single operation span covering a cursor's whole lifetime), and the new fixture caught it on its first run.

Changes

Nesting. A caller-driven getMore gets its own operation span, sibling to the cursor-creating operation's span. Driver-internal iteration, where one public API call drains the cursor itself, creates no additional operation spans. No span is scoped to a cursor's lifetime, so a cursor that is never exhausted leaves nothing unfinished. A change-stream resume ends the failed getMore operation span rather than extending it. A cursor iterated inside a transaction nests under the withTransaction span or the pseudo operation transaction span, depending on which API started it.

db.mongodb.cursor_id. Raised from SHOULD to MUST and added to operation spans. It holds the id the driver sent for a getMore, even when that reply returns 0. It is omitted rather than emitted as 0 for a cursor-creating command that leaves no cursor open, and omitted for commands that may operate on several cursors at once.

Tests. operation/get_more.yml covers the nesting and both cursor_id outcomes. transaction/get_more.yml covers a cursor iterated inside a core-API transaction. Both use ignoreExtraSpans: false. Prose tests 3 and 4 cover the two things the unified format cannot express: that cursor_id holds the id sent rather than the 0 returned ($$type cannot exclude 0), and the convenient transaction API's callback.

Unified test format. ignoreExtraSpans applies at every level of the span tree. Without this, the negative assertion in operation/get_more.yml — that the getMore is not nested under find — is not enforceable by a conformant runner.

Two decisions worth a second opinion

Neither is stated in the design document, so please confirm rather than assume:

1. Span name getMore <db>.<collection>, following the existing convention of naming operation spans after commands rather than public-API methods. Naming it after the driver's iteration method would vary per driver and make the test unassertable cross-driver.
2. Cursor id 0 omitted rather than emitted as a literal 0. This matches the existing find.yml and aggregate.yml fixtures, which omit cursor_id on commands that exhaust in the first batch, and OpenTelemetry's convention of omitting unavailable attributes rather than encoding a sentinel.

Verification

Both fixtures pass against PyMongo, transaction/get_more.yml unchanged from the first run. Prose tests 3 and 4 are implemented there. The generated JSON is byte-identical to a fresh run of this repository's generator, and both fixtures are schema-valid against their declared schema version 1.27.

AI disclosure

Drafted with Claude Code (Claude Opus 5 and Sonnet 5). Reviewed by the human author before opening.

[comandeo-mongo]

Suggested change

	`withTransaction` callback nests into the `withTransaction` span.
	`withTransaction` callback nests into the `withTransaction` span; a cursor iterated inside a transaction created using core transactions api nests into the pseudo operation `transaction` span.

[blink1073]

Fixed

[comandeo-mongo]

Would it be better to implement this test as a unified? If we do not use the convenient transaction api, it seems to be possible. Something like this:

operations:
  - { name: startTransaction, object: *session0 }
  - name: createFindCursor
    object: *collection0
    arguments: { filter: {}, batchSize: 2, session: *session0 }
    saveResultAsEntity: &cursor0 cursor0
  - { name: iterateUntilDocumentOrError, object: *cursor0, expectResult: { _id: 1 } }
  - { name: iterateUntilDocumentOrError, object: *cursor0, expectResult: { _id: 2 } }
  - { name: iterateUntilDocumentOrError, object: *cursor0, expectResult: { _id: 3 } }
  - { name: commitTransaction, object: *session0 }

expectTracingMessages:
  - client: *client0
    ignoreExtraSpans: false
    spans:
      - name: transaction
        attributes: { db.system.name: mongodb }
        nested:
          - name: find transaction-get-more.test
          - name: getMore transaction-get-more.test
          - name: commitTransaction admin

If we want to test withTransaction explicitly, then we need a prose test.

[blink1073]

I added a unified test and clarified the intent of the prose test

[comandeo-mongo]

Great work, thank you!

[blink1073]

@paulinevos, can you please review the changes to unified-test-format.md and approve on behalf of dbx-spec-maintainers-unified-test-format?