monitoring – Tools for monitoring driver events.

New in version 3.1.

Attention

Starting in PyMongo 3.11, the monitoring classes outlined below are included in the PyMongo distribution under the event_loggers submodule.

Use to register global listeners for specific events. Listeners must inherit from one of the abstract classes below and implement the correct functions for that class.

For example, a simple command logger might be implemented like this:

Server discovery and monitoring events are also available. For example:

Connection monitoring and pooling events are also available. For example:

Event listeners can also be registered per instance of MongoClient:

Note that previously registered global listeners are automatically included when configuring per client event listeners. Registering a new global listener will not add that listener to existing client instances.

Note

Events are delivered synchronously. Application threads block waiting for event handlers (e.g. ) to return. Care must be taken to ensure that your event handlers are efficient enough to not adversely affect overall application performance.

Warning

The command documents published through this API are not copies. If you intend to modify them in any way you must copy them in your event handler first.

pymongo.monitoring.register(listener)

Register a global event listener.

class pymongo.monitoring.CommandListener

Abstract base class for command listeners.

Handles CommandStartedEvent, CommandSucceededEvent, and CommandFailedEvent.

• failed(event)

  Abstract method to handle a CommandFailedEvent.

  Parameters:	event: An instance of CommandFailedEvent.

• started(event)

  Abstract method to handle a CommandStartedEvent.

  Parameters:	event: An instance of .

• succeeded(event)

  Abstract method to handle a CommandSucceededEvent.

  Parameters:	event: An instance of CommandSucceededEvent.

class pymongo.monitoring.ServerListener

Abstract base class for server listeners. Handles ServerOpeningEvent, ServerDescriptionChangedEvent, and ServerClosedEvent.

New in version 3.3.

• closed(event)

  Abstract method to handle a ServerClosedEvent.

  Parameters:	event: An instance of .

• description_changed(event)

  Abstract method to handle a ServerDescriptionChangedEvent.

  Parameters:	event: An instance of ServerDescriptionChangedEvent.

• opened(event)

  Abstract method to handle a ServerOpeningEvent.

  Parameters:	event: An instance of .

class pymongo.monitoring.ServerHeartbeatListener

Abstract base class for server heartbeat listeners.

Handles ServerHeartbeatStartedEvent, ServerHeartbeatSucceededEvent, and ServerHeartbeatFailedEvent.

New in version 3.3.

• failed(event)

  Abstract method to handle a ServerHeartbeatFailedEvent.

  Parameters:	event: An instance of ServerHeartbeatFailedEvent.

• started(event)

  Abstract method to handle a ServerHeartbeatStartedEvent.

  Parameters:	event: An instance of .

• succeeded(event)

  Abstract method to handle a ServerHeartbeatSucceededEvent.

  Parameters:	event: An instance of ServerHeartbeatSucceededEvent.

class pymongo.monitoring.TopologyListener

Abstract base class for topology monitoring listeners. Handles TopologyOpenedEvent, TopologyDescriptionChangedEvent, and TopologyClosedEvent.

New in version 3.3.

• closed(event)

  Abstract method to handle a TopologyClosedEvent.

  Parameters:	event: An instance of .

• description_changed(event)

  Abstract method to handle a TopologyDescriptionChangedEvent.

  Parameters:	event: An instance of TopologyDescriptionChangedEvent.

• opened(event)

  Abstract method to handle a TopologyOpenedEvent.

class pymongo.monitoring.ConnectionPoolListener

Abstract base class for connection pool listeners.

Handles all of the connection pool events defined in the Connection Monitoring and Pooling Specification: , PoolClearedEvent, , ConnectionCreatedEvent, , ConnectionClosedEvent, , ConnectionCheckOutFailedEvent, , and ConnectionCheckedInEvent.

New in version 3.9.

• connection_check_out_failed(event)

  Abstract method to handle a .

  Emitted when the driver’s attempt to check out a connection fails.

  Parameters:	event: An instance of ConnectionCheckOutFailedEvent.

• connection_check_out_started(event)

  Abstract method to handle a .

  Emitted when the driver starts attempting to check out a connection.

  Parameters:	event: An instance of ConnectionCheckOutStartedEvent.

• connection_checked_in(event)

  Abstract method to handle a .

  Emitted when the driver checks in a Connection back to the Connection Pool.

  Parameters:	event: An instance of ConnectionCheckedInEvent.

• connection_checked_out(event)

  Abstract method to handle a .

  Emitted when the driver successfully checks out a Connection.

  Parameters:	event: An instance of ConnectionCheckedOutEvent.

