DOCSP-43082: Cluster monitoring

source/includes/monitoring/sdam.c

@@ -0,0 +1,43 @@
+#include <stdio.h>
+#include <bson/bson.h>
+#include <mongoc/mongoc.h>
+
+typedef struct {
+   int server_opening_events;
+} stats_t;
+
+static void
+server_opening (const mongoc_apm_server_opening_t *event)
+{
+   stats_t *stats = (stats_t *) mongoc_apm_server_opening_get_context (event);
+   stats->server_opening_events += 1;
+
+   printf ("Server opening: %s\n", mongoc_apm_server_opening_get_host (event)->host_and_port);
+}
+
+int
+main (void)
+{
+   mongoc_init ();
+
+   stats_t stats = {0};
+
+   mongoc_client_t *client = mongoc_client_new ("<connection string URI>");
+
+   {
+      mongoc_apm_callbacks_t *cbs = mongoc_apm_callbacks_new ();
+      mongoc_apm_set_server_opening_cb (cbs, server_opening);
+      mongoc_client_set_apm_callbacks (client, cbs, &stats);
+      mongoc_apm_callbacks_destroy (cbs);
+   }
+
+   // Perform database operations
+
+   mongoc_client_destroy (client);   
+
+   printf ("Observed %d server opening events\n", stats.server_opening_events);
+
+   mongoc_cleanup ();
+
+   return EXIT_SUCCESS;
+}

source/index.txt

@@ -11,6 +11,7 @@
    /databases-collections
    /read
    /indexes
+   /monitoring
    /aggregation
    /whats-new
    /compatibility

source/monitoring.txt

@@ -0,0 +1,11 @@
+.. _c-monitoring:
+
+========================
+Monitor Your Application
+========================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /monitoring/cluster-monitoring

source/monitoring/cluster-monitoring.txt

@@ -0,0 +1,128 @@
+.. _c-cluster-monitoring:
+
+==================
+Cluster Monitoring
+==================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, server, topology
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecols
+
+Overview
+--------
+
+This guide shows you how to use the {+driver-short+} 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.
+
+.. _c-subscribe-sdam:
+
+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
+
+.. literalinclude:: /includes/monitoring/sdam.c
+   :language: c
+   :copyable:
+   :linenos:
+   :emphasize-lines: 10, 30-32
+
+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:
+
+.. code-block:: none
+   :copyable: false
+
+   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:
+
+.. list-table::
+   :widths: 35 65 
+   :header-rows: 1
+
+   * - Event Type
+     - Description
+
+   * - `mongoc_apm_server_changed_t <{+api-libmongoc+}/mongoc_apm_server_changed_t.html>`__
+     - Created when the server description changes, such as the server's
+       type changing from secondary to primary.
+
+   * - `mongoc_apm_server_opening_t <{+api-libmongoc+}/mongoc_apm_server_opening_t.html>`__
+     - Created when a new server is added to the topology. For an example application that
+       subscribes to this SDAM event, see :ref:`c-subscribe-sdam` on this page.
+
+   * - `mongoc_apm_server_closed_t <{+api-libmongoc+}/mongoc_apm_server_closed_t.html>`__
+     - Created when an existing server is removed from the topology.
+
+   * - `mongoc_apm_topology_changed_t <{+api-libmongoc+}/mongoc_apm_topology_changed_t.html>`__
+     - Created when the topology description changes, such as when there
+       is an election of a new primary.
+
+   * - `mongoc_apm_topology_opening_t <{+api-libmongoc+}/mongoc_apm_topology_opening_t.html>`__
+     - Created when the driver first connects to the cluster.
+
+   * - `mongoc_apm_topology_closed_t <{+api-libmongoc+}/mongoc_apm_topology_closed_t.html>`__
+     - Created when the driver disconnects from the cluster.
+
+   * - `mongoc_apm_server_heartbeat_started_t <{+api-libmongoc+}/mongoc_apm_server_heartbeat_started_t.html>`__
+     - Created when the server monitor sends a ``hello`` command to the server.
+       This action is called a heartbeat.
+
+   * - `mongoc_apm_server_heartbeat_succeeded_t <{+api-libmongoc+}/mongoc_apm_server_heartbeat_succeeded_t.html>`__
+     - Created when the heartbeat succeeds.
+
+   * - `mongoc_apm_server_heartbeat_failed_t <{+api-libmongoc+}/mongoc_apm_server_heartbeat_failed_t.html>`__
+     - Created when the heartbeat fails.
+
+You can find information about each monitoring subscriber type and event
+method in the `Application Performance Monitoring <{+api-libmongoc+}/application-performance-monitoring.html>`__
+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() <{+api-libmongoc+}/mongoc_apm_set_server_opening_cb.html>`__
+- `mongoc_client_set_apm_callbacks() <{+api-libmongoc+}/mongoc_client_set_apm_callbacks.html>`__