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 and stamps it on the checked-out connection (conn.op_id) on every attempt
• Connection gains an op_id attribute, reset on check-in.
• pool.command and server.run_operation source op_id from the connection and pass it to command_runner.run_command / run_cursor_command, which thread it through to the publish_command_* events.

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; verifies non-retryable multi-writes don't retry.
• 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

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[NoahStapp]

This class needs to add the @async_client_context.require_failCommand_appName annotation to safely use appName.

[shrey-mongo]

Fixed

[NoahStapp]

This needs to be updated to use the new operation_id, if present.

[shrey-mongo]

Fixed

[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

[NoahStapp]

What's the purpose of this change?

[shrey-mongo]

It was needed to fix an untyped-decorator mypy error that was occurring in my test. This matches the signature of require_failCommand_fail_point.

[NoahStapp]

You don't need both the require_failCommand_fail_point and require_failCommand_appName annotations, the latter is a strict subset of the former.

[NoahStapp]

I don't think we want to track op_id on connections. It introduces more risk of accidental inclusion or staleness on operations like auth compared to explicitly passing it through each operation. What about passing op_id as a kwarg on Connection.command() and on _Query/_GetMore where operations are actually initiated?