Skip to content

Commit 014a396

Browse files
rustagirrustagir
authored
DOCSP-37874: logging monitoring (#19)
1 parent 0c285a5 commit 014a396

File tree

4 files changed

+331
-3
lines changed

4 files changed

+331
-3
lines changed

‎source/index.txt

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ Java RS Driver
66
:titlesonly:
77
:maxdepth: 1
88

9-
/installation
10-
/get-started
11-
/tutorials
9+
/installation/
10+
/get-started/
11+
/tutorials/
12+
/reference/
1213
View the Source <https://github.com/mongodb/mongo-java-driver>
1314

1415
Have a lovely day!

‎source/reference.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _javars-reference:
2+
3+
=========
4+
Reference
5+
=========
6+
7+
.. toctree::
8+
9+
/reference/logging/
10+
/reference/monitoring/
11+

‎source/reference/logging.txt

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
.. _javars-logging:
2+
3+
=======
4+
Logging
5+
=======
6+
7+
By default, logging is enabled via the popular `SLF4J
8+
<https://www.slf4j.org/>`__ API. Logging is optional, so the driver
9+
uses SLF4J if the driver detects the presence of SLF4J API (class
10+
``org.slf4j.Logger``) in the classpath.
11+
12+
Otherwise, the driver logs a single warning via JUL
13+
(``java.util.logging``) and logging is otherwise disabled.
14+
15+
The driver uses the following logger names:
16+
17+
- ``org.mongodb.driver``: the root logger
18+
19+
- ``cluster``: for logs related to monitoring of the MongoDB servers to
20+
which the driver connects
21+
22+
- ``connection``: for logs related to connections and connection pools
23+
24+
- ``protocol``: for logs related to protocol messages sent to and
25+
received from a MongoDB server
26+
27+
- ``insert``: for logs related to insert messages and responses
28+
29+
- ``update``: for logs related to update messages and responses
30+
31+
- ``delete``: for logs related to delete messages and responses
32+
33+
- ``query``: for logs related to query messages and responses
34+
35+
- ``getmore``: for logs related to ``getmore`` messages and responses
36+
37+
- ``killcursor``: for logs related to ``killcursor`` messages and responses
38+
39+
- ``command``: for logs related to command messages and responses
40+
41+
- ``uri``: for logs related to connection string parsing
42+
43+
- ``management``: for logs related to JMX

‎source/reference/monitoring.txt

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
.. _javars-monitoring:
2+
3+
==============
4+
JMX Monitoring
5+
==============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
The driver uses `JMX
14+
<https://docs.oracle.com/javase/8/docs/technotes/guides/jmx/>`__ to
15+
create`MXBeans
16+
<https://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html>`__
17+
that allow you to monitor various aspects of the driver.
18+
19+
The driver creates ``MXBean`` instances of a single
20+
type, ``ConnectionPoolStatisticsMBean``. The driver registers one
21+
``ConnectionPoolStatisticsMBean`` instance for each server it connects
22+
to. For example, when connected to a replica set, the driver creates an
23+
instance for each non-hidden member of the replica set.
24+
25+
Each ``MXBean`` instance is required to be registered with a unique object
26+
name, which consists of a domain and a set of named properties. All
27+
``MXBean`` instances created by the driver are under the domain
28+
``org.mongodb.driver``. Instances of ``ConnectionPoolStatisticsMBean``
29+
have the following properties:
30+
31+
- ``clusterId``: a client-generated unique identifier, required to
32+
ensure object name uniqueness in situations where an application has
33+
multiple ``MongoClient`` instances connected to the same MongoDB server
34+
deployment
35+
- ``host``: the hostname of the server
36+
- ``port``: the port on which the server is listening
37+
- ``minSize``: the minimum allowed size of the pool, including idle and
38+
in-use members
39+
- ``maxSize``: the maximum allowed size of the pool, including idle and
40+
in-use members
41+
- ``size``: the current size of the pool, including idle and in-use
42+
members
43+
- ``checkedOutCount``: the current count of connections that are
44+
currently in use
45+
46+
JMX connection pool monitoring is disabled by default. To enable it
47+
add a ``com.mongodb.management.JMXConnectionPoolListener`` instance
48+
when creating a ``MongoClientSettings`` instance:
49+
50+
.. code-block:: java
51+
52+
MongoClientSettings settings =
53+
MongoClientSettings.builder()
54+
.applyToConnectionPoolSettings(builder -> builder.addConnectionPoolListener(new JMXConnectionPoolListener()))
55+
.build();
56+
57+
Command Monitoring
58+
------------------
59+
60+
The driver implements the command monitoring specification, allowing
61+
an application to be notified when a command starts and when it either
62+
succeeds or fails.
63+
64+
An application registers command listeners with a ``MongoClient`` by
65+
configuring a ``MongoClientSettings`` instance with instances of classes
66+
that implement the ``CommandListener`` interface. The following example
67+
is a simple implementation of the ``CommandListener`` interface:
68+
69+
.. code-block:: java
70+
71+
public class TestCommandListener implements CommandListener {
72+
@Override
73+
public void commandStarted(final CommandStartedEvent event) {
74+
System.out.println(String.format("Sent command '%s:%s' with id %s to database '%s' "
75+
+ "on connection '%s' to server '%s'",
76+
event.getCommandName(),
77+
event.getCommand().get(event.getCommandName()),
78+
event.getRequestId(),
79+
event.getDatabaseName(),
80+
event.getConnectionDescription()
81+
.getConnectionId(),
82+
event.getConnectionDescription().getServerAddress()));
83+
}
84+
85+
@Override
86+
public void commandSucceeded(final CommandSucceededEvent event) {
87+
System.out.println(String.format("Successfully executed command '%s' with id %s "
88+
+ "on connection '%s' to server '%s'",
89+
event.getCommandName(),
90+
event.getRequestId(),
91+
event.getConnectionDescription()
92+
.getConnectionId(),
93+
event.getConnectionDescription().getServerAddress()));
94+
}
95+
96+
@Override
97+
public void commandFailed(final CommandFailedEvent event) {
98+
System.out.println(String.format("Failed execution of command '%s' with id %s "
99+
+ "on connection '%s' to server '%s' with exception '%s'",
100+
event.getCommandName(),
101+
event.getRequestId(),
102+
event.getConnectionDescription()
103+
.getConnectionId(),
104+
event.getConnectionDescription().getServerAddress(),
105+
event.getThrowable()));
106+
}
107+
}
108+
109+
The following example creates an instance of ``MongoClientSettings``
110+
configured with an instance of ``TestCommandListener``:
111+
112+
.. code-block:: java
113+
114+
MongoClientSettings settings = MongoClientSettings.builder()
115+
.addCommandListener(new TestCommandListener())
116+
.build();
117+
MongoClient client = MongoClients.create(settings);
118+
119+
A ``MongoClient`` configured with these options prints a message to
120+
``System.out`` before sending each command to a MongoDB server, and
121+
prints another message upon either successful completion or failure of each
122+
command.
123+
124+
Cluster Monitoring
125+
------------------
126+
127+
The driver implements the SDAM Monitoring specification, allowing an
128+
application to be notified when the driver detects changes to the
129+
topology of the MongoDB cluster to which it is connected.
130+
131+
An application registers listeners with a ``MongoClient`` by configuring
132+
``MongoClientSettings`` with instances of classes that implement any of
133+
the ``ClusterListener``, ``ServerListener``, or
134+
``ServerMonitorListener`` interfaces.
135+
136+
The following code demonstrates how to create a cluster listener:
137+
138+
.. code-block:: java
139+
140+
public class TestClusterListener implements ClusterListener {
141+
private final ReadPreference readPreference;
142+
private boolean isWritable;
143+
private boolean isReadable;
144+
145+
public TestClusterListener(final ReadPreference readPreference) {
146+
this.readPreference = readPreference;
147+
}
148+
149+
@Override
150+
public void clusterOpening(final ClusterOpeningEvent clusterOpeningEvent) {
151+
System.out.println(String.format("Cluster with unique client identifier %s opening",
152+
clusterOpeningEvent.getClusterId()));
153+
}
154+
155+
@Override
156+
public void clusterClosed(final ClusterClosedEvent clusterClosedEvent) {
157+
System.out.println(String.format("Cluster with unique client identifier %s closed",
158+
clusterClosedEvent.getClusterId()));
159+
}
160+
161+
@Override
162+
public void clusterDescriptionChanged(final ClusterDescriptionChangedEvent event) {
163+
if (!isWritable) {
164+
if (event.getNewDescription().hasWritableServer()) {
165+
isWritable = true;
166+
System.out.println("Writable server available!");
167+
}
168+
} else {
169+
if (!event.getNewDescription().hasWritableServer()) {
170+
isWritable = false;
171+
System.out.println("No writable server available!");
172+
}
173+
}
174+
175+
if (!isReadable) {
176+
if (event.getNewDescription().hasReadableServer(readPreference)) {
177+
isReadable = true;
178+
System.out.println("Readable server available!");
179+
}
180+
} else {
181+
if (!event.getNewDescription().hasReadableServer(readPreference)) {
182+
isReadable = false;
183+
System.out.println("No readable server available!");
184+
}
185+
}
186+
}
187+
}
188+
189+
The following example creates an instance of ``MongoClientSettings``
190+
configured with an instance of ``TestClusterListener``:
191+
192+
.. code-block:: java
193+
194+
List<ServerAddress> seedList = ...
195+
MongoClientSettings settings = MongoClientSettings.builder()
196+
.applyToClusterSettings(builder ->
197+
builder.addClusterListener(new TestClusterListener(ReadPreference.secondary())))
198+
.build();
199+
MongoClient client = MongoClients.create(settings);
200+
201+
A ``MongoClient`` configured with these options prints a message to
202+
``System.out`` when the ``MongoClient`` is created with these options, and
203+
when that ``MongoClient`` is closed. In addition, it prints a message
204+
when the client enters any of the following states:
205+
206+
- Has an available server that will accept writes
207+
- Is without an available server that will accept writes
208+
- Has an available server that will accept reads by using the configured
209+
``ReadPreference``
210+
- Is without an available server that will accept reads by using the
211+
configured ``ReadPreference``
212+
213+
Connection Pool Monitoring
214+
--------------------------
215+
216+
The driver supports monitoring of connection pool-related events.
217+
218+
An application registers listeners with a ``MongoClient`` by configuring
219+
``MongoClientSettings`` with instances of classes that implement the
220+
``ConnectionPoolListener`` interface.
221+
222+
The following code demonstrates how to create a connection pool listener:
223+
224+
.. code-block:: java
225+
226+
public class TestConnectionPoolListener implements ConnectionPoolListener {
227+
@Override
228+
public void connectionPoolOpened(final ConnectionPoolOpenedEvent event) {
229+
System.out.println(event);
230+
}
231+
232+
@Override
233+
public void connectionPoolClosed(final ConnectionPoolClosedEvent event) {
234+
System.out.println(event);
235+
}
236+
237+
@Override
238+
public void connectionCheckedOut(final ConnectionCheckedOutEvent event) {
239+
System.out.println(event);
240+
}
241+
242+
@Override
243+
public void connectionCheckedIn(final ConnectionCheckedInEvent event) {
244+
System.out.println(event);
245+
}
246+
247+
@Override
248+
public void connectionAdded(final ConnectionAddedEvent event) {
249+
System.out.println(event);
250+
}
251+
252+
@Override
253+
public void connectionRemoved(final ConnectionRemovedEvent event) {
254+
System.out.println(event);
255+
}
256+
}
257+
258+
259+
The following example creates an instance of ``MongoClientSettings``
260+
configured with an instance of ``TestConnectionPoolListener``:
261+
262+
.. code-block:: java
263+
264+
List<ServerAddress> seedList = ...
265+
MongoClientSettings settings = MongoClientSettings.builder()
266+
.applyToConnectionPoolSettings(builder ->
267+
builder.addConnectionPoolListener(new TestConnectionPoolListener()))
268+
.build();
269+
MongoClient client = MongoClients.create(settings);
270+
271+
A ``MongoClient`` configured with these options prints a message to
272+
``System.out`` for each connection pool-related event for each MongoDB
273+
server to which the MongoClient is connected.

0 commit comments

Comments
 (0)