`monitoring` – Tools for monitoring driver events.¶

Tools to monitor driver events.

New in version 3.1.

Use register() 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:

import logging

from pymongo import monitoring

class CommandLogger(monitoring.CommandListener):

    def started(self, event):
        logging.info("Command {0.command_name} with request id "
                     "{0.request_id} started on server "
                     "{0.connection_id}".format(event))

    def succeeded(self, event):
        logging.info("Command {0.command_name} with request id "
                     "{0.request_id} on server {0.connection_id} "
                     "succeeded in {0.duration_micros} "
                     "microseconds".format(event))

    def failed(self, event):
        logging.info("Command {0.command_name} with request id "
                     "{0.request_id} on server {0.connection_id} "
                     "failed in {0.duration_micros} "
                     "microseconds".format(event))

monitoring.register(CommandLogger())

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

class ServerLogger(monitoring.ServerListener):

    def opened(self, event):
        logging.info("Server {0.server_address} added to topology "
                     "{0.topology_id}".format(event))

    def description_changed(self, event):
        previous_server_type = event.previous_description.server_type
        new_server_type = event.new_description.server_type
        if new_server_type != previous_server_type:
            # server_type_name was added in PyMongo 3.4
            logging.info(
                "Server {0.server_address} changed type from "
                "{0.previous_description.server_type_name} to "
                "{0.new_description.server_type_name}".format(event))

    def closed(self, event):
        logging.warning("Server {0.server_address} removed from topology "
                        "{0.topology_id}".format(event))


class HeartbeatLogger(monitoring.ServerHeartbeatListener):

    def started(self, event):
        logging.info("Heartbeat sent to server "
                     "{0.connection_id}".format(event))

    def succeeded(self, event):
        # The reply.document attribute was added in PyMongo 3.4.
        logging.info("Heartbeat to server {0.connection_id} "
                     "succeeded with reply "
                     "{0.reply.document}".format(event))

    def failed(self, event):
        logging.warning("Heartbeat to server {0.connection_id} "
                        "failed with error {0.reply}".format(event))

class TopologyLogger(monitoring.TopologyListener):

    def opened(self, event):
        logging.info("Topology with id {0.topology_id} "
                     "opened".format(event))

    def description_changed(self, event):
        logging.info("Topology description updated for "
                     "topology id {0.topology_id}".format(event))
        previous_topology_type = event.previous_description.topology_type
        new_topology_type = event.new_description.topology_type
        if new_topology_type != previous_topology_type:
            # topology_type_name was added in PyMongo 3.4
            logging.info(
                "Topology {0.topology_id} changed type from "
                "{0.previous_description.topology_type_name} to "
                "{0.new_description.topology_type_name}".format(event))
        # The has_writable_server and has_readable_server methods
        # were added in PyMongo 3.4.
        if not event.new_description.has_writable_server():
            logging.warning("No writable servers available.")
        if not event.new_description.has_readable_server():
            logging.warning("No readable servers available.")

    def closed(self, event):
        logging.info("Topology with id {0.topology_id} "
                     "closed".format(event))

Event listeners can also be registered per instance of MongoClient:

client = MongoClient(event_listeners=[CommandLogger()])

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. started()) 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.

Parameters

listener: A subclasses of CommandListener, ServerHeartbeatListener, ServerListener, or TopologyListener.

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 CommandStartedEvent.

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 ServerClosedEvent.

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 ServerOpeningEvent.

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 ServerHeartbeatStartedEvent.

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 TopologyClosedEvent.

description_changed(event)¶

Abstract method to handle a TopologyDescriptionChangedEvent.

Parameters

event: An instance of TopologyDescriptionChangedEvent.

opened(event)¶

Abstract method to handle a TopologyOpenedEvent.

Parameters

event: An instance of TopologyOpenedEvent.

class pymongo.monitoring.CommandStartedEvent(command, database_name, *args)¶

Event published when a command starts.

Parameters

command: The command document.
database_name: The name of the database this command was run against.
request_id: The request id for this operation.
connection_id: The address (host, port) of the server this command was sent to.
operation_id: An optional identifier for a series of related events.

property command¶: The command document.

property command_name¶: The command name.

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

property database_name¶: The name of the database this command was run against.

property operation_id¶: An id for this series of events or None.

property request_id¶: The request id for this operation.

class pymongo.monitoring.CommandSucceededEvent(duration, reply, command_name, request_id, connection_id, operation_id)¶

Event published when a command succeeds.

Parameters

duration: The command duration as a datetime.timedelta.
reply: The server reply document.
command_name: The command name.
request_id: The request id for this operation.
connection_id: The address (host, port) of the server this command was sent to.
operation_id: An optional identifier for a series of related events.

property command_name¶: The command name.

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

property duration_micros¶: The duration of this operation in microseconds.

property operation_id¶: An id for this series of events or None.

property reply¶: The server failure document for this operation.

property request_id¶: The request id for this operation.

class pymongo.monitoring.CommandFailedEvent(duration, failure, *args)¶

Event published when a command fails.

Parameters

duration: The command duration as a datetime.timedelta.
failure: The server reply document.
command_name: The command name.
request_id: The request id for this operation.
connection_id: The address (host, port) of the server this command was sent to.
operation_id: An optional identifier for a series of related events.

property command_name¶: The command name.

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

property duration_micros¶: The duration of this operation in microseconds.

property failure¶: The server failure document for this operation.

property operation_id¶: An id for this series of events or None.

property request_id¶: The request id for this operation.

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

Published when server description changes.

New in version 3.3.

property new_description¶: The new ServerDescription.

property previous_description¶: The previous ServerDescription.

property server_address¶: The address (host/port pair) of the server

property 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.

property server_address¶: The address (host/port pair) of the server

property 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.

property server_address¶: The address (host/port pair) of the server

property 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.

property new_description¶: The new TopologyDescription.

property previous_description¶: The previous TopologyDescription.

property 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.

property 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.

property 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.

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

class pymongo.monitoring.ServerHeartbeatSucceededEvent(duration, reply, *args)¶

Fired when the server heartbeat succeeds.

New in version 3.3.

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

property duration¶: The duration of this heartbeat in microseconds.

property reply¶: An instance of IsMaster.

class pymongo.monitoring.ServerHeartbeatFailedEvent(duration, reply, *args)¶

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

New in version 3.3.

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

property duration¶: The duration of this heartbeat in microseconds.

property reply¶: A subclass of Exception.

`monitoring` – Tools for monitoring driver events.¶

Previous topic

Next topic

This Page

monitoring – Tools for monitoring driver events.¶

`monitoring` – Tools for monitoring driver events.¶