Cluster Monitoring

Overview

This guide shows you how to use the C driver to monitor server discovery and monitoring (SDAM) events in a MongoDB instance, replica set, or sharded cluster. These events occur when there are any changes in the state of the MongoDB instance or cluster that you are connected to.

You might use information about SDAM events in your application to understand cluster changes, assess cluster health, or perform capacity planning.

Subscribe to Events

You can access details about SDAM events by subscribing to them in your application. To subscribe to an event, define an Application Performance Monitoring (APM) callback function to handle each event type you want to subscribe to. Pass a mongoc_apm_callbacks_t object to the mongoc_client_set_apm_callbacks() function to register the list of APM callbacks with a client.

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

• Defines a server_opening() APM callback function

• Creates a mongoc_apm_callbacks_t object to store callbacks

• Calls the mongoc_apm_set_server_opening_cb() function, which stores a pointer to the provided APM callback function in the mongoc_apm_callbacks_t object

• Calls the mongoc_client_set_apm_callbacks() function, which registers the callback in the mongoc_apm_callbacks_t object with the client

1
#include <stdio.h>
2
#include <bson/bson.h>
3
#include <mongoc/mongoc.h>
4
5
typedef struct {
6
   int server_opening_events;
7
} stats_t;
8
9
static void
10
server_opening (const mongoc_apm_server_opening_t *event)
11
{
12
   stats_t *stats = (stats_t *) mongoc_apm_server_opening_get_context (event);
13
   stats->server_opening_events += 1;
14
15
   printf ("Server opening: %s\n", mongoc_apm_server_opening_get_host (event)->host_and_port);
16
}
17
18
int
19
main (void)
20
{
21
   mongoc_init ();
22
23
   stats_t stats = {0};
24
25
   mongoc_client_t *client = mongoc_client_new ("<connection string URI>");
26
   
27
   {
28
      mongoc_apm_callbacks_t *cbs = mongoc_apm_callbacks_new ();
29
      mongoc_apm_set_server_opening_cb (cbs, server_opening);
30
      mongoc_client_set_apm_callbacks (client, cbs, &stats);
31
      mongoc_apm_callbacks_destroy (cbs);
32
   }
33
34
   // Perform database operations
35
36
   mongoc_client_destroy (client);   
37
38
   printf ("Observed %d server opening events\n", stats.server_opening_events);
39
40
   mongoc_cleanup ();
41
42
   return EXIT_SUCCESS;
43
}

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 SDAM events by defining the corresponding APM callback function. The following table provides the name of each SDAM event, links to the type's API documentation, and describes when the event is published:

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 functions discussed in this guide, see the following API documentation:

• mongoc_apm_set_server_opening_cb()

• mongoc_client_set_apm_callbacks()