PYTHON-5903 Retry attempts should share a single stable operation_id

[shrey-mongo]

PYTHON-5903: Retry attempts should share a single stable operation_id

Changes in this PR

Command-monitoring events carry an operation_id to correlate the events of one logical operation. For single-document CRUD and cursor operations, each retry attempt got a different operation_id (it defaulted to the per-attempt request_id), so consumers couldn't group a retried operation's events. Bulk writes already shared one across batches.

• _ClientConnectionRetryable mints the operation_id once per logical operation.
• New internal pymongo/_op_id.py module holds an OP_ID ContextVar and an _OpIdContext context manager. _write/_read enter it around each attempt's command execution, so every attempt publishes the same id; on exit the previous value is restored.
• command_runner._run_command falls back to OP_ID.get() when no explicit op_id is passed (bulk write pass their own), and threads it to the publish_command_* events and command logs.
• Commands outside an operation's scope (handshake/auth during connection establishment, killCursors, pinned-cursor getMores, background tasks) read the default None and keep falling back to request_id.
• _handle_reauth suppresses the in-flight id (_OpIdContext(None)) while re-authenticating, then restores it for the retried command.
• AsyncPeriodicExecutor._run() resets OP_ID alongside _csot.reset_all() so executor tasks don't inherit an operation's id from their spawning context.

Test Plan

• New test/asynchronous/test_operation_id_retry.py forces multiple retries via a failCommand failpoint across a read/write matrix and asserts all command events share one operation_id
• also unit-tests the reauth guard (id suppressed during auth, restored for the retry).
• Extended test_async_contextvars_reset.py to assert OP_ID is reset inside executor tasks, alongside the CSOT vars.
• Ran the new tests plus the existing command-monitoring and retryable reads/writes suites against a single-node replica set which passed.

Checklist

Checklist for Author

• Did you update the changelog (if necessary)?
• Is there test coverage?
• Is any followup work tracked in a JIRA ticket? If so, add link(s).

Checklist for Reviewer

• Does the title of the PR reference a JIRA Ticket?
• Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
• Is all relevant documentation (README or docstring) updated?

[NoahStapp]

Please fill out the pull request template completely.

[Copilot]

Pull request overview

This PR ensures command-monitoring operation_id remains stable across retry attempts for retryable reads/writes and relevant cursor operations, improving APM correlation for a single logical operation.

Changes:

• Mint a single per-operation operation_id in the retryable-operation wrapper and stamp it onto the checked-out connection for each attempt.
• Thread the connection’s op_id through pool/server command execution into command_runner so published command-monitoring events use it.
• Add sync + async integration tests that force multiple retries via failCommand and assert all related command events share one operation_id.

Reviewed changes

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

Show a summary per file

File	Description
tools/synchro.py	Registers the new test file in the synchro conversion list.
test/test_operation_id_retry.py	Sync integration coverage asserting operation_id stability across retries (and no retry for non-retryable multi-writes).
test/asynchronous/test_operation_id_retry.py	Async equivalent of the retry operation_id stability tests.
pymongo/synchronous/server.py	Passes conn.op_id into cursor command execution for APM publishing.
pymongo/synchronous/pool.py	Adds Connection.op_id, forwards it into run_command, and clears it on check-in.
pymongo/synchronous/mongo_client.py	Mints/stabilizes per-operation ids across retries and stamps them on checked-out connections.
pymongo/synchronous/command_runner.py	Accepts/threads op_id through run_command / run_cursor_command into _run_command.
pymongo/asynchronous/server.py	Async counterpart: passes conn.op_id for cursor command execution.
pymongo/asynchronous/pool.py	Async counterpart: adds/forwards/clears op_id on connections.
pymongo/asynchronous/mongo_client.py	Async counterpart: stable per-operation id and per-attempt stamping onto connections.
pymongo/asynchronous/command_runner.py	Async counterpart: threads op_id through command execution to APM event publishing.

[shrey-mongo]

Updated description to include full template

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.72727% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pymongo/_op_id.py	93.75%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[NoahStapp]

There are merge conflicts, please resolve.

[shrey-mongo]

I fixed the merge conflict and the typing error that was causing the workflow to fail

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

[aclark4life]

Checklist

Checklist for Author

• Did you update the changelog (if necessary)?

I'm not sure if we need a changelog entry but maybe you intended to add one? May as well add one e.g.

Command monitoring events and command log messages for a single logical
  operation now share one stable ``operation_id`` across all of its retry
  attempts, so consumers can correlate a retried operation's events. As a
  result, ``operation_id`` is no longer equal to the per-attempt ``request_id``
  for these operations.

[shrey-mongo]

You're right, updated the changelog.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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