/ /

Monitor Application Events

Overview

This guide shows you how to set up and configure monitoring in the MongoDB Rust Driver.

Monitoring collects information about the activities of a running program, which you can use with an application performance management library.

Monitoring the Rust driver lets you understand the driver's resource usage and performance. This information helps you make informed decisions when you design and debug your application.

This guide shows you how to perform the following tasks:

Monitor Command Events
Monitor Server Discovery and Monitoring (SDAM) Events
Monitor Connection Pool Events

Monitor Command Events

You can use the Rust driver to monitor the outcome of commands that the driver sends to your MongoDB deployment.

Use information about command events in your application, or monitor commands to learn more about how the driver executes them.

Event Descriptions

You can monitor the following command events:

Event Name	Description
CommandStartedEvent	Created when a command starts.
CommandSucceededEvent	Created when a command succeeds.
CommandFailedEvent	Created when a command does not succeed.

Event Subscription Example

Monitor command events by assigning an EventHandler instance as the value of the command_event_handler client option. To construct an EventHandler that processes all command events, use the callback() or async_callback() method.

The following example connects to a MongoDB deployment, instructs the client to monitor command events, and prints each event:

let mut client_options = ClientOptions::parse("<connection string>").await?;
client_options.command_event_handler = Some(EventHandler::callback(|ev| println!("{:?}", ev)));
let client = Client::with_options(client_options)?;
// ... perform actions with the client to generate events

Monitor Server Discovery and Monitoring (SDAM) Events

You can use the Rust driver to monitor topology events in a MongoDB instance, replica set, or sharded cluster. The driver creates topology events, also known as Server Discovery and Monitoring (SDAM) events, when the state of the instance or cluster changes.

Use information about topology changes in your application, or monitor cluster changes to learn more about how they affect your application.

Event Descriptions

You can monitor the following SDAM events:

Event Name	Description
ServerDescriptionChangedEvent	Created when an instance state changes, such as when a replica set member changes from a secondary to a primary.
ServerOpeningEvent	Created when a connection to an instance, such as a replica set member, opens.
ServerClosedEvent	Created when a connection to an instance, such as a replica set member, closes.
TopologyDescriptionChangedEvent	Created when the topology description changes, such as when there is an election of a new primary or when a `mongos` proxy disconnects.
TopologyOpeningEvent	Created before the driver attempts to connect to an instance.
TopologyClosedEvent	Created after all instance connections in the topology close.
ServerHeartbeatStartedEvent	Created before the driver issues a `hello` command to an instance.
ServerHeartbeatSucceededEvent	Created when the `hello` command returns successfully from a MongoDB instance.
ServerHeartbeatFailedEvent	Created when a `hello` command to a MongoDB instance does not return a successful response.

Event Subscription Example

Monitor SDAM events by assigning an EventHandler instance as the value of the sdam_event_handler client option. To construct an EventHandler that processes all SDAM events, use the callback() or async_callback() method.

The following example connects to a MongoDB deployment, instructs the client to monitor SDAM events, and prints each event:

let mut client_options = ClientOptions::parse("<connection string>").await?;
client_options.sdam_event_handler = Some(EventHandler::callback(|ev| println!("{:?}", ev)));
let client = Client::with_options(client_options)?;
// ... perform actions with the client to generate events

Monitor Connection Pool Events

You can use the Rust driver to monitor the driver's connection pool. A connection pool is a set of open Transmission Control Protocol (TCP) connections that your driver maintains with a MongoDB instance. Connection pools reduce the number of new connections your application needs to create, which can make your application run faster.

Use information about changes to your connection pool in your application, or monitor the connection pool to learn more about how the driver uses connections.

Event Descriptions

You can monitor the following connection pool events:

Event Name	Description
PoolCreatedEvent	Created when a connection pool is created.
PoolReadyEvent	Created when a connection pool is ready.
PoolClearedEvent	Created when a connection pool is cleared.
PoolClosedEvent	Created when a connection pool is closed, before the destruction of the server instance.
ConnectionCreatedEvent	Created when a connection is created, but not necessarily when it is used for an operation.
ConnectionReadyEvent	Created after a connection successfully completes a handshake and is ready for operations.
ConnectionClosedEvent	Created when a connection is closed.
ConnectionCheckoutStartedEvent	Created when an operation attempts to acquire a connection for execution.
ConnectionCheckoutFailedEvent	Created when an operation cannot acquire a connection for execution.
ConnectionCheckedOutEvent	Created when an operation successfully acquires a connection for execution.
ConnectionCheckedInEvent	Created when a connection is checked back into the pool after an operation is executed.

Event Subscription Example

Monitor connection pool events by assigning an EventHandler instance as the value of the cmap_event_handler client option. To construct an EventHandler that processes all connection pool events, use the callback() or async_callback() method.

The following example connects to a MongoDB deployment, instructs the client to monitor connection pool events, and prints each event:

let mut client_options = ClientOptions::parse("<connection string>").await?;
client_options.cmap_event_handler = Some(EventHandler::callback(|ev| println!("{:?}", ev)));
let client = Client::with_options(client_options)?;
// ... perform actions with the client to generate events

Additional Information

To learn more about monitoring a MongoDB deployment, see the How to Monitor MongoDB article.

To learn more about improving the performance of your application, see the Performance Considerations guide.

API Documentation

To learn more about the methods and types mentioned in this guide, see the following API documentation:

Back

MongoDB Vector Search

Tracing and Logging