Skip to content

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

Closed
blink1073 wants to merge 12 commits into
masterfrom
DRIVERS-3598
Closed

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

Conversation

@blink1073

@blink1073 blink1073 commented Aug 12, 2026

Copy link
Copy Markdown
Owner

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).

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

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 closed this Aug 12, 2026
@blink1073 blink1073 reopened this Aug 12, 2026
@blink1073 blink1073 closed this Aug 12, 2026
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