Skip to content

Commit 5acb888

Browse files
rustagirrustagir
authored
DOCSP-38204: logging & monitoring (#25)
1 parent 89c1642 commit 5acb888

File tree

4 files changed

+309
-1
lines changed

4 files changed

+309
-1
lines changed

‎source/index.txt

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
/installation/
1616
/get-started/
1717
/tutorials/
18+
/reference/
1819
/bson/
1920
View the Source <https://github.com/mongodb/mongo-java-driver>
2021
API Documentation <{+api+}/index.html>
@@ -34,10 +35,12 @@ runnable project by following one of the tutorials.
3435

3536
- :ref:`scala-tutorials`
3637

37-
.. - :ref:`scala-reference`
38+
- :ref:`scala-reference`
3839

3940
- :ref:`scala-bson`
4041

42+
.. - :ref:`scala-builders`
43+
4144
- `Driver Source GitHub Repository <https://github.com/mongodb/mongo-java-driver>`__
4245

4346
- `API Documentation <{+api+}/index.html>`__

‎source/reference.txt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. _scala-reference:
2+
3+
=========
4+
Reference
5+
=========
6+
7+
.. toctree::
8+
9+
/reference/logging/
10+
/reference/monitoring/
11+
12+
.. /reference/observables/
13+
14+
- :ref:`scala-logging`
15+
- :ref:`scala-monitoring`
16+
17+
.. :ref:`scala-observables`

‎source/reference/logging.txt

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

‎source/reference/monitoring.txt

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

0 commit comments

Comments
 (0)