Skip to content

Commit 14e0d91

Browse files
norareidynorareidy
authored
DOCSP-43082: Cluster monitoring (#63)
* DOCSP-43082: Cluster monitoring * edits * fix link * MM feedback * wording * EC feedback * EC last feedback
1 parent 263de2a commit 14e0d91

File tree

4 files changed

+183
-0
lines changed

4 files changed

+183
-0
lines changed

‎source/includes/monitoring/sdam.c

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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+
}

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
/databases-collections
1212
/read
1313
/indexes
14+
/monitoring
1415
/aggregation
1516
/whats-new
1617
/compatibility

‎source/monitoring.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _c-monitoring:
2+
3+
========================
4+
Monitor Your Application
5+
========================
6+
7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 1
10+
11+
/monitoring/cluster-monitoring

‎source/monitoring/cluster-monitoring.txt

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
.. _c-cluster-monitoring:
2+
3+
==================
4+
Cluster Monitoring
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, server, topology
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecols
19+
20+
Overview
21+
--------
22+
23+
This guide shows you how to use the {+driver-short+} to monitor server
24+
discovery and monitoring (SDAM) events in a MongoDB instance, replica
25+
set, or sharded cluster. These events occur when there are any changes
26+
in the state of the MongoDB instance or cluster that you are connected
27+
to.
28+
29+
You might use information about SDAM events in your application to
30+
understand cluster changes, assess cluster health, or perform capacity
31+
planning.
32+
33+
.. _c-subscribe-sdam:
34+
35+
Subscribe to Events
36+
-------------------
37+
38+
You can access details about SDAM events by subscribing to them
39+
in your application. To subscribe to an event, define an Application
40+
Performance Monitoring (APM) callback function to handle each event
41+
type you want to subscribe to. Pass a ``mongoc_apm_callbacks_t`` object
42+
to the ``mongoc_client_set_apm_callbacks()`` function to register the
43+
list of APM callbacks with a client.
44+
45+
This code monitors server opening events by performing the following
46+
actions:
47+
48+
- Defines a ``server_opening()`` APM callback function
49+
- Creates a ``mongoc_apm_callbacks_t`` object to store callbacks
50+
- Calls the ``mongoc_apm_set_server_opening_cb()`` function, which
51+
stores a pointer to the provided APM callback function in the
52+
``mongoc_apm_callbacks_t`` object
53+
- Calls the ``mongoc_client_set_apm_callbacks()`` function, which registers
54+
the callback in the ``mongoc_apm_callbacks_t`` object with the client
55+
56+
.. literalinclude:: /includes/monitoring/sdam.c
57+
:language: c
58+
:copyable:
59+
:linenos:
60+
:emphasize-lines: 10, 30-32
61+
62+
When you perform a database operation, the driver establishes a new connection to
63+
the server and your subscriber records the server opening event. The code outputs
64+
messages that resemble the following:
65+
66+
.. code-block:: none
67+
:copyable: false
68+
69+
Server opening: <host>:<port number>
70+
71+
Event Descriptions
72+
------------------
73+
74+
You can subscribe to SDAM events by defining the corresponding
75+
APM callback function. The following table provides the name of
76+
each SDAM event, links to the type's API documentation, and describes
77+
when the event is published:
78+
79+
.. list-table::
80+
:widths: 35 65
81+
:header-rows: 1
82+
83+
* - Event Type
84+
- Description
85+
86+
* - `mongoc_apm_server_changed_t <{+api-libmongoc+}/mongoc_apm_server_changed_t.html>`__
87+
- Created when the server description changes, such as the server's
88+
type changing from secondary to primary.
89+
90+
* - `mongoc_apm_server_opening_t <{+api-libmongoc+}/mongoc_apm_server_opening_t.html>`__
91+
- Created when a new server is added to the topology. For an example application that
92+
subscribes to this SDAM event, see :ref:`c-subscribe-sdam` on this page.
93+
94+
* - `mongoc_apm_server_closed_t <{+api-libmongoc+}/mongoc_apm_server_closed_t.html>`__
95+
- Created when an existing server is removed from the topology.
96+
97+
* - `mongoc_apm_topology_changed_t <{+api-libmongoc+}/mongoc_apm_topology_changed_t.html>`__
98+
- Created when the topology description changes, such as when there
99+
is an election of a new primary.
100+
101+
* - `mongoc_apm_topology_opening_t <{+api-libmongoc+}/mongoc_apm_topology_opening_t.html>`__
102+
- Created when the driver first connects to the cluster.
103+
104+
* - `mongoc_apm_topology_closed_t <{+api-libmongoc+}/mongoc_apm_topology_closed_t.html>`__
105+
- Created when the driver disconnects from the cluster.
106+
107+
* - `mongoc_apm_server_heartbeat_started_t <{+api-libmongoc+}/mongoc_apm_server_heartbeat_started_t.html>`__
108+
- Created when the server monitor sends a ``hello`` command to the server.
109+
This action is called a heartbeat.
110+
111+
* - `mongoc_apm_server_heartbeat_succeeded_t <{+api-libmongoc+}/mongoc_apm_server_heartbeat_succeeded_t.html>`__
112+
- Created when the heartbeat succeeds.
113+
114+
* - `mongoc_apm_server_heartbeat_failed_t <{+api-libmongoc+}/mongoc_apm_server_heartbeat_failed_t.html>`__
115+
- Created when the heartbeat fails.
116+
117+
You can find information about each monitoring subscriber type and event
118+
method in the `Application Performance Monitoring <{+api-libmongoc+}/application-performance-monitoring.html>`__
119+
section of the API documentation.
120+
121+
API Documentation
122+
-----------------
123+
124+
To learn more about the functions discussed in this guide, see the
125+
following API documentation:
126+
127+
- `mongoc_apm_set_server_opening_cb() <{+api-libmongoc+}/mongoc_apm_set_server_opening_cb.html>`__
128+
- `mongoc_client_set_apm_callbacks() <{+api-libmongoc+}/mongoc_client_set_apm_callbacks.html>`__

0 commit comments

Comments
 (0)