Monitoring¶
On this page
The driver allows the application to be notified when certain events happen. These events are organized into the following categories:
- Command monitoring
- Topology lifecycle
- Server lifecycle
- Server heartbeats
- Connection pools and connections
Topology and server events are part of Server Discovery and Monitoring (SDAM).
Command Monitoring¶
All user-initiated commands that are sent to the server publish events that
can be subscribed to for fine grained information. The monitoring API
publishes a guaranteed start event for each command, then either a succeeded
or a failed event. A subscriber must implement 3 methods: started
,
succeeded
, and failed
, each which takes a single parameter for
the event. The following is an example logging subscriber based on a
logging subscriber used internally by the driver:
To register a custom subscriber, you can do so globally for all clients or on a per-client basis:
Sample output:
Server Discovery And Monitoring¶
The Ruby driver implements Server Discovery And Monitoring (SDAM) specification. and makes the following events available to the application:
- Topology opening
- Server opening
- Server description changed
- Topology changed
- Server closed
- Topology closed
- Heartbeat events (covered below in a separate section)
For all events other than the heartbeat events, the succeeded
method
will be called on each event subscriber with the event as the sole argument.
Available data for events varies, therefore to log the events a separate
class is needed for each event type. A simple SDAM logging subscriber
can look like the following:
To subscribe to SDAM events globally:
Subscribing to SDAM events for a single client is a little more involved since the events may be published during the client’s construction:
Sample output:
Server Heartbeats¶
The application can be notified of each server heartbeat by subscribing to SERVER_HEARTBEAT topic. A server heartbeat listener must implement three methods: started, succeeded and failed. Each heartbeat invokes the started method on the listener, and then either succeeded or failed method depending on the outcome of the heartbeat.
All heartbeat events contain the address of the server that the heartbeat was sent to. Succeeded and failed events contain the round trip time for the ismaster command. Failed event also contains the exception instance that was raised during ismaster command execution. Please review the API documentation for ServerHeartbeatStarted, ServerHeartbeatSucceeded and ServerHeartbeatFailed for event attribute details.
The following is an example logging heartbeat event subscriber:
Similarly to command events, the application can subscribe to heartbeat events globally or for a specific client:
Sample output:
Connection Pool And Connection Monitoring¶
Each client maintains a connection pool for each server in the deployment that
it is aware of, and publishes events for both connection pools and individual
connections. To subscribe to these events, define a subscriber class implementing
the method pubished
which takes a single parameter for the event that
is being published. Note that future versions of the driver may introduce
additional events published through this mechanism.
The following events are currently implemented by the driver, following the CMAP specification:
- PoolCreated
- PoolCleared
- PoolClosed
- ConnectionCreated
- ConnectionReady
- ConnectionClosed
- ConnectionCheckOutStarted
- ConnectionCheckOutFailed
- ConnectionCheckOutSucceeded
- ConnectionCheckedIn
The driver provides a logging subscriber which may be used to log all connection pool and connection-related events. This subscriber is not enabled by default because it will create log entries for each operation performed by the application. To enable this subscriber globally or per client:
Sample output:
Disabling Monitoring¶
To turn off monitoring, set the client monitoring option to false
: