Monitor Application Events

Overview

In this guide, you can learn how to set up and configure monitoring in the MongoDB C++ Driver.

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

Monitoring the C++ driver lets you understand the driver's resource usage and performance. This information can help you make informed decisions when designing and debugging your application.

This guide shows how to perform the following tasks:

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

Tip

This guide explains how to use information about the activity of the driver in code. To learn how to record events in the driver, see the Log Driver Events guide.

Monitor Command Events

The C++ driver creates command events when your client runs a database command. For example, find, insert, delete, and count commands produce command events. You can initiate these commands by running the driver's standard create, read, update, or delete operations, or by using the database commands directly.

Tip

To learn more about database commands, see the Run a Command guide.

You can access details about command events by subscribing to them in your application. To subscribe to a command event, create a mongocxx::options::apm object to store your Application Performance Monitoring (APM) configuration. Then, pass the options to your mongocxx::client object. Call the following methods on the mongocxx::options::apm object to set command monitoring behavior:

Method	Description
`on_command_started()`	Specifies how the client responds when a command starts, which generates a `mongocxx::events::command_started_event`
`on_command_failed()`	Specifies how the client responds when a command does not succeed, which generates a `mongocxx::events::command_failed_event`
`on_command_succeeded()`	Specifies how the client responds when a command succeeds, which generates a `mongocxx::events::command_succeeded_event`

The following code monitors command started events by performing the following actions:

Calls the on_command_started() method on a mongocxx::options::apm object
Passes a callback to on_command_started() that prints each command's name and request ID
Configures your client with these options

1 #include <iostream>
2 #include <mongocxx/client.hpp>
3 #include <mongocxx/instance.hpp>
4 #include <mongocxx/uri.hpp>
5 #include <mongocxx/options/apm.hpp>
6 
7 int main() {
8     mongocxx::instance instance{};
9     
10     int command_started_events = 0;
11     
12     mongocxx::options::apm apm_opts;
13     apm_opts.on_command_started([&command_started_events](const mongocxx::events::command_started_event& event) {
14         command_started_events++;
15         std::cout << "Command started: " << event.command_name() 
16                   << " (request_id: " << event.request_id() << ")" << std::endl;
17     });
18     
19     mongocxx::uri uri("<connection string URI>");
20     mongocxx::options::client client_opts;
21     client_opts.apm_opts(apm_opts);
22     
23     mongocxx::client client{uri, client_opts};
24     
25     // Perform database operations
26     
27     std::cout << "Observed " << command_started_events << " command started events" << std::endl;
28     
29     return 0;
30 }

When you run a find command, the code prints messages that resemble the following sample output:

Command started: find (request_id: 3)

Monitor Server Discovery and Monitoring (SDAM) Events

The C++ driver creates topology events, also known as SDAM events, when the state of the instance or cluster that you connected to changes. For example, the driver creates an event when you establish a new connection or when the cluster elects a new primary node.

To learn more about topology events, see the Replication guide in the Server Manual.

You can access details about SDAM events by subscribing to them in your application. To subscribe to an SDAM event, create a mongocxx::options::apm object to store your APM configuration. Then, pass the options to your mongocxx::client object. Call the following methods on the mongocxx::options::apm object to set SDAM monitoring behavior:

Method	Description
`on_server_changed()`	Specifies how the client responds when the server description changes, which generates a `mongocxx::events::server_changed_event`
`on_server_opening()`	Specifies how the client responds when a new server is added to the topology, which generates a `mongocxx::events::server_opening_event`
`on_server_closed()`	Specifies how the client responds when a server is removed from the topology, which generates a `mongocxx::events::server_closed_event`
`on_topology_changed()`	Specifies how the client responds when the topology description changes, which generates a `mongocxx::events::topology_changed_event`
`on_topology_opening()`	Specifies how the client responds when the driver first connects to the cluster, which generates a `mongocxx::events::topology_opening_event`
`on_topology_closed()`	Specifies how the client responds when the driver disconnects from the cluster, which generates a `mongocxx::events::topology_closed_event`
`on_heartbeat_started()`	Specifies how the client responds when a heartbeat is sent to the server, which generates a `mongocxx::events::heartbeat_started_event`
`on_heartbeat_succeeded()`	Specifies how the client responds when a heartbeat succeeds, which generates a `mongocxx::events::heartbeat_succeeded_event`
`on_heartbeat_failed()`	Specifies how the client responds when a heartbeat fails, which generates a `mongocxx::events::heartbeat_failed_event`

