From 359621569dfb1efe3a2b3c21ed5b45c9a76469a2 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Fri, 7 Oct 2022 17:17:01 -0400 Subject: [PATCH 01/10] DRIVERS-1675 Add log messages and tests to CMAP spec --- .../connection-monitoring-and-pooling.rst | 374 +++++++++++- .../tests/README.rst | 217 +------ .../tests/cmap-format/README.rst | 215 +++++++ .../connection-must-have-id.json | 0 .../connection-must-have-id.yml | 0 .../connection-must-order-ids.json | 0 .../connection-must-order-ids.yml | 0 .../pool-checkin-destroy-closed.json | 0 .../pool-checkin-destroy-closed.yml | 0 .../pool-checkin-destroy-stale.json | 0 .../pool-checkin-destroy-stale.yml | 0 .../pool-checkin-make-available.json | 0 .../pool-checkin-make-available.yml | 0 .../tests/{ => cmap-format}/pool-checkin.json | 0 .../tests/{ => cmap-format}/pool-checkin.yml | 0 .../pool-checkout-connection.json | 0 .../pool-checkout-connection.yml | 0 ...kout-custom-maxConnecting-is-enforced.json | 0 ...ckout-custom-maxConnecting-is-enforced.yml | 0 .../pool-checkout-error-closed.json | 0 .../pool-checkout-error-closed.yml | 0 ...ol-checkout-maxConnecting-is-enforced.json | 0 ...ool-checkout-maxConnecting-is-enforced.yml | 0 .../pool-checkout-maxConnecting-timeout.json | 0 .../pool-checkout-maxConnecting-timeout.yml | 0 ...-minPoolSize-connection-maxConnecting.json | 0 ...t-minPoolSize-connection-maxConnecting.yml | 0 .../pool-checkout-multiple.json | 0 .../pool-checkout-multiple.yml | 0 .../pool-checkout-no-idle.json | 0 .../pool-checkout-no-idle.yml | 0 .../pool-checkout-no-stale.json | 0 .../pool-checkout-no-stale.yml | 0 ...out-returned-connection-maxConnecting.json | 0 ...kout-returned-connection-maxConnecting.yml | 0 .../pool-clear-clears-waitqueue.json | 0 .../pool-clear-clears-waitqueue.yml | 0 .../pool-clear-interrupt-immediately.json | 0 .../pool-clear-interrupt-immediately.yml | 0 ...lear-interrupting-pending-connections.json | 0 ...clear-interrupting-pending-connections.yml | 0 .../pool-clear-min-size.json | 0 .../{ => cmap-format}/pool-clear-min-size.yml | 0 .../{ => cmap-format}/pool-clear-paused.json | 0 .../{ => cmap-format}/pool-clear-paused.yml | 0 .../{ => cmap-format}/pool-clear-ready.json | 0 .../{ => cmap-format}/pool-clear-ready.yml | 0 ...e-run-interruptInUseConnections-false.json | 0 ...le-run-interruptInUseConnections-false.yml | 0 .../pool-close-destroy-conns.json | 0 .../pool-close-destroy-conns.yml | 0 .../tests/{ => cmap-format}/pool-close.json | 0 .../tests/{ => cmap-format}/pool-close.yml | 0 .../pool-create-max-size.json | 0 .../pool-create-max-size.yml | 0 .../pool-create-min-size-error.json | 0 .../pool-create-min-size-error.yml | 0 .../pool-create-min-size.json | 0 .../pool-create-min-size.yml | 0 .../pool-create-with-options.json | 0 .../pool-create-with-options.yml | 0 .../tests/{ => cmap-format}/pool-create.json | 0 .../tests/{ => cmap-format}/pool-create.yml | 0 .../{ => cmap-format}/pool-ready-ready.json | 0 .../{ => cmap-format}/pool-ready-ready.yml | 0 .../tests/{ => cmap-format}/pool-ready.json | 0 .../tests/{ => cmap-format}/pool-ready.yml | 0 .../wait-queue-fairness.json | 0 .../{ => cmap-format}/wait-queue-fairness.yml | 0 .../{ => cmap-format}/wait-queue-timeout.json | 0 .../{ => cmap-format}/wait-queue-timeout.yml | 0 .../tests/logging/connection-logging.json | 427 +++++++++++++ .../tests/logging/connection-logging.yml | 190 ++++++ .../logging/connection-pool-options.json | 574 ++++++++++++++++++ .../tests/logging/connection-pool-options.yml | 311 ++++++++++ .../unified-test-format.rst | 11 + 76 files changed, 2092 insertions(+), 227 deletions(-) create mode 100644 source/connection-monitoring-and-pooling/tests/cmap-format/README.rst rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/connection-must-have-id.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/connection-must-have-id.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/connection-must-order-ids.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/connection-must-order-ids.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin-destroy-closed.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin-destroy-closed.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin-destroy-stale.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin-destroy-stale.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin-make-available.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin-make-available.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkin.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-connection.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-connection.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-custom-maxConnecting-is-enforced.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-custom-maxConnecting-is-enforced.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-error-closed.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-error-closed.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-maxConnecting-is-enforced.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-maxConnecting-is-enforced.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-maxConnecting-timeout.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-maxConnecting-timeout.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-minPoolSize-connection-maxConnecting.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-minPoolSize-connection-maxConnecting.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-multiple.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-multiple.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-no-idle.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-no-idle.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-no-stale.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-no-stale.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-returned-connection-maxConnecting.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-checkout-returned-connection-maxConnecting.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-clears-waitqueue.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-clears-waitqueue.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-interrupt-immediately.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-interrupt-immediately.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-interrupting-pending-connections.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-interrupting-pending-connections.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-min-size.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-min-size.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-paused.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-paused.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-ready.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-ready.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-schedule-run-interruptInUseConnections-false.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-clear-schedule-run-interruptInUseConnections-false.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-close-destroy-conns.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-close-destroy-conns.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-close.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-close.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-max-size.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-max-size.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-min-size-error.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-min-size-error.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-min-size.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-min-size.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-with-options.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create-with-options.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-create.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-ready-ready.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-ready-ready.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-ready.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/pool-ready.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/wait-queue-fairness.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/wait-queue-fairness.yml (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/wait-queue-timeout.json (100%) rename source/connection-monitoring-and-pooling/tests/{ => cmap-format}/wait-queue-timeout.yml (100%) create mode 100644 source/connection-monitoring-and-pooling/tests/logging/connection-logging.json create mode 100644 source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml create mode 100644 source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json create mode 100644 source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst index a684c1385a..c14d15379a 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst @@ -259,7 +259,7 @@ has the following properties: - **Thread Safe:** All Pool behaviors MUST be thread safe. - **Not Fork-Safe:** A Pool is explicitly not fork-safe. If a Pool detects that is it being used by a forked process, it MUST immediately clear itself and update its pid - **Single Owner:** A Pool MUST be associated with exactly one Endpoint, and MUST NOT be shared between Endpoints. -- **Emit Events:** A Pool MUST emit pool events when dictated by this spec (see `Connection Pool Monitoring <#connection-pool-monitoring>`__). Users MUST be able to subscribe to emitted events in a manner idiomatic to their language and driver. +- **Emit Events and Log Messages:** A Pool MUST emit pool events and log messages when dictated by this spec (see `Connection Pool Monitoring <#connection-pool-monitoring>`__). Users MUST be able to subscribe to emitted events and log messages in a manner idiomatic to their language and driver. - **Closeable:** A Pool MUST be able to be manually closed. When a Pool is closed, the following behaviors change: - Checking in a `Connection <#connection>`_ to the Pool automatically closes the `Connection <#connection>`_ @@ -391,7 +391,7 @@ section in the SDAM specification for more information. set generation to 0 set state to "paused" - emit PoolCreatedEvent + emit PoolCreatedEvent and equivalent log message Closing a Connection Pool ------------------------- @@ -406,7 +406,7 @@ When a pool is closed, it MUST first close all available `Connections <#connecti mark pool as "closed" for connection in availableConnections: close connection - emit PoolClosedEvent + emit PoolClosedEvent and equivalent log message Marking a Connection Pool as Ready ---------------------------------- @@ -422,7 +422,7 @@ method MUST immediately return and MUST NOT emit a PoolReadyEvent. .. code:: mark pool as "ready" - emit PoolReadyEvent + emit PoolReadyEvent and equivalent log message allow background thread to create connections Note that the PoolReadyEvent MUST be emitted before the background thread is allowed to resume creating new connections, @@ -442,7 +442,7 @@ performs no I/O. increment totalConnectionCount increment pendingConnectionCount set connection state to "pending" - emit ConnectionCreatedEvent + emit ConnectionCreatedEvent and equivalent log message return connection Establishing a Connection (Internal Implementation) @@ -459,7 +459,7 @@ handshake, handling OP_COMPRESSED, and performing authentication. perform connection handshake handle OP_COMPRESSED perform connection authentication - emit ConnectionReadyEvent + emit ConnectionReadyEvent and equivalent log message return connection except error: close connection @@ -487,7 +487,7 @@ thread or async I/O. decrement pendingConnectionCount decrement totalConnectionCount - emit ConnectionClosedEvent + emit ConnectionClosedEvent and equivalent log message # The following can happen at a later time (i.e. in background # thread) or via non-blocking I/O. @@ -606,7 +606,7 @@ Before a given `Connection <#connection>`_ is returned from checkOut, it must be .. code:: connection = Null - emit ConnectionCheckOutStartedEvent + emit ConnectionCheckOutStartedEvent and equivalent log message try: enter WaitQueue wait until at top of wait queue @@ -629,13 +629,13 @@ Before a given `Connection <#connection>`_ is returned from checkOut, it must be continue except pool is "closed": - emit ConnectionCheckOutFailedEvent(reason="poolClosed") + emit ConnectionCheckOutFailedEvent(reason="poolClosed") and equivalent log message throw PoolClosedError except pool is "paused": - emit ConnectionCheckOutFailedEvent(reason="connectionError") + emit ConnectionCheckOutFailedEvent(reason="connectionError") and equivalent log message throw PoolClearedError except timeout: - emit ConnectionCheckOutFailedEvent(reason="timeout") + emit ConnectionCheckOutFailedEvent(reason="timeout") and equivalent log message throw WaitQueueTimeoutError finally: # This must be done in all drivers @@ -655,7 +655,7 @@ Before a given `Connection <#connection>`_ is returned from checkOut, it must be try: establish connection except connection establishment error: - emit ConnectionCheckOutFailedEvent(reason="error") + emit ConnectionCheckOutFailedEvent(reason="connectionError") and equivalent log message decrement totalConnectionCount throw finally: @@ -663,7 +663,7 @@ Before a given `Connection <#connection>`_ is returned from checkOut, it must be else: decrement availableConnectionCount set connection state to "in use" - emit ConnectionCheckedOutEvent + emit ConnectionCheckedOutEvent and equivalent log message return connection Checking In a Connection @@ -685,7 +685,7 @@ Otherwise, the `Connection <#connection>`_ is marked as available. .. code:: - emit ConnectionCheckedInEvent + emit ConnectionCheckedInEvent and equivalent log message if connection is perished OR pool is closed: close connection else: @@ -709,10 +709,10 @@ marking all current `Connections <#connection>`_ as stale. It should also transition the pool's state to "paused" to halt the creation of new connections until it is marked as "ready" again. The checkOut and checkIn algorithms will handle clearing out stale `Connections <#connection>`_. If a user is subscribed -to Connection Monitoring events, a PoolClearedEvent MUST be emitted after -incrementing the generation / marking the pool as "paused". If the pool is -already "paused" when it is cleared, then the pool MUST NOT emit a PoolCleared -event. +to Connection Monitoring events and/or connection log messages, a PoolClearedEvent +and log message MUST be emitted after incrementing the generation / marking the pool +as "paused". If the pool is already "paused" when it is cleared, then the pool MUST +NOT emit a PoolCleared event or log message. As part of clearing the pool, the WaitQueue MUST also be cleared, meaning all requests in the WaitQueue MUST fail with errors indicating that the pool was @@ -745,7 +745,7 @@ Clearing a load balanced pool A Pool MUST also have a method of clearing all `Connections <#connection>`_ for a specific ``serviceId`` for use when in load balancer mode. This method increments the generation of the pool for that specific ``serviceId`` in the -generation map. A PoolClearedEvent MUST be emitted after incrementing the +generation map. A PoolClearedEvent and log message MUST be emitted after incrementing the generation. Note that this method MUST NOT transition the pool to the "paused" state and MUST NOT clear the WaitQueue. @@ -998,6 +998,337 @@ See the `Load Balancer Specification <../load-balancers/load-balancers.rst#event connectionId: number; } +Connection Pool Logging +~~~~~~~~~~~~~~~~~~~~~~~ +Please refer to the `logging specification <../logging/logging.rst>`_ for details on logging implementations in general, including log levels, log +components, handling of null values in log messages, and structured versus unstructured logging. + +Drivers MUST support logging of connection pool information via the following types of log messages. These messages MUST be logged at ``Debug`` level +and use the ``connection`` log component. These messages MUST be emitted when specified in “Connection Pool Behaviors”. + +The log messages are intended to match the information contained in the events above. Drivers MAY implement connection logging support via an event +subscriber if it is convenient to do so. + +The types used in the structured message definitions below are demonstrative, and drivers MAY use similar types instead so long as the information +is present (e.g. a double instead of an integer, or a string instead of an integer if the structured logging framework does not support numeric types.) + +Common Fields +------------- +All connection log messages MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - serverHost + - String + - the hostname or IP address for the endpoint the pool is for. + + * - serverPort + - Int + - The port for the endpoint the pool is for. Optional; only present if a port was specified. + +Pool Created Message +--------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection pool created" + + * - maxIdleTimeMS + - Int + - The maxIdleTimeMS value for this pool. Optional; only required to include if the user specified a value. + + * - minPoolSize + - Int + - The minPoolSize value for this pool. Optional; only required to include if the user specified a value. + + * - maxPoolSize + - Int + - The maxPoolSize value for this pool. Optional; only required to include if the user specified a value. + + * - maxConnecting + - Int + - The maxConnecting value for this pool. Optional; only required to include if the driver supports this option and the user + specified a value. + + * - waitQueueTimeoutMS + - Int + - The waitQueueTimeoutMS value for this pool. Optional; only required to include if the driver supports this option and the + user specified a value. + + * - waitQueueSize + - Int + - The waitQueueSize value for this pool. Optional; only required to include if the driver supports this option and the + user specified a value. + + * - waitQueueMultiple + - Int + - The waitQueueMultiple value for this pool. Optional; only required to include if the driver supports this option and the + user specified a value. + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection pool created for host with hostname {{serverHost}} on port {{serverPort}} using options maxIdleTimeMS={{maxIdleTimeMS}}, + minPoolSize={{minPoolSize}}, maxPoolSize={{maxPoolSize}}, maxConnecting={{maxConnecting}}, waitQueueTimeoutMS={{waitQueueTimeoutMS}}, + waitQueueSize={{waitQueueSize}}, waitQueueMultiple={{waitQueueMultiple}} + +Pool Ready Message +------------------ +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection pool ready" + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection pool ready for host with hostname {{serverHost}} on port {{serverPort}} + +Pool Cleared Message +-------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection pool cleared" + + * - serviceId + - String + - The hex string representation of the service ID which the pool was cleared for. Optional; only present in load balanced mode. + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection pool cleared for serviceId {{serviceId}} and host with hostname {{serverHost}} on port {{serverPort}} + +Pool Closed Message +------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection pool closed" + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection pool closed for host with hostname {{serverHost}} on port {{serverPort}} + +Connection Created Message +-------------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection created" + + * - driverConnectionId + - Int + - The driver-generated ID for the connection as defined in `Connection <#connection>`_. + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection created with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + +Connection Ready Message +------------------------ +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection ready" + + * - driverConnectionId + - Int + - The driver-generated ID for the connection as defined in `Connection <#connection>`_. + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection ready with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + +Connection Closed Message +------------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection closed" + + * - driverConnectionId + - Int + - The driver-generated ID for the connection as defined in `Connection <#connection>`_. + + * - reason + - String + - A string describing the reason the connection was closed. The following strings MUST be used for each possible reason + as defined in `Events <#events>`_ above: + + - Stale: "Connection became stale because the pool was cleared" + - Idle: "Connection has been available but unused for longer than the configured max idle time" + - Error: "An error occurred while using the connection" + - Pool closed: "Connection pool was closed" + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection closed with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}}. Reason: {{reason}} + +Connection Checkout Started Message +----------------------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection checkout started" + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Checkout started for connection to host with hostname {{serverHost}} on port {{serverPort}} + +Connection Checkout Failed Message +----------------------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection checkout failed" + + * - reason + - String + - A string describing the reason checkout. The following strings MUST be used for each possible reason + as defined in `Events <#events>`_ above: + + - Timeout: "Wait queue timeout elapsed without a connection becoming available" + - ConnectionError: "An error occurred while trying to establish a new connection" + - Pool closed: "Connection pool was closed" + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Checkout failed for connection to host with hostname {{serverHost}} on port {{serverPort}} + +Connection Checked Out +----------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection checked out" + + * - driverConnectionId + - Int + - The driver-generated ID for the connection as defined in `Connection <#connection>`_. + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection checked out with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + +Connection Checked In +--------------------- +In addition to the common fields defined above, this message MUST contain the following key-value pairs: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Key + - Suggested Type + - Value + + * - message + - String + - "Connection checked in" + + * - driverConnectionId + - Int + - The driver-generated ID for the connection as defined in `Connection <#connection>`_. + +The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: + + Connection checked in with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + Connection Pool Errors ~~~~~~~~~~~~~~~~~~~~~~ @@ -1121,8 +1452,8 @@ not. This enables the following behaviors: between SDAM and Server Selection. These requests would then likely fail with potentially high latency, again wasting resources both server and driver side. -Why not emit PoolCleared events when clearing a paused pool? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why not emit PoolCleared events and log messages when clearing a paused pool? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If a pool is already paused when it is cleared, that means it was previously cleared and no new connections have been created since then. Thus, clearing the @@ -1205,6 +1536,7 @@ Changelog :2021-11-08: Make maxConnecting configurable. :2022-04-05: Preemptively cancel in progress operations when SDAM heartbeats timeout. :2022-10-05: Remove spec front matter and reformat changelog. +:2022-10-14: Add connection pool log messages and associated tests. ---- diff --git a/source/connection-monitoring-and-pooling/tests/README.rst b/source/connection-monitoring-and-pooling/tests/README.rst index b4c87927a8..ae4af543f2 100644 --- a/source/connection-monitoring-and-pooling/tests/README.rst +++ b/source/connection-monitoring-and-pooling/tests/README.rst @@ -11,217 +11,16 @@ Connection Monitoring and Pooling (CMAP) Introduction ============ +Drivers MUST implement all of the following types of CMAP tests: -The YAML and JSON files in this directory are platform-independent tests that -drivers can use to prove their conformance to the Connection Monitoring and Pooling (CMAP) Spec. - -Several prose tests, which are not easily expressed in YAML, are also presented -in this file. Those tests will need to be manually implemented by each driver. - -Common Test Format -================== - -Each YAML file has the following keys: - -- ``version``: A version number indicating the expected format of the spec tests (current version = 1) -- ``style``: A string indicating what style of tests this file contains. Contains one of the following: - - - ``"unit"``: a test that may be run without connecting to a MongoDB deployment. - - ``"integration"``: a test that MUST be run against a real MongoDB deployment. - -- ``description``: A text description of what the test is meant to assert - -Unit Test Format: -================= - -All Unit Tests have some of the following fields: - -- ``poolOptions``: If present, connection pool options to use when creating a pool; - both `standard ConnectionPoolOptions `__ - and the following test-specific options are allowed: - - - ``backgroundThreadIntervalMS``: A time interval between the end of a - `Background Thread Run `__ - and the beginning of the next Run. If a Connection Pool does not implement a Background Thread, the Test Runner MUST ignore the option. - If the option is not specified, an implementation is free to use any value it finds reasonable. - - Possible values (0 is not allowed): - - - A negative value: never begin a Run. - - A positive value: the interval between Runs in milliseconds. - -- ``operations``: A list of operations to perform. All operations support the following fields: - - - ``name``: A string describing which operation to issue. - - ``thread``: The name of the thread in which to run this operation. If not specified, runs in the default thread - -- ``error``: Indicates that the main thread is expected to error during this test. An error may include of the following fields: - - - ``type``: the type of error emitted - - ``message``: the message associated with that error - - ``address``: Address of pool emitting error - -- ``events``: An array of all connection monitoring events expected to occur while running ``operations``. An event may contain any of the following fields - - - ``type``: The type of event emitted - - ``address``: The address of the pool emitting the event - - ``connectionId``: The id of a connection associated with the event - - ``options``: Options used to create the pool - - ``reason``: A reason giving mroe information on why the event was emitted - -- ``ignore``: An array of event names to ignore - -Valid Unit Test Operations are the following: - -- ``start(target)``: Starts a new thread named ``target`` - - - ``target``: The name of the new thread to start - -- ``wait(ms)``: Sleep the current thread for ``ms`` milliseconds - - - ``ms``: The number of milliseconds to sleep the current thread for - -- ``waitForThread(target)``: wait for thread ``target`` to finish executing. Propagate any errors to the main thread. - - - ``target``: The name of the thread to wait for. - -- ``waitForEvent(event, count, timeout)``: block the current thread until ``event`` has occurred ``count`` times - - - ``event``: The name of the event - - ``count``: The number of times the event must occur (counting from the start of the test) - - ``timeout``: If specified, time out with an error after waiting for this many milliseconds without seeing the required events - -- ``label = pool.checkOut()``: call ``checkOut`` on pool, returning the checked out connection - - - ``label``: If specified, associate this label with the returned connection, so that it may be referenced in later operations - -- ``pool.checkIn(connection)``: call ``checkIn`` on pool - - - ``connection``: A string label identifying which connection to check in. Should be a label that was previously set with ``checkOut`` - -- ``pool.clear()``: call ``clear`` on Pool - - - ``interruptInUseConnections``: Determines whether "in use" connections should be also interrupted - -- ``pool.close()``: call ``close`` on Pool -- ``pool.ready()``: call ``ready`` on Pool - - -Integration Test Format -======================= - -The integration test format is identical to the unit test format with -the addition of the following fields to each test: - -- ``runOn`` (optional): An array of server version and/or topology requirements - for which the tests can be run. If the test environment satisfies one or more - of these requirements, the tests may be executed; otherwise, this test should - be skipped. If this field is omitted, the tests can be assumed to have no - particular requirements and should be executed. Each element will have some or - all of the following fields: - - - ``minServerVersion`` (optional): The minimum server version (inclusive) - required to successfully run the tests. If this field is omitted, it should - be assumed that there is no lower bound on the required server version. - - - ``maxServerVersion`` (optional): The maximum server version (inclusive) - against which the tests can be run successfully. If this field is omitted, - it should be assumed that there is no upper bound on the required server - version. - -- ``failPoint``: optional, a document containing a ``configureFailPoint`` - command to run against the endpoint being used for the test. - -- ``poolOptions.appName`` (optional): appName attribute to be set in connections, which will be affected by the fail point. - -Spec Test Match Function -======================== - -The definition of MATCH or MATCHES in the Spec Test Runner is as follows: - -- MATCH takes two values, ``expected`` and ``actual`` -- Notation is "Assert [actual] MATCHES [expected] -- Assertion passes if ``expected`` is a subset of ``actual``, with the values ``42`` and ``"42"`` acting as placeholders for "any value" - -Pseudocode implementation of ``actual`` MATCHES ``expected``: - -:: - - If expected is "42" or 42: - Assert that actual exists (is not null or undefined) - Else: - Assert that actual is of the same JSON type as expected - If expected is a JSON array: - For every idx/value in expected: - Assert that actual[idx] MATCHES value - Else if expected is a JSON object: - For every key/value in expected - Assert that actual[key] MATCHES value - Else: - Assert that expected equals actual - -Unit Test Runner: -================= - -For the unit tests, the behavior of a Connection is irrelevant beyond the need to asserting ``connection.id``. Drivers MAY use a mock connection class for testing the pool behavior in unit tests - -For each YAML file with ``style: unit``: - -- Create a Pool ``pool``, subscribe and capture any Connection Monitoring events emitted in order. - - - If ``poolOptions`` is specified, use those options to initialize both pools - - The returned pool must have an ``address`` set as a string value. - -- Process each ``operation`` in ``operations`` (on the main thread) - - - If a ``thread`` is specified, the main thread MUST schedule the operation to execute in the corresponding thread. Otherwise, execute the operation directly in the main thread. - -- If ``error`` is presented - - - Assert that an actual error ``actualError`` was thrown by the main thread - - Assert that ``actualError`` MATCHES ``error`` - -- Else: - - - Assert that no errors were thrown by the main thread - -- calculate ``actualEvents`` as every Connection Event emitted whose ``type`` is not in ``ignore`` -- if ``events`` is not empty, then for every ``idx``/``expectedEvent`` in ``events`` - - - Assert that ``actualEvents[idx]`` exists - - Assert that ``actualEvents[idx]`` MATCHES ``expectedEvent`` - - -It is important to note that the ``ignore`` list is used for calculating ``actualEvents``, but is NOT used for the ``waitForEvent`` command - -Integration Test Runner -======================= - -The steps to run the integration tests are the same as those used to run the -unit tests with the following modifications: - -- The integration tests MUST be run against an actual endpoint. If the - deployment being tested contains multiple endpoints, then the runner MUST - only use one of them to run the tests against. - -- For each test, if `failPoint` is specified, its value is a - ``configureFailPoint`` command. Run the command on the admin database of the - endpoint being tested to enable the fail point. - -- At the end of each test, any enabled fail point MUST be disabled to avoid - spurious failures in subsequent tests. The fail point may be disabled like - so:: - - db.adminCommand({ - configureFailPoint: , - mode: "off" - }); - +* Pool unit and integration tests as described in `cmap-format/README.rst <./cmap-format/README.rst>`__ +* Pool prose tests as described below in `Prose Tests`_ +* Logging tests as described below in `Logging Tests`_ Prose Tests =========== -The following tests have not yet been automated, but MUST still be tested +The following tests have not yet been automated, but MUST still be tested: #. All ConnectionPoolOptions MUST be specified at the MongoClient level #. All ConnectionPoolOptions MUST be the same for all pools created by a MongoClient @@ -229,3 +28,9 @@ The following tests have not yet been automated, but MUST still be tested #. A user MUST be able to subscribe to Connection Monitoring Events in a manner idiomatic to their language and driver #. When a check out attempt fails because connection set up throws an error, assert that a ConnectionCheckOutFailedEvent with reason="connectionError" is emitted. + +Logging Tests +============= + +Tests for connection pool logging can be found in the `/logging <./logging>`__ subdirectory and are written in the +`Unified Test Format <../../unified-test-format/unified-test-format.rst>`__. \ No newline at end of file diff --git a/source/connection-monitoring-and-pooling/tests/cmap-format/README.rst b/source/connection-monitoring-and-pooling/tests/cmap-format/README.rst new file mode 100644 index 0000000000..5bb72dd0fe --- /dev/null +++ b/source/connection-monitoring-and-pooling/tests/cmap-format/README.rst @@ -0,0 +1,215 @@ +.. role:: javascript(code) + :language: javascript + +=================================================================== +Connection Monitoring and Pooling (CMAP) Unit and Integration Tests +=================================================================== + +.. contents:: + +-------- + +Introduction +============ + +The YAML and JSON files in this directory are platform-independent tests that +drivers can use to prove their conformance to the Connection Monitoring and Pooling (CMAP) Spec. + +Common Test Format +================== + +Each YAML file has the following keys: + +- ``version``: A version number indicating the expected format of the spec tests (current version = 1) +- ``style``: A string indicating what style of tests this file contains. Contains one of the following: + + - ``"unit"``: a test that may be run without connecting to a MongoDB deployment. + - ``"integration"``: a test that MUST be run against a real MongoDB deployment. + +- ``description``: A text description of what the test is meant to assert + +Unit Test Format: +================= + +All Unit Tests have some of the following fields: + +- ``poolOptions``: If present, connection pool options to use when creating a pool; + both `standard ConnectionPoolOptions `__ + and the following test-specific options are allowed: + + - ``backgroundThreadIntervalMS``: A time interval between the end of a + `Background Thread Run `__ + and the beginning of the next Run. If a Connection Pool does not implement a Background Thread, the Test Runner MUST ignore the option. + If the option is not specified, an implementation is free to use any value it finds reasonable. + + Possible values (0 is not allowed): + + - A negative value: never begin a Run. + - A positive value: the interval between Runs in milliseconds. + +- ``operations``: A list of operations to perform. All operations support the following fields: + + - ``name``: A string describing which operation to issue. + - ``thread``: The name of the thread in which to run this operation. If not specified, runs in the default thread + +- ``error``: Indicates that the main thread is expected to error during this test. An error may include of the following fields: + + - ``type``: the type of error emitted + - ``message``: the message associated with that error + - ``address``: Address of pool emitting error + +- ``events``: An array of all connection monitoring events expected to occur while running ``operations``. An event may contain any of the following fields + + - ``type``: The type of event emitted + - ``address``: The address of the pool emitting the event + - ``connectionId``: The id of a connection associated with the event + - ``options``: Options used to create the pool + - ``reason``: A reason giving mroe information on why the event was emitted + +- ``ignore``: An array of event names to ignore + +Valid Unit Test Operations are the following: + +- ``start(target)``: Starts a new thread named ``target`` + + - ``target``: The name of the new thread to start + +- ``wait(ms)``: Sleep the current thread for ``ms`` milliseconds + + - ``ms``: The number of milliseconds to sleep the current thread for + +- ``waitForThread(target)``: wait for thread ``target`` to finish executing. Propagate any errors to the main thread. + + - ``target``: The name of the thread to wait for. + +- ``waitForEvent(event, count, timeout)``: block the current thread until ``event`` has occurred ``count`` times + + - ``event``: The name of the event + - ``count``: The number of times the event must occur (counting from the start of the test) + - ``timeout``: If specified, time out with an error after waiting for this many milliseconds without seeing the required events + +- ``label = pool.checkOut()``: call ``checkOut`` on pool, returning the checked out connection + + - ``label``: If specified, associate this label with the returned connection, so that it may be referenced in later operations + +- ``pool.checkIn(connection)``: call ``checkIn`` on pool + + - ``connection``: A string label identifying which connection to check in. Should be a label that was previously set with ``checkOut`` + +- ``pool.clear()``: call ``clear`` on Pool + + - ``interruptInUseConnections``: Determines whether "in use" connections should be also interrupted + +- ``pool.close()``: call ``close`` on Pool +- ``pool.ready()``: call ``ready`` on Pool + + +Integration Test Format +======================= + +The integration test format is identical to the unit test format with +the addition of the following fields to each test: + +- ``runOn`` (optional): An array of server version and/or topology requirements + for which the tests can be run. If the test environment satisfies one or more + of these requirements, the tests may be executed; otherwise, this test should + be skipped. If this field is omitted, the tests can be assumed to have no + particular requirements and should be executed. Each element will have some or + all of the following fields: + + - ``minServerVersion`` (optional): The minimum server version (inclusive) + required to successfully run the tests. If this field is omitted, it should + be assumed that there is no lower bound on the required server version. + + - ``maxServerVersion`` (optional): The maximum server version (inclusive) + against which the tests can be run successfully. If this field is omitted, + it should be assumed that there is no upper bound on the required server + version. + +- ``failPoint``: optional, a document containing a ``configureFailPoint`` + command to run against the endpoint being used for the test. + +- ``poolOptions.appName`` (optional): appName attribute to be set in connections, which will be affected by the fail point. + +Spec Test Match Function +======================== + +The definition of MATCH or MATCHES in the Spec Test Runner is as follows: + +- MATCH takes two values, ``expected`` and ``actual`` +- Notation is "Assert [actual] MATCHES [expected] +- Assertion passes if ``expected`` is a subset of ``actual``, with the values ``42`` and ``"42"`` acting as placeholders for "any value" + +Pseudocode implementation of ``actual`` MATCHES ``expected``: + +:: + + If expected is "42" or 42: + Assert that actual exists (is not null or undefined) + Else: + Assert that actual is of the same JSON type as expected + If expected is a JSON array: + For every idx/value in expected: + Assert that actual[idx] MATCHES value + Else if expected is a JSON object: + For every key/value in expected + Assert that actual[key] MATCHES value + Else: + Assert that expected equals actual + +Unit Test Runner: +================= + +For the unit tests, the behavior of a Connection is irrelevant beyond the need to asserting ``connection.id``. Drivers MAY use a mock connection class for testing the pool behavior in unit tests + +For each YAML file with ``style: unit``: + +- Create a Pool ``pool``, subscribe and capture any Connection Monitoring events emitted in order. + + - If ``poolOptions`` is specified, use those options to initialize both pools + - The returned pool must have an ``address`` set as a string value. + +- Process each ``operation`` in ``operations`` (on the main thread) + + - If a ``thread`` is specified, the main thread MUST schedule the operation to execute in the corresponding thread. Otherwise, execute the operation directly in the main thread. + +- If ``error`` is presented + + - Assert that an actual error ``actualError`` was thrown by the main thread + - Assert that ``actualError`` MATCHES ``error`` + +- Else: + + - Assert that no errors were thrown by the main thread + +- calculate ``actualEvents`` as every Connection Event emitted whose ``type`` is not in ``ignore`` +- if ``events`` is not empty, then for every ``idx``/``expectedEvent`` in ``events`` + + - Assert that ``actualEvents[idx]`` exists + - Assert that ``actualEvents[idx]`` MATCHES ``expectedEvent`` + + +It is important to note that the ``ignore`` list is used for calculating ``actualEvents``, but is NOT used for the ``waitForEvent`` command + +Integration Test Runner +======================= + +The steps to run the integration tests are the same as those used to run the +unit tests with the following modifications: + +- The integration tests MUST be run against an actual endpoint. If the + deployment being tested contains multiple endpoints, then the runner MUST + only use one of them to run the tests against. + +- For each test, if `failPoint` is specified, its value is a + ``configureFailPoint`` command. Run the command on the admin database of the + endpoint being tested to enable the fail point. + +- At the end of each test, any enabled fail point MUST be disabled to avoid + spurious failures in subsequent tests. The fail point may be disabled like + so:: + + db.adminCommand({ + configureFailPoint: , + mode: "off" + }); diff --git a/source/connection-monitoring-and-pooling/tests/connection-must-have-id.json b/source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-have-id.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/connection-must-have-id.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-have-id.json diff --git a/source/connection-monitoring-and-pooling/tests/connection-must-have-id.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-have-id.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/connection-must-have-id.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-have-id.yml diff --git a/source/connection-monitoring-and-pooling/tests/connection-must-order-ids.json b/source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-order-ids.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/connection-must-order-ids.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-order-ids.json diff --git a/source/connection-monitoring-and-pooling/tests/connection-must-order-ids.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-order-ids.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/connection-must-order-ids.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/connection-must-order-ids.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-closed.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-closed.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-closed.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-closed.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-closed.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-closed.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-closed.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-closed.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-stale.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-stale.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-stale.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-stale.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-stale.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-stale.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin-destroy-stale.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-destroy-stale.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin-make-available.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-make-available.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin-make-available.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-make-available.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin-make-available.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-make-available.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin-make-available.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin-make-available.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkin.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkin.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkin.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-connection.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-connection.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-connection.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-connection.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-connection.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-connection.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-connection.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-connection.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-custom-maxConnecting-is-enforced.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-custom-maxConnecting-is-enforced.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-custom-maxConnecting-is-enforced.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-custom-maxConnecting-is-enforced.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-custom-maxConnecting-is-enforced.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-custom-maxConnecting-is-enforced.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-custom-maxConnecting-is-enforced.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-custom-maxConnecting-is-enforced.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-error-closed.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-error-closed.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-error-closed.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-error-closed.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-error-closed.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-error-closed.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-error-closed.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-error-closed.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-is-enforced.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-is-enforced.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-is-enforced.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-is-enforced.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-is-enforced.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-is-enforced.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-is-enforced.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-is-enforced.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-timeout.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-timeout.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-timeout.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-timeout.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-timeout.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-timeout.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-maxConnecting-timeout.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-maxConnecting-timeout.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-minPoolSize-connection-maxConnecting.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-minPoolSize-connection-maxConnecting.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-minPoolSize-connection-maxConnecting.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-minPoolSize-connection-maxConnecting.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-minPoolSize-connection-maxConnecting.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-minPoolSize-connection-maxConnecting.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-minPoolSize-connection-maxConnecting.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-minPoolSize-connection-maxConnecting.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-multiple.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-multiple.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-multiple.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-multiple.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-multiple.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-multiple.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-multiple.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-multiple.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-no-idle.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-idle.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-no-idle.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-idle.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-no-idle.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-idle.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-no-idle.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-idle.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-no-stale.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-stale.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-no-stale.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-stale.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-no-stale.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-stale.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-no-stale.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-no-stale.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-returned-connection-maxConnecting.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-returned-connection-maxConnecting.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-returned-connection-maxConnecting.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-returned-connection-maxConnecting.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-checkout-returned-connection-maxConnecting.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-returned-connection-maxConnecting.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-checkout-returned-connection-maxConnecting.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-checkout-returned-connection-maxConnecting.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-clears-waitqueue.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-clears-waitqueue.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-clears-waitqueue.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-clears-waitqueue.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-clears-waitqueue.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-clears-waitqueue.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-clears-waitqueue.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-clears-waitqueue.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-interrupt-immediately.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupt-immediately.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-interrupt-immediately.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupt-immediately.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-interrupt-immediately.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupt-immediately.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-interrupt-immediately.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupt-immediately.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-interrupting-pending-connections.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupting-pending-connections.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-interrupting-pending-connections.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupting-pending-connections.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-interrupting-pending-connections.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupting-pending-connections.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-interrupting-pending-connections.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-interrupting-pending-connections.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-min-size.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-min-size.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-min-size.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-min-size.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-min-size.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-min-size.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-min-size.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-min-size.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-paused.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-paused.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-paused.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-paused.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-paused.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-paused.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-paused.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-paused.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-ready.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-ready.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-ready.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-ready.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-ready.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-ready.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-ready.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-ready.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-schedule-run-interruptInUseConnections-false.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-schedule-run-interruptInUseConnections-false.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-schedule-run-interruptInUseConnections-false.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-schedule-run-interruptInUseConnections-false.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-clear-schedule-run-interruptInUseConnections-false.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-schedule-run-interruptInUseConnections-false.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-clear-schedule-run-interruptInUseConnections-false.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-clear-schedule-run-interruptInUseConnections-false.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-close-destroy-conns.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-close-destroy-conns.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-close-destroy-conns.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-close-destroy-conns.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-close-destroy-conns.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-close-destroy-conns.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-close-destroy-conns.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-close-destroy-conns.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-close.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-close.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-close.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-close.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-close.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-close.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-close.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-close.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-max-size.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-max-size.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-max-size.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-max-size.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-max-size.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-max-size.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-max-size.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-max-size.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-min-size-error.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size-error.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-min-size-error.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size-error.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-min-size-error.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size-error.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-min-size-error.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size-error.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-min-size.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-min-size.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-min-size.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-min-size.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-min-size.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-with-options.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-with-options.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-with-options.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-with-options.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-create-with-options.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-with-options.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create-with-options.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create-with-options.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-create.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-create.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-create.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-create.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-create.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-ready-ready.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready-ready.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-ready-ready.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready-ready.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-ready-ready.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready-ready.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-ready-ready.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready-ready.yml diff --git a/source/connection-monitoring-and-pooling/tests/pool-ready.json b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-ready.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready.json diff --git a/source/connection-monitoring-and-pooling/tests/pool-ready.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/pool-ready.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/pool-ready.yml diff --git a/source/connection-monitoring-and-pooling/tests/wait-queue-fairness.json b/source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-fairness.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/wait-queue-fairness.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-fairness.json diff --git a/source/connection-monitoring-and-pooling/tests/wait-queue-fairness.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-fairness.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/wait-queue-fairness.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-fairness.yml diff --git a/source/connection-monitoring-and-pooling/tests/wait-queue-timeout.json b/source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-timeout.json similarity index 100% rename from source/connection-monitoring-and-pooling/tests/wait-queue-timeout.json rename to source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-timeout.json diff --git a/source/connection-monitoring-and-pooling/tests/wait-queue-timeout.yml b/source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-timeout.yml similarity index 100% rename from source/connection-monitoring-and-pooling/tests/wait-queue-timeout.yml rename to source/connection-monitoring-and-pooling/tests/cmap-format/wait-queue-timeout.yml diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json new file mode 100644 index 0000000000..c6ba297f7b --- /dev/null +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json @@ -0,0 +1,427 @@ +{ + "description": "connection-logging", + "schemaVersion": "1.13", + "runOnRequirements": [ + { + "topologies": [ + "single" + ] + } + ], + "createEntities": [ + { + "client": { + "id": "failPointClient" + } + } + ], + "tests": [ + { + "description": "Create a client, run a command, and close the client", + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "observeLogMessages": { + "connection": "debug" + } + } + } + ] + } + }, + { + "name": "listDatabases", + "object": "client", + "arguments": { + "filter": {} + } + }, + { + "name": "close", + "object": "client" + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection checkout started", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection created", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection ready", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection checked out", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection checked in", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection closed", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "reason": "Connection pool was closed" + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool closed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + } + ] + } + ] + }, + { + "description": "Connection checkout fails due to error establishing connection", + "runOnRequirements": [ + { + "auth": true + } + ], + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "uriOptions": { + "retryReads": false, + "appname": "clientAppName" + }, + "observeLogMessages": { + "connection": "debug" + } + } + } + ] + } + }, + { + "name": "failPoint", + "object": "testRunner", + "arguments": { + "client": "failPointClient", + "failPoint": { + "configureFailPoint": "failCommand", + "mode": { + "times": 1 + }, + "data": { + "failCommands": [ + "saslContinue" + ], + "closeConnection": true, + "appName": "clientAppName" + } + } + } + }, + { + "name": "listDatabases", + "object": "client", + "arguments": { + "filter": {} + }, + "expectError": { + "isClientError": true + } + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection checkout started", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection created", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool cleared", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection closed", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "reason": "An error occurred while using the connection" + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection checkout failed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "reason": "An error occurred while trying to establish a connection" + } + } + ] + } + ] + } + ] +} diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml new file mode 100644 index 0000000000..6925d17d0c --- /dev/null +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml @@ -0,0 +1,190 @@ +description: "connection-logging" + +schemaVersion: "1.13" + +runOnRequirements: + - topologies: + - single # The number of log messages is different for each topology since there is a connection pool per host. + +createEntities: + - client: + id: &failPointClient failPointClient + +tests: + - description: "Create a client, run a command, and close the client" + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + observeLogMessages: + connection: debug + - name: listDatabases + object: *client + arguments: + filter: {} + - name: close + object: *client + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection checkout started" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection created" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection ready" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection checked out" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection checked in" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection closed" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + reason: "Connection pool was closed" + + - level: debug + component: connection + data: + message: "Connection pool closed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + # This test exists to probide coverage of checkout failed and pool cleared events. + - description: "Connection checkout fails due to error establishing connection" + runOnRequirements: + - auth: true + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + uriOptions: + retryReads: false + appname: &clientAppName clientAppName + observeLogMessages: + connection: debug + - name: failPoint + object: testRunner + arguments: + client: *failPointClient + failPoint: + configureFailPoint: failCommand + mode: { times: 1 } + data: + failCommands: ["saslContinue"] + closeConnection: true + appName: *clientAppName + - name: listDatabases + object: *client + arguments: + filter: {} + expectError: + isClientError: true + + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection checkout started" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection created" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool cleared" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection closed" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + reason: "An error occurred while using the connection" + + - level: debug + component: connection + data: + message: "Connection checkout failed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + reason: "An error occurred while trying to establish a connection" diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json new file mode 100644 index 0000000000..a35675b55f --- /dev/null +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json @@ -0,0 +1,574 @@ +{ + "description": "connection-logging", + "schemaVersion": "1.13", + "runOnRequirements": [ + { + "topologies": [ + "single" + ] + } + ], + "tests": [ + { + "description": "Options should be included in connection pool created message when specified", + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "observeEvents": [ + "connectionReadyEvent" + ], + "observeLogMessages": { + "connection": "debug" + }, + "uriOptions": { + "minPoolSize": 1, + "maxPoolSize": 5, + "maxIdleTimeMS": 10000 + } + } + } + ] + } + }, + { + "name": "waitForEvent", + "object": "testRunner", + "arguments": { + "client": "client", + "event": { + "connectionReadyEvent": {} + }, + "count": 1 + } + }, + { + "name": "close", + "object": "client" + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "minPoolSize": 1, + "maxPoolSize": 5, + "maxIdleTimeMS": 10000 + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection created", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection ready", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection closed", + "driverConnectionId": { + "$$type": [ + "int", + "long" + ] + }, + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "reason": "Connection pool was closed" + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool closed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + } + ] + } + ] + }, + { + "description": "maxConnecting should be included in connection pool created message when specified", + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "observeEvents": [ + "poolReadyEvent" + ], + "observeLogMessages": { + "connection": "debug" + }, + "uriOptions": { + "maxConnecting": 5 + } + } + } + ] + } + }, + { + "name": "waitForEvent", + "object": "testRunner", + "arguments": { + "client": "client", + "event": { + "poolReadyEvent": {} + }, + "count": 1 + } + }, + { + "name": "close", + "object": "client" + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "maxConnecting": 5 + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool closed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + } + ] + } + ] + }, + { + "description": "waitQueueTimeoutMS should be included in connection pool created message when specified", + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "observeEvents": [ + "poolReadyEvent" + ], + "observeLogMessages": { + "connection": "debug" + }, + "uriOptions": { + "waitQueueTimeoutMS": 10000 + } + } + } + ] + } + }, + { + "name": "waitForEvent", + "object": "testRunner", + "arguments": { + "client": "client", + "event": { + "poolReadyEvent": {} + }, + "count": 1 + } + }, + { + "name": "close", + "object": "client" + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "waitQueueTimeoutMS": 10000 + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool closed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + } + ] + } + ] + }, + { + "description": "waitQueueSize should be included in connection pool created message when specified", + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "observeEvents": [ + "poolReadyEvent" + ], + "observeLogMessages": { + "connection": "debug" + }, + "uriOptions": { + "waitQueueSize": 100 + } + } + } + ] + } + }, + { + "name": "waitForEvent", + "object": "testRunner", + "arguments": { + "client": "client", + "event": { + "poolReadyEvent": {} + }, + "count": 1 + } + }, + { + "name": "close", + "object": "client" + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "waitQueueSize": 100 + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool closed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + } + ] + } + ] + }, + { + "description": "waitQueueMultiple should be included in connection pool created message when specified", + "operations": [ + { + "name": "createEntities", + "object": "testRunner", + "arguments": { + "entities": [ + { + "client": { + "id": "client", + "observeEvents": [ + "poolReadyEvent" + ], + "observeLogMessages": { + "connection": "debug" + }, + "uriOptions": { + "waitQueueSize": 5 + } + } + } + ] + } + }, + { + "name": "waitForEvent", + "object": "testRunner", + "arguments": { + "client": "client", + "event": { + "poolReadyEvent": {} + }, + "count": 1 + } + }, + { + "name": "close", + "object": "client" + } + ], + "expectLogMessages": [ + { + "client": "client", + "messages": [ + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool created", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + }, + "waitQueueMultiple": 5 + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool ready", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + }, + { + "level": "debug", + "component": "connection", + "data": { + "message": "Connection pool closed", + "serverHost": { + "$$type": "string" + }, + "serverPort": { + "$$type": [ + "int", + "long" + ] + } + } + } + ] + } + ] + } + ] +} diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml new file mode 100644 index 0000000000..c32e38579a --- /dev/null +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml @@ -0,0 +1,311 @@ +description: "connection-logging" + +schemaVersion: "1.13" + +runOnRequirements: + - topologies: + - single # The number of log messages is different for each topology since there is a connection pool per host. + +tests: + - description: "Options should be included in connection pool created message when specified" + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + # Observe and wait on a connection ready event for the connection created in the background. + # This is to avoid raciness around whether the background thread has created the connection + # (and whether corresponding log messages have been generated) by the time we close the client. + observeEvents: + - connectionReadyEvent + observeLogMessages: + connection: debug + uriOptions: + minPoolSize: 1 + maxPoolSize: 5 + maxIdleTimeMS: 10000 + + - name: waitForEvent + object: testRunner + arguments: + client: *client + event: + connectionReadyEvent: {} + count: 1 + + - name: close + object: *client + + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + minPoolSize: 1 + maxPoolSize: 5 + maxIdleTimeMS: 10000 + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection created" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection ready" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection closed" + driverConnectionId: { $$type: [int, long] } + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + reason: "Connection pool was closed" + + - level: debug + component: connection + data: + message: "Connection pool closed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + # Drivers who have not done DRIVERS-1943 will need to skip this test. + - description: "maxConnecting should be included in connection pool created message when specified" + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is + # ready by the time we close the client, in order to avoid raciness in which messages + # ar eemitted. + observeEvents: + - poolReadyEvent + observeLogMessages: + connection: debug + uriOptions: + maxConnecting: 5 + + - name: waitForEvent + object: testRunner + arguments: + client: *client + event: + poolReadyEvent: {} + count: 1 + + - name: close + object: *client + + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + maxConnecting: 5 + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool closed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + # Drivers that do not support waitQueueTimeoutMS will need to skip this test. + - description: "waitQueueTimeoutMS should be included in connection pool created message when specified" + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is + # ready by the time we close the client, in order to avoid raciness in which messages + # ar eemitted. + observeEvents: + - poolReadyEvent + observeLogMessages: + connection: debug + uriOptions: + waitQueueTimeoutMS: 10000 + + - name: waitForEvent + object: testRunner + arguments: + client: *client + event: + poolReadyEvent: {} + count: 1 + + - name: close + object: *client + + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + waitQueueTimeoutMS: 10000 + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool closed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + # Drivers that do not support waitQueueSize will need to skip this test. + - description: "waitQueueSize should be included in connection pool created message when specified" + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is + # ready by the time we close the client, in order to avoid raciness in which messages + # ar eemitted. + observeEvents: + - poolReadyEvent + observeLogMessages: + connection: debug + uriOptions: + waitQueueSize: 100 + + - name: waitForEvent + object: testRunner + arguments: + client: *client + event: + poolReadyEvent: {} + count: 1 + + - name: close + object: *client + + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + waitQueueSize: 100 + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool closed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + # Drivers that do not support waitQueueMultiple will need to skip this test. + - description: "waitQueueMultiple should be included in connection pool created message when specified" + operations: + - name: createEntities + object: testRunner + arguments: + entities: + - client: + id: &client client + # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is + # ready by the time we close the client, in order to avoid raciness in which messages + # ar eemitted. + observeEvents: + - poolReadyEvent + observeLogMessages: + connection: debug + uriOptions: + waitQueueSize: 5 + + - name: waitForEvent + object: testRunner + arguments: + client: *client + event: + poolReadyEvent: {} + count: 1 + + - name: close + object: *client + + expectLogMessages: + - client: *client + messages: + - level: debug + component: connection + data: + message: "Connection pool created" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + waitQueueMultiple: 5 + + - level: debug + component: connection + data: + message: "Connection pool ready" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } + + - level: debug + component: connection + data: + message: "Connection pool closed" + serverHost: { $$type: string } + serverPort: { $$type: [int, long] } diff --git a/source/unified-test-format/unified-test-format.rst b/source/unified-test-format/unified-test-format.rst index 5320dc4242..0f38753378 100644 --- a/source/unified-test-format/unified-test-format.rst +++ b/source/unified-test-format/unified-test-format.rst @@ -1634,6 +1634,16 @@ specifications: Client operations that require special handling or are not documented by an existing specification are described below. +close +~~~~~ + +Closes the client, i.e. close underlying connection pool(s) and cease monitoring +the topology. For languages that rely on built-in language mechanisms such as reference +counting to automatically close/deinitialize clients once they go out of scope, this may +require implementing an abstraction to allow a client entity's underlying client to be set +to null. Because drivers do not consistently propagate errors encountered while closing a +client, test files SHOULD NOT specify `expectResult `_ or +`expectError `_ for this operation. .. _client_createChangeStream: @@ -3882,6 +3892,7 @@ Changelog .. Please note schema version bumps in changelog entries where applicable. +:2022-10-17: Add description of a `close` operation for client entities. :2022-10-14: **Schema version 1.13.** Add support for logging assertions via the ``observeLogMessages`` field for client entities, along with a new top-level field ``expectLogMessages`` From c3a6104713ecdf7f10aebd0aa6875c42f03679d0 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Tue, 18 Oct 2022 17:38:13 -0400 Subject: [PATCH 02/10] restrict test using failCommand to 4.0+ --- .../tests/logging/connection-logging.json | 6 ++++-- .../tests/logging/connection-logging.yml | 4 ++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json index c6ba297f7b..a2cd69f965 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json @@ -234,7 +234,8 @@ "description": "Connection checkout fails due to error establishing connection", "runOnRequirements": [ { - "auth": true + "auth": true, + "minServerVersion": "4.0" } ], "operations": [ @@ -248,7 +249,8 @@ "id": "client", "uriOptions": { "retryReads": false, - "appname": "clientAppName" + "appname": "clientAppName", + "heartbeatFrequencyMS": 10000 }, "observeLogMessages": { "connection": "debug" diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml index 6925d17d0c..063e3d39dc 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml @@ -103,6 +103,7 @@ tests: - description: "Connection checkout fails due to error establishing connection" runOnRequirements: - auth: true + minServerVersion: "4.0" # failCommand was added to mongod in 4.0 operations: - name: createEntities object: testRunner @@ -113,6 +114,9 @@ tests: uriOptions: retryReads: false appname: &clientAppName clientAppName + # use a high heartbeatFrequencyMS to avoid a successful monitor check marking the pool as + # ready (and emitting another event) during the course of test execution. + heartbeatFrequencyMS: 10000 observeLogMessages: connection: debug - name: failPoint From cec597514986fd64f94c60e38d36825bc4c6bf61 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Thu, 20 Oct 2022 17:24:08 -0400 Subject: [PATCH 03/10] add a sentence clarifying a client entity should not be used after it is closed --- source/unified-test-format/unified-test-format.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/unified-test-format/unified-test-format.rst b/source/unified-test-format/unified-test-format.rst index 0f38753378..8ce115d2f4 100644 --- a/source/unified-test-format/unified-test-format.rst +++ b/source/unified-test-format/unified-test-format.rst @@ -1643,7 +1643,9 @@ counting to automatically close/deinitialize clients once they go out of scope, require implementing an abstraction to allow a client entity's underlying client to be set to null. Because drivers do not consistently propagate errors encountered while closing a client, test files SHOULD NOT specify `expectResult `_ or -`expectError `_ for this operation. +`expectError `_ for this operation. Test files SHOULD NOT +specify any operations for a client entity following a `close` operation on it, as +driver behavior when an operation is attempted on a closed client is not consistent. .. _client_createChangeStream: From de7361e8630e45df9a4f23ad1d869de0a4f8eb3d Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Mon, 31 Oct 2022 17:54:02 -0400 Subject: [PATCH 04/10] address review comments --- .../connection-monitoring-and-pooling.rst | 29 ++++++++++--------- .../tests/logging/connection-logging.json | 2 +- .../tests/logging/connection-logging.yml | 2 +- 3 files changed, 17 insertions(+), 16 deletions(-) diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst index c14d15379a..df1efaad9a 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst @@ -1010,7 +1010,7 @@ The log messages are intended to match the information contained in the events a subscriber if it is convenient to do so. The types used in the structured message definitions below are demonstrative, and drivers MAY use similar types instead so long as the information -is present (e.g. a double instead of an integer, or a string instead of an integer if the structured logging framework does not support numeric types.) +is present (e.g. a double instead of an integer, or a string instead of an integer if the structured logging framework does not support numeric types). Common Fields ------------- @@ -1026,11 +1026,12 @@ All connection log messages MUST contain the following key-value pairs: * - serverHost - String - - the hostname or IP address for the endpoint the pool is for. + - the hostname, IP address, or Unix domain socket path for the endpoint the pool is for. * - serverPort - Int - - The port for the endpoint the pool is for. Optional; only present if a port was specified. + - The port for the endpoint the pool is for. Optional; not present for Unix domain sockets. When + the user does not specify a port and the default (27017) is used, the driver SHOULD include it here. Pool Created Message --------------------- @@ -1082,7 +1083,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection pool created for host with hostname {{serverHost}} on port {{serverPort}} using options maxIdleTimeMS={{maxIdleTimeMS}}, + Connection pool created for {{serverHost}}:{{serverPort}} using options maxIdleTimeMS={{maxIdleTimeMS}}, minPoolSize={{minPoolSize}}, maxPoolSize={{maxPoolSize}}, maxConnecting={{maxConnecting}}, waitQueueTimeoutMS={{waitQueueTimeoutMS}}, waitQueueSize={{waitQueueSize}}, waitQueueMultiple={{waitQueueMultiple}} @@ -1104,7 +1105,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection pool ready for host with hostname {{serverHost}} on port {{serverPort}} + Connection pool ready for {{serverHost}}:{{serverPort}} Pool Cleared Message -------------------- @@ -1128,7 +1129,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection pool cleared for serviceId {{serviceId}} and host with hostname {{serverHost}} on port {{serverPort}} + Connection pool for {{serverHost}}:{{serverPort}} cleared for serviceId {{serviceId}} Pool Closed Message ------------------- @@ -1148,7 +1149,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection pool closed for host with hostname {{serverHost}} on port {{serverPort}} + Connection pool closed for {{serverHost}}:{{serverPort}} Connection Created Message -------------------------- @@ -1172,7 +1173,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection created with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + Connection created with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} Connection Ready Message ------------------------ @@ -1196,7 +1197,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection ready with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + Connection ready with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} Connection Closed Message ------------------------- @@ -1230,7 +1231,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection closed with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}}. Reason: {{reason}} + Connection closed with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}}. Reason: {{reason}} Connection Checkout Started Message ----------------------------------- @@ -1250,7 +1251,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Checkout started for connection to host with hostname {{serverHost}} on port {{serverPort}} + Checkout started for connection to {{serverHost}}:{{serverPort}} Connection Checkout Failed Message ----------------------------------- @@ -1279,7 +1280,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Checkout failed for connection to host with hostname {{serverHost}} on port {{serverPort}} + Checkout failed for connection to {{serverHost}}:{{serverPort}}. Reason: {{reason}} Connection Checked Out ----------------------- @@ -1303,7 +1304,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection checked out with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + Connection checked out with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} Connection Checked In --------------------- @@ -1327,7 +1328,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection checked in with driver ID {{driverConnectionId}} to host with hostname {{serverHost}} on port {{serverPort}} + Connection checked in with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} Connection Pool Errors ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json index a2cd69f965..6806ae5086 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json @@ -418,7 +418,7 @@ "long" ] }, - "reason": "An error occurred while trying to establish a connection" + "reason": "An error occurred while trying to establish a new connection" } } ] diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml index 063e3d39dc..2076d09c9a 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml @@ -191,4 +191,4 @@ tests: message: "Connection checkout failed" serverHost: { $$type: string } serverPort: { $$type: [int, long] } - reason: "An error occurred while trying to establish a connection" + reason: "An error occurred while trying to establish a new connection" From a851d914057c1cbd89fbdd316ca86c16adf46d95 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Mon, 31 Oct 2022 17:56:09 -0400 Subject: [PATCH 05/10] Update unified-test-format.rst --- source/unified-test-format/unified-test-format.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/unified-test-format/unified-test-format.rst b/source/unified-test-format/unified-test-format.rst index 8ce115d2f4..826d5255cf 100644 --- a/source/unified-test-format/unified-test-format.rst +++ b/source/unified-test-format/unified-test-format.rst @@ -1644,8 +1644,9 @@ require implementing an abstraction to allow a client entity's underlying client to null. Because drivers do not consistently propagate errors encountered while closing a client, test files SHOULD NOT specify `expectResult `_ or `expectError `_ for this operation. Test files SHOULD NOT -specify any operations for a client entity following a `close` operation on it, as -driver behavior when an operation is attempted on a closed client is not consistent. +specify any operations for a client entity or any entity descended from it following +a `close` operation on it, as driver behavior when an operation is attempted on a closed +client or one of its descendant objects is not consistent. .. _client_createChangeStream: From 027e988bde49cfb9fba738d21dc6d307f7bad2e8 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Tue, 1 Nov 2022 13:28:55 -0400 Subject: [PATCH 06/10] remove unneeded client close operations and pool closed message expectations from tests --- .../logging/connection-pool-options.json | 123 ------------------ .../tests/logging/connection-pool-options.yml | 61 +-------- 2 files changed, 2 insertions(+), 182 deletions(-) diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json index a35675b55f..e67804915c 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.json @@ -46,10 +46,6 @@ }, "count": 1 } - }, - { - "name": "close", - "object": "client" } ], "expectLogMessages": [ @@ -134,45 +130,6 @@ ] } } - }, - { - "level": "debug", - "component": "connection", - "data": { - "message": "Connection closed", - "driverConnectionId": { - "$$type": [ - "int", - "long" - ] - }, - "serverHost": { - "$$type": "string" - }, - "serverPort": { - "$$type": [ - "int", - "long" - ] - }, - "reason": "Connection pool was closed" - } - }, - { - "level": "debug", - "component": "connection", - "data": { - "message": "Connection pool closed", - "serverHost": { - "$$type": "string" - }, - "serverPort": { - "$$type": [ - "int", - "long" - ] - } - } } ] } @@ -213,10 +170,6 @@ }, "count": 1 } - }, - { - "name": "close", - "object": "client" } ], "expectLogMessages": [ @@ -255,22 +208,6 @@ ] } } - }, - { - "level": "debug", - "component": "connection", - "data": { - "message": "Connection pool closed", - "serverHost": { - "$$type": "string" - }, - "serverPort": { - "$$type": [ - "int", - "long" - ] - } - } } ] } @@ -311,10 +248,6 @@ }, "count": 1 } - }, - { - "name": "close", - "object": "client" } ], "expectLogMessages": [ @@ -353,22 +286,6 @@ ] } } - }, - { - "level": "debug", - "component": "connection", - "data": { - "message": "Connection pool closed", - "serverHost": { - "$$type": "string" - }, - "serverPort": { - "$$type": [ - "int", - "long" - ] - } - } } ] } @@ -409,10 +326,6 @@ }, "count": 1 } - }, - { - "name": "close", - "object": "client" } ], "expectLogMessages": [ @@ -451,22 +364,6 @@ ] } } - }, - { - "level": "debug", - "component": "connection", - "data": { - "message": "Connection pool closed", - "serverHost": { - "$$type": "string" - }, - "serverPort": { - "$$type": [ - "int", - "long" - ] - } - } } ] } @@ -507,10 +404,6 @@ }, "count": 1 } - }, - { - "name": "close", - "object": "client" } ], "expectLogMessages": [ @@ -549,22 +442,6 @@ ] } } - }, - { - "level": "debug", - "component": "connection", - "data": { - "message": "Connection pool closed", - "serverHost": { - "$$type": "string" - }, - "serverPort": { - "$$type": [ - "int", - "long" - ] - } - } } ] } diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml index c32e38579a..59a31c3fe5 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml @@ -17,7 +17,8 @@ tests: id: &client client # Observe and wait on a connection ready event for the connection created in the background. # This is to avoid raciness around whether the background thread has created the connection - # (and whether corresponding log messages have been generated) by the time we close the client. + # (and whether corresponding log messages have been generated) by the time log message assertions + # are made. observeEvents: - connectionReadyEvent observeLogMessages: @@ -35,9 +36,6 @@ tests: connectionReadyEvent: {} count: 1 - - name: close - object: *client - expectLogMessages: - client: *client messages: @@ -74,22 +72,6 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } - - level: debug - component: connection - data: - message: "Connection closed" - driverConnectionId: { $$type: [int, long] } - serverHost: { $$type: string } - serverPort: { $$type: [int, long] } - reason: "Connection pool was closed" - - - level: debug - component: connection - data: - message: "Connection pool closed" - serverHost: { $$type: string } - serverPort: { $$type: [int, long] } - # Drivers who have not done DRIVERS-1943 will need to skip this test. - description: "maxConnecting should be included in connection pool created message when specified" operations: @@ -117,9 +99,6 @@ tests: poolReadyEvent: {} count: 1 - - name: close - object: *client - expectLogMessages: - client: *client messages: @@ -138,13 +117,6 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } - - level: debug - component: connection - data: - message: "Connection pool closed" - serverHost: { $$type: string } - serverPort: { $$type: [int, long] } - # Drivers that do not support waitQueueTimeoutMS will need to skip this test. - description: "waitQueueTimeoutMS should be included in connection pool created message when specified" operations: @@ -172,9 +144,6 @@ tests: poolReadyEvent: {} count: 1 - - name: close - object: *client - expectLogMessages: - client: *client messages: @@ -193,13 +162,6 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } - - level: debug - component: connection - data: - message: "Connection pool closed" - serverHost: { $$type: string } - serverPort: { $$type: [int, long] } - # Drivers that do not support waitQueueSize will need to skip this test. - description: "waitQueueSize should be included in connection pool created message when specified" operations: @@ -227,9 +189,6 @@ tests: poolReadyEvent: {} count: 1 - - name: close - object: *client - expectLogMessages: - client: *client messages: @@ -248,13 +207,6 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } - - level: debug - component: connection - data: - message: "Connection pool closed" - serverHost: { $$type: string } - serverPort: { $$type: [int, long] } - # Drivers that do not support waitQueueMultiple will need to skip this test. - description: "waitQueueMultiple should be included in connection pool created message when specified" operations: @@ -282,9 +234,6 @@ tests: poolReadyEvent: {} count: 1 - - name: close - object: *client - expectLogMessages: - client: *client messages: @@ -303,9 +252,3 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } - - level: debug - component: connection - data: - message: "Connection pool closed" - serverHost: { $$type: string } - serverPort: { $$type: [int, long] } From 97dc23ff744489f6555d779710f15f5df00ab735 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Tue, 1 Nov 2022 13:44:17 -0400 Subject: [PATCH 07/10] update comments --- .../tests/logging/connection-pool-options.yml | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml index 59a31c3fe5..b22693a92b 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-pool-options.yml @@ -82,8 +82,8 @@ tests: - client: id: &client client # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is - # ready by the time we close the client, in order to avoid raciness in which messages - # ar eemitted. + # ready by the time we assert on log messages, in order to avoid raciness around which messages + # are emitted. observeEvents: - poolReadyEvent observeLogMessages: @@ -127,8 +127,8 @@ tests: - client: id: &client client # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is - # ready by the time we close the client, in order to avoid raciness in which messages - # ar eemitted. + # ready by the time we assert on log messages, in order to avoid raciness around which messages + # are emitted. observeEvents: - poolReadyEvent observeLogMessages: @@ -172,8 +172,8 @@ tests: - client: id: &client client # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is - # ready by the time we close the client, in order to avoid raciness in which messages - # ar eemitted. + # ready by the time we assert on log messages, in order to avoid raciness around which messages + # are emitted. observeEvents: - poolReadyEvent observeLogMessages: @@ -217,8 +217,8 @@ tests: - client: id: &client client # Observe and wait for a poolReadyEvent so we can ensure the pool has been created and is - # ready by the time we close the client, in order to avoid raciness in which messages - # ar eemitted. + # ready by the time we assert on log messages, in order to avoid raciness around which messages + # are emitted. observeEvents: - poolReadyEvent observeLogMessages: @@ -251,4 +251,3 @@ tests: message: "Connection pool ready" serverHost: { $$type: string } serverPort: { $$type: [int, long] } - From 67096ae29de26c4ff92abfae173942184c29fe12 Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Tue, 1 Nov 2022 15:22:29 -0400 Subject: [PATCH 08/10] fix typo --- .../tests/logging/connection-logging.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml index 2076d09c9a..8201808810 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml @@ -99,7 +99,7 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } - # This test exists to probide coverage of checkout failed and pool cleared events. + # This test exists to provide coverage of checkout failed and pool cleared events. - description: "Connection checkout fails due to error establishing connection" runOnRequirements: - auth: true From bf59603120b7ea9c82236279180881cd87144a1b Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Thu, 3 Nov 2022 17:24:01 -0400 Subject: [PATCH 09/10] add errors to log messages where relevant --- .../connection-monitoring-and-pooling.rst | 14 ++++++++++++-- .../tests/logging/connection-logging.json | 10 ++++++++-- .../tests/logging/connection-logging.yml | 2 ++ 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst index df1efaad9a..6251e307df 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst @@ -1229,9 +1229,14 @@ In addition to the common fields defined above, this message MUST contain the fo - Error: "An error occurred while using the connection" - Pool closed: "Connection pool was closed" + * - error + - Flexible + - If ``reason`` is ``Error``, the associated error. The type and format of this value is flexible; see the + `logging specification <../logging/logging.rst#representing-errors-in-log-messages>`_ for details on representing errors in log messages. + The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection closed with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}}. Reason: {{reason}} + Connection closed with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}}. Reason: {{reason}}. Error: {{error}} Connection Checkout Started Message ----------------------------------- @@ -1278,9 +1283,14 @@ In addition to the common fields defined above, this message MUST contain the fo - ConnectionError: "An error occurred while trying to establish a new connection" - Pool closed: "Connection pool was closed" + * - error + - Flexible + - If ``reason`` is ``ConnectionError``, the associated error. The type and format of this value is flexible; see the + `logging specification <../logging/logging.rst#representing-errors-in-log-messages>`_ for details on representing errors in log messages. + The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Checkout failed for connection to {{serverHost}}:{{serverPort}}. Reason: {{reason}} + Checkout failed for connection to {{serverHost}}:{{serverPort}}. Reason: {{reason}}. Error: {{error}} Connection Checked Out ----------------------- diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json index 6806ae5086..e21a3d0497 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.json @@ -401,7 +401,10 @@ "long" ] }, - "reason": "An error occurred while using the connection" + "reason": "An error occurred while using the connection", + "error": { + "$$exists": true + } } }, { @@ -418,7 +421,10 @@ "long" ] }, - "reason": "An error occurred while trying to establish a new connection" + "reason": "An error occurred while trying to establish a new connection", + "error": { + "$$exists": true + } } } ] diff --git a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml index 8201808810..58ac7ec341 100644 --- a/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml +++ b/source/connection-monitoring-and-pooling/tests/logging/connection-logging.yml @@ -184,6 +184,7 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } reason: "An error occurred while using the connection" + error: { $$exists: true } - level: debug component: connection @@ -192,3 +193,4 @@ tests: serverHost: { $$type: string } serverPort: { $$type: [int, long] } reason: "An error occurred while trying to establish a new connection" + error: { $$exists: true } From 982914632a716bdc2b1cbbb4eab19300b83e270c Mon Sep 17 00:00:00 2001 From: Kaitlin Mahar Date: Thu, 3 Nov 2022 18:44:56 -0400 Subject: [PATCH 10/10] reword unstructured log messages --- .../connection-monitoring-and-pooling.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst index 6251e307df..0fe3811ae7 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst @@ -1173,7 +1173,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection created with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} + Connection created: address={{serverHost}}:{{serverPort}}, driver-generated ID={{driverConnectionId}} Connection Ready Message ------------------------ @@ -1197,7 +1197,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection ready with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} + Connection ready: address={{serverHost}}:{{serverPort}}, driver-generated ID={{driverConnectionId}} Connection Closed Message ------------------------- @@ -1236,7 +1236,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection closed with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}}. Reason: {{reason}}. Error: {{error}} + Connection closed: address={{serverHost}}:{{serverPort}}, driver-generated ID={{driverConnectionId}}. Reason: {{reason}}. Error: {{error}} Connection Checkout Started Message ----------------------------------- @@ -1314,7 +1314,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection checked out with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} + Connection checked out: address={serverHost}}:{{serverPort}}, driver-generated ID={{driverConnectionId}} Connection Checked In --------------------- @@ -1338,7 +1338,7 @@ In addition to the common fields defined above, this message MUST contain the fo The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: - Connection checked in with driver-generated ID {{driverConnectionId}} to {{serverHost}}:{{serverPort}} + Connection checked in: address={{serverHost}}:{{serverPort}}, driver-generated ID={{driverConnectionId}} Connection Pool Errors ~~~~~~~~~~~~~~~~~~~~~~