Conversation
mongoKart
left a comment
mongoKart
left a comment
There was a problem hiding this comment.
lgtm w/ small suggestions!
| - Adds the ``maxAdaptiveRetries()`` method to | ||
| ``MongoClientSettings.Builder`` and the ``maxAdaptiveRetries`` |
There was a problem hiding this comment.
| - Adds the ``maxAdaptiveRetries()`` method to | |
| ``MongoClientSettings.Builder`` and the ``maxAdaptiveRetries`` | |
| - Adds the ``MongoClientSettings.Builder.maxAdaptiveRetries()`` method | |
| and the ``maxAdaptiveRetries`` |
| - Adds the ``enableOverloadRetargeting()`` method to | ||
| ``MongoClientSettings.Builder`` and the |
There was a problem hiding this comment.
| - Adds the ``enableOverloadRetargeting()`` method to | |
| ``MongoClientSettings.Builder`` and the | |
| - Adds the ``MongoClientSettings.Builder.enableOverloadRetargeting()`` method | |
| and the |
| control whether retries of a ``SystemOverloadedError`` attempt to | ||
| use a different server. The default value is ``false``. This | ||
| setting has no effect on sharded clusters. | ||
| - Adds the ``SystemOverloadedError`` and ``RetryableError`` error |
There was a problem hiding this comment.
| - Adds the ``SystemOverloadedError`` and ``RetryableError`` error | |
| - Adds the ``SystemOverloadedError`` and ``RetryableError`` |
| - Adds the ``MongoClientSettings.Builder.maxAdaptiveRetries()`` method | ||
| and the ``maxAdaptiveRetries`` connection string option, which configure | ||
| the maximum number of retry attempts for operations that fail with a | ||
| ``SystemOverloadedError``. The default value is ``2``. |
There was a problem hiding this comment.
...that fail with a
SystemOverloadedError...
- A command execution can fail with an error having the
SystemOverloadedErrorlabel, but it can't "fail withSystemOverloadedError", as currently formulated. - Both the
SystemOverloadedErrorand theRetryableErrorlabels must be present. See https://github.com/mongodb/mongo-java-driver/blob/ff74470144f9c5ea98a5ab0881edbbfb1be2ca80/driver-core/src/main/com/mongodb/MongoClientSettings.java#L503-L568 for the full details.
| - Adds the ``MongoClientSettings.Builder.maxAdaptiveRetries()`` method | ||
| and the ``maxAdaptiveRetries`` connection string option, which configure | ||
| the maximum number of retry attempts for operations that fail with a | ||
| ``SystemOverloadedError``. The default value is ``2``. |
There was a problem hiding this comment.
...the maximum number of retry attempts for operations...
Drivers retry commands, not operations (see https://github.com/mongodb/mongo-java-driver/blob/ff74470144f9c5ea98a5ab0881edbbfb1be2ca80/driver-core/src/main/com/mongodb/MongoClientSettings.java#L448-L470 and https://github.com/mongodb/mongo-java-driver/blob/ff74470144f9c5ea98a5ab0881edbbfb1be2ca80/driver-core/src/main/com/mongodb/MongoClientSettings.java#L475-L498), so the maxAdaptiveRetries client setting / connection string option controls the maximum number of retry attempts when executing a command and encountering an error having the SystemOverloadedError and the RetryableError labels (such errors are referred to as retryable overload errors).
For example, when executing the MongoCluster.bulkWrite operation, the driver may execute one or more bulkWrite commands, each followed by executing one or more getMore commands. If any of those command executions fails with a retryable overload error and is retried because of that, the maxAdaptiveRetries applies on a per-command basis, so if one of the bulkWrite command executions had maxAdaptiveRetries retry attempts, another bulkWrite command execution, or another getMore command execution may also have maxAdaptiveRetries retry attempts. And all of those are still part of the execution of a single MongoCluster.bulkWrite operation.
"operation" vs "command" (for your information; if possible, share / spread among other documentation authors)
The driver specifications often use the terms interchangeably, which is always incorrect.
- An operation is a driver API concept. It is initiated by calling API methods like
MongoCluster.listDatabases,MongoDatabase.runCommand,MongoColletion.deleteOne, etc; some API methods may initiate multiple operations, e.g.,GridFSBucket.uploadFromStream. Execution of an operation may involve executing multiple commands with different or same name (the first key in the BSON representation of a command), and execution of each command may involve multiple execution attempts: the first attempt, and the retry attempts. Each execution of an operation has its own ID, which is accessible via theCommandEvent.getOperationId(events caused by execution of all commands in an operation have the same "operation ID"). - A command is the server API concept (more specifically, MQL-level concept: https://www.mongodb.com/docs/manual/reference/command/). The driver encodes a command into a message of the MongoDB wire protocol (https://www.mongodb.com/docs/manual/reference/mongodb-wire-protocol/). Each execution attempt of a command has its own ID, which is accessible via the
CommandEvent.getRequestId(events caused by different execution attempts of the same command have different "request ID").
Retries:
- The driver is capable of idempotently retrying some commands. The idempotency key is the pair of
lsidandtxnNumber(see https://www.mongodb.com/docs/manual/reference/server-sessions/). So the driver retries at the command level. - An application does not fully construct commands, unless it executes them via the
runCommandoperation, but even then, it still can't properly specify the aforementioned idempotency key, nor is the information on when it is possible to idempotently retry a command (not all commands support that, not all servers support that, etc.) is necessarily part of the public contract. So an application, if it retries explicitly, can retry only at the operation level, which, in the most general case, may require reassessing the state of the DB after the previous operation failure.
P.S. The server internally, at least in some places (including the server logs), uses the term "operation" instead of "command".
P.P.S. In no way the above is intended as a flawless definition of what an operation and what a command is. It is merely an attempt to communicate to you the nature of what they are, to emphasize that they are definitely not the same thing, and to warn that you'll see the terms incorrectly used interchangeably almost everywhere.
| - Adds the ``MongoClientSettings.Builder.maxAdaptiveRetries()`` method | ||
| and the ``maxAdaptiveRetries`` connection string option, which configure | ||
| the maximum number of retry attempts for operations that fail with a | ||
| ``SystemOverloadedError``. The default value is ``2``. |
There was a problem hiding this comment.
The default value is
2
No, the default value is null, which implies 2, but is not equivalent to 2 (if they were equivalent, then explicitly setting 2 would be guaranteed to produce the same behavior as the default within the same major version of the driver, but we explicitly document that there is no such guarantee), because "the implied value and behavior may change in the future in a minor version". Please refer to https://github.com/mongodb/mongo-java-driver/blob/ff74470144f9c5ea98a5ab0881edbbfb1be2ca80/driver-core/src/main/com/mongodb/MongoClientSettings.java#L503-L568 for the full details.
The above seems too complex for what's new, so I am proposing not to mention the default.
| - Adds the ``SystemOverloadedError`` and ``RetryableError`` | ||
| labels to ``MongoException``. |
There was a problem hiding this comment.
- As currently formulated, the item is incorrect. We did introduce the
MongoException.SYSTEM_OVERLOADED_ERROR_LABELandMongoException.RETRYABLE_ERROR_LABELconstants, and that's how the change may be mentioned in what's new. - The ticket mentions that we need to express the potential need to adjust application retries. Users who do not upgrade, or who have application retries and do not use automatic retries built into the driver, might need to update application error handling to handle new errors happening in new situations when the server is deemed overloaded. This is where the aforementioned new constants may come in handy.
| - Adds the ``MongoClientSettings.Builder.enableOverloadRetargeting()`` method | ||
| and the ``enableOverloadRetargeting`` connection string option, which | ||
| control whether retries of a ``SystemOverloadedError`` attempt to | ||
| use a different server. The default value is ``false``. This | ||
| setting has no effect on sharded clusters. |
There was a problem hiding this comment.
retries of a
SystemOverloadedErrorattempt
A command execution can fail with an error having the SystemOverloadedError label, but there is no such thing as a "SystemOverloadedError attempt", as currently formulated.
3 participants
JIRA - DOCSP-64536
Shared what's new item for the 5.12 release.