• connection_closed(event)

  Abstract method to handle a .

  Emitted when a Connection Pool closes a Connection.

  Parameters:	event: An instance of ConnectionClosedEvent.

• connection_created(event)

  Abstract method to handle a .

  Emitted when a Connection Pool creates a Connection object.

  Parameters:	event: An instance of ConnectionCreatedEvent.

• connection_ready(event)

  Abstract method to handle a .

  Emitted when a Connection has finished its setup, and is now ready to use.

  Parameters:	event: An instance of ConnectionReadyEvent.

• pool_cleared(event)

  Abstract method to handle a PoolClearedEvent.

  Emitted when a Connection Pool is cleared.

  Parameters:	event: An instance of .

• pool_closed(event)

  Abstract method to handle a PoolClosedEvent.

  Emitted when a Connection Pool is closed.

  Parameters:	event: An instance of PoolClosedEvent.

• pool_created(event)

  Abstract method to handle a .

  Emitted when a Connection Pool is created.

  Parameters:	event: An instance of PoolCreatedEvent.

class pymongo.monitoring.CommandStartedEvent(command, database_name, request_id, connection_id, operation_id, service_id=None)

Event published when a command starts.

• command

  The command document.

• command_name

  The command name.

• connection_id

  The address (host, port) of the server this command was sent to.

• database_name

  The name of the database this command was run against.

• operation_id

  An id for this series of events or None.

• request_id

  The request id for this operation.

• service_id

  New in version 3.12.

class pymongo.monitoring.CommandSucceededEvent(duration, reply, command_name, request_id, connection_id, operation_id, service_id=None)

Event published when a command succeeds.

• command_name

  The command name.

• The address (host, port) of the server this command was sent to.

• duration_micros

  The duration of this operation in microseconds.

• operation_id

  An id for this series of events or None.

• reply

  The server failure document for this operation.

• request_id

  The request id for this operation.

• service_id

  The service_id this command was sent to, or None.

  New in version 3.12.

class pymongo.monitoring.CommandFailedEvent(duration, failure, command_name, request_id, connection_id, operation_id, service_id=None)

Event published when a command fails.

• command_name

  The command name.

• connection_id

  The address (host, port) of the server this command was sent to.

• duration_micros

  The duration of this operation in microseconds.

• failure

  The server failure document for this operation.

• operation_id

  An id for this series of events or None.

• request_id

  The request id for this operation.

• service_id

  The service_id this command was sent to, or None.

  New in version 3.12.

class pymongo.monitoring.ServerDescriptionChangedEvent(previous_description, new_description, \args*)

Published when server description changes.

New in version 3.3.

• new_description

  The new .

• previous_description

  The previous ServerDescription.

• server_address

  The address (host, port) pair of the server

• topology_id

  A unique identifier for the topology this server is a part of.

class pymongo.monitoring.ServerOpeningEvent(server_address, topology_id)

Published when server is initialized.

New in version 3.3.

• server_address

  The address (host, port) pair of the server

• topology_id

  A unique identifier for the topology this server is a part of.

class pymongo.monitoring.ServerClosedEvent(server_address, topology_id)

Published when server is closed.

New in version 3.3.

• server_address

  The address (host, port) pair of the server

• topology_id

  A unique identifier for the topology this server is a part of.

class pymongo.monitoring.TopologyDescriptionChangedEvent(previous_description, new_description, \args*)

Published when the topology description changes.

New in version 3.3.

• new_description

  The new .

• previous_description

  The previous TopologyDescription.

• topology_id

  A unique identifier for the topology this server is a part of.

class pymongo.monitoring.TopologyOpenedEvent(topology_id)

Published when the topology is initialized.

New in version 3.3.

• topology_id

  A unique identifier for the topology this server is a part of.

class pymongo.monitoring.TopologyClosedEvent(topology_id)

Published when the topology is closed.

New in version 3.3.

• topology_id

  A unique identifier for the topology this server is a part of.

class pymongo.monitoring.ServerHeartbeatStartedEvent(connection_id)

Published when a heartbeat is started.

New in version 3.3.

• connection_id

  The address (host, port) of the server this heartbeat was sent to.

class pymongo.monitoring.ServerHeartbeatSucceededEvent(duration, reply, connection_id, awaited=False)

Fired when the server heartbeat succeeds.

New in version 3.3.

• awaited

  Whether the heartbeat was awaited.

  If true, then reflects the sum of the round trip time to the server and the time that the server waited before sending a response.

• duration

  The duration of this heartbeat in microseconds.

• reply

  An instance of IsMaster.

  Warning

  is deprecated. Starting with PyMongo 4.0 this attribute will return an instance of Hello, which provides the same API.

class (duration, reply, connection_id, awaited=False)

Fired when the server heartbeat fails, either with an “ok: 0” or a socket exception.

New in version 3.3.

• Whether the heartbeat was awaited.

  If true, then reflects the sum of the round trip time to the server and the time that the server waited before sending a response.

• connection_id

  The address (host, port) of the server this heartbeat was sent to.

• duration

  The duration of this heartbeat in microseconds.

• reply

  A subclass of Exception.

class pymongo.monitoring.PoolCreatedEvent(address, options)

Published when a Connection Pool is created.

New in version 3.9.

• address

  The address (host, port) pair of the server the pool is attempting to connect to.

• options

  Any non-default pool options that were set on this Connection Pool.

class pymongo.monitoring.PoolClearedEvent(address, service_id=None)

Published when a Connection Pool is cleared.

New in version 3.9.

• address

  The address (host, port) pair of the server the pool is attempting to connect to.

• service_id

  Connections with this service_id are cleared.

  When service_id is None, all connections in the pool are cleared.

  New in version 3.12.

class pymongo.monitoring.PoolClosedEvent(address)

Published when a Connection Pool is closed.

New in version 3.9.

• address

  The address (host, port) pair of the server the pool is attempting to connect to.

class pymongo.monitoring.ConnectionCreatedEvent(address, connection_id)

Published when a Connection Pool creates a Connection object.

NOTE: This connection is not ready for use until the is published.

New in version 3.9.

• address

  The address (host, port) pair of the server this connection is attempting to connect to.

• connection_id

  The ID of the Connection.

class pymongo.monitoring.ConnectionReadyEvent(address, connection_id)

Published when a Connection has finished its setup, and is ready to use.

New in version 3.9.

• address

  The address (host, port) pair of the server this connection is attempting to connect to.

• connection_id

  The ID of the Connection.

class pymongo.monitoring.ConnectionClosedReason

An enum that defines values for reason on a ConnectionClosedEvent.

New in version 3.9.

• ERROR = ‘error’

  The connection experienced an error, making it no longer valid.

• IDLE = ‘idle’

  The connection became stale by being idle for too long (maxIdleTimeMS).

• POOL_CLOSED = ‘poolClosed’

  The pool was closed, making the connection no longer valid.

• STALE = ‘stale’

  The pool was cleared, making the connection no longer valid.

class pymongo.monitoring.ConnectionClosedEvent(address, connection_id, reason)

Published when a Connection is closed.

New in version 3.9.

• address

  The address (host, port) pair of the server this connection is attempting to connect to.

• connection_id

  The ID of the Connection.

• reason

  A reason explaining why this connection was closed.

  The reason must be one of the strings from the enum.

class pymongo.monitoring.ConnectionCheckOutStartedEvent(address)

Published when the driver starts attempting to check out a connection.

New in version 3.9.

• address

  The address (host, port) pair of the server this connection is attempting to connect to.

class pymongo.monitoring.ConnectionCheckOutFailedReason

An enum that defines values for reason on a ConnectionCheckOutFailedEvent.

New in version 3.9.

• CONN_ERROR = ‘connectionError’

  The connection check out attempt experienced an error while setting up a new connection.

• POOL_CLOSED = ‘poolClosed’

  The pool was previously closed, and cannot provide new connections.

• TIMEOUT = ‘timeout’

  The connection check out attempt exceeded the specified timeout.

class pymongo.monitoring.ConnectionCheckOutFailedEvent(address, reason)

Published when the driver’s attempt to check out a connection fails.

New in version 3.9.

• address

  The address (host, port) pair of the server this connection is attempting to connect to.

• reason

  A reason explaining why connection check out failed.

  The reason must be one of the strings from the enum.

class pymongo.monitoring.ConnectionCheckedOutEvent(address, connection_id)

Published when the driver successfully checks out a Connection.

New in version 3.9.

• address

  The address (host, port) pair of the server this connection is attempting to connect to.

• connection_id

  The ID of the Connection.

class pymongo.monitoring.ConnectionCheckedInEvent(address, connection_id)

Published when the driver checks in a Connection into the Pool.

New in version 3.9.

• The address (host, port) pair of the server this connection is attempting to connect to.

• connection_id

  The ID of the Connection.