The following code monitors server opening events by performing the following actions:

Calls the on_server_opening() method on a mongocxx::options::apm object
Passes a callback to on_server_opening() that prints each server's host and port
Configures your client with these options

1 #include <iostream>
2 #include <mongocxx/client.hpp>
3 #include <mongocxx/instance.hpp>
4 #include <mongocxx/uri.hpp>
5 #include <mongocxx/options/apm.hpp>
6 
7 int main() {
8     mongocxx::instance instance{};
9     
10     int server_opening_events = 0;
11     
12     mongocxx::options::apm apm_opts;
13     apm_opts.on_server_opening([&server_opening_events](const mongocxx::events::server_opening_event& event) {
14         server_opening_events++;
15         std::cout << "Server opening: " << event.host() << ":" << event.port() << std::endl;
16     });
17     
18     mongocxx::uri uri("<connection string URI>");
19     mongocxx::options::client client_opts;
20     client_opts.apm_opts(apm_opts);
21     
22     mongocxx::client client{uri, client_opts};
23     
24     // Perform database operations
25     
26     std::cout << "Observed " << server_opening_events << " server opening events" << std::endl;
27     
28     return 0;
29 }

When you perform a database operation, the driver establishes a new connection to the server, and your subscriber records the server opening event. The code outputs messages that resemble the following:

Server opening: <host>:<port number>

Event Descriptions

You can subscribe to monitoring events by creating a callback function that accepts an event class object as a parameter. The following table provides the name of each event class, links to the type's API documentation, and describes when the event is published:

Event Handler Class	Description
mongocxx::events::command_started_event	Created when a command is started.
mongocxx::events::command_succeeded_event	Created when a command succeeds.
mongocxx::events::command_failed_event	Created when a command fails.
mongocxx::events::server_changed_event	Created when the server description changes, such as when the server's type changes from secondary to primary.
mongocxx::events::server_opening_event	Created when a new server is added to the topology.
mongocxx::events::server_closed_event	Created when an existing server is removed from the topology.
mongocxx::events::topology_changed_event	Created when the topology description changes, such as when there is an election of a new primary.
mongocxx::events::topology_opening_event	Created when the driver first connects to the cluster.
mongocxx::events::topology_closed_event	Created when the driver disconnects from the cluster.
mongocxx::events::heartbeat_started_event	Created when the server monitor sends a `hello` command to the server. This action is called a heartbeat.
mongocxx::events::heartbeat_succeeded_event	Created when the heartbeat succeeds.
mongocxx::events::heartbeat_failed_event	Created when the heartbeat fails.

You can find information about each monitoring subscriber type and event method in the Application Performance Monitoring section of the API documentation.

API Documentation

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

Back

Logging

Change Streams

1	#include <iostream>
2	#include <mongocxx/client.hpp>
3	#include <mongocxx/instance.hpp>
4	#include <mongocxx/uri.hpp>
5	#include <mongocxx/options/apm.hpp>
6
7	int main() {
8	mongocxx::instance instance{};
9
10	int command_started_events = 0;
11
12	mongocxx::options::apm apm_opts;
13	apm_opts.on_command_started([&command_started_events](const mongocxx::events::command_started_event& event) {
14	command_started_events++;
15	std::cout << "Command started: " << event.command_name()
16	<< " (request_id: " << event.request_id() << ")" << std::endl;
17	});
18
19	mongocxx::uri uri("<connection string URI>");
20	mongocxx::options::client client_opts;
21	client_opts.apm_opts(apm_opts);
22
23	mongocxx::client client{uri, client_opts};
24
25	// Perform database operations
26
27	std::cout << "Observed " << command_started_events << " command started events" << std::endl;
28
29	return 0;
30	}