Skip to content

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

Open
blink1073 wants to merge 12 commits into
mongodb:masterfrom
blink1073:DRIVERS-3598
Open

DRIVERS-3598 Specify and test getMore span nesting in the OpenTelemetry spec#1973
blink1073 wants to merge 12 commits into
mongodb:masterfrom
blink1073:DRIVERS-3598

Conversation

@blink1073

@blink1073 blink1073 commented Aug 12, 2026

Copy link
Copy Markdown
Member

DRIVERS-3598

Please complete the following before merging:

  • Is the relevant DRIVERS ticket in the PR title?

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.

Changes

  • 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.
  • 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 covering the nesting and both cursor_id outcomes with ignoreExtraSpans: false, plus prose tests 3 and 4 for what the unified format cannot express.
  • Unified test format: ignoreExtraSpans applies at every level of the span tree, without which the tests' negative assertion is not enforceable.

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 tests, 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.

Testing

Python implementation: mongodb/mongo-python-driver#2964

get_more.json caught a real divergence there on its first run: PyMongo used a single cursor-lifetime operation span, the reading this PR rules out, and passes unmodified now that the driver conforms. Prose tests 3 and 4 are implemented and passing.

@blink1073
blink1073 marked this pull request as ready for review August 12, 2026 12:53
@blink1073
blink1073 requested review from a team as code owners August 12, 2026 12:53
@blink1073
blink1073 requested review from jyemin and mdb-ad August 12, 2026 12:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant