Skip to content

Commit 71ddfad

Browse files
jyeminjyemin
committed
JAVA-2009, JAVA-2139: Add reference documentation for SDAM Monitoring, and for command monitoring in the asynchronous driver
1 parent 39db098 commit 71ddfad

File tree

2 files changed

+242
-11
lines changed

2 files changed

+242
-11
lines changed

‎docs/reference/content/driver-async/reference/management/monitoring.md‎

Lines changed: 151 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title = "Monitoring"
88
pre = "<i class='fa'></i>"
99
+++
1010

11-
# Monitoring
11+
# JMX Monitoring
1212

1313
The driver uses [JMX](http://docs.oracle.com/javase/8/docs/technotes/guides/jmx/) to create
1414
[MXBeans](http://docs.oracle.com/javase/tutorial/jmx/mbeans/mxbeans.html) that allow an
@@ -32,3 +32,153 @@ application has multiple `MongoClient` instances connected to the same MongoDB s
3232
- `size`: the current size of the pool, including idle and and in-use members
3333
- `waitQueueSize`: the current size of the wait queue for a connection from this pool
3434
- `checkedOutCount`: the current count of connections that are currently in use
35+
36+
# Command Monitoring
37+
38+
The driver implements the
39+
[command monitoring specification](https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst),
40+
allowing an application to be notified when a command starts and when it either succeeds or fails.
41+
42+
An application registers command listeners with a `MongoClient` by configuring `MongoClientSettings` with instances of classes
43+
that implement the [`CommandListener`]({{< apiref "com/mongodb/event/CommandListener" >}}) interface. Consider the following, somewhat
44+
simplistic, implementation of the `CommandListener` interface:
45+
46+
```java
47+
public class TestCommandListener implements CommandListener {
48+
@Override
49+
public void commandStarted(final CommandStartedEvent event) {
50+
System.out.println(String.format("Sent command '%s:%s' with id %s to database '%s' "
51+
+ "on connection '%s' to server '%s'",
52+
event.getCommandName(),
53+
event.getCommand().get(event.getCommandName()),
54+
event.getRequestId(),
55+
event.getDatabaseName(),
56+
event.getConnectionDescription()
57+
.getConnectionId(),
58+
event.getConnectionDescription().getServerAddress()));
59+
}
60+
61+
@Override
62+
public void commandSucceeded(final CommandSucceededEvent event) {
63+
System.out.println(String.format("Successfully executed command '%s' with id %s "
64+
+ "on connection '%s' to server '%s'",
65+
event.getCommandName(),
66+
event.getRequestId(),
67+
event.getConnectionDescription()
68+
.getConnectionId(),
69+
event.getConnectionDescription().getServerAddress()));
70+
}
71+
72+
@Override
73+
public void commandFailed(final CommandFailedEvent event) {
74+
System.out.println(String.format("Failed execution of command '%s' with id %s "
75+
+ "on connection '%s' to server '%s' with exception '%s'",
76+
event.getCommandName(),
77+
event.getRequestId(),
78+
event.getConnectionDescription()
79+
.getConnectionId(),
80+
event.getConnectionDescription().getServerAddress(),
81+
event.getThrowable()));
82+
}
83+
}
84+
```
85+
86+
and an instance of `MongoClientSettings` configured with an instance of `TestCommandListener`:
87+
88+
```java
89+
ClusterSettings clusterSettings = ...
90+
MongoClientSettings settings = MongoClientSettings.builder()
91+
.clusterSettings(clusterSettings)
92+
.addCommandListener(new TestCommandListener())
93+
.build();
94+
MongoClient client = MongoClients.create(settings);
95+
```
96+
97+
A `MongoClient` configured with these options will print a message to `System.out` before sending each command to a MongoDB server, and
98+
another message upon either successful completion or failure of each command.
99+
100+
# Cluster Monitoring
101+
102+
The driver implements the
103+
[SDAM Monitoring specification](https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst),
104+
allowing an application to be notified when the driver detects changes to the topology of the MongoDB cluster to which it is connected.
105+
106+
An application registers listeners with a `MongoClient` by configuring `MongoClientSettings` with instances of classes that
107+
implement any of the [`ClusterListener`]({{< apiref "com/mongodb/event/ClusterListener" >}}),
108+
[`ServerListener`]({{< apiref "com/mongodb/event/ServerListener" >}}),
109+
or [`ServerMonitorListener`]({{< apiref "com/mongodb/event/ServerMonitorListener" >}}) interfaces.
110+
111+
Consider the following, somewhat simplistic, example of a cluster listener:
112+
113+
```java
114+
public class TestClusterListener implements ClusterListener {
115+
private final ReadPreference readPreference;
116+
private boolean isWritable;
117+
private boolean isReadable;
118+
119+
public TestClusterListener(final ReadPreference readPreference) {
120+
this.readPreference = readPreference;
121+
}
122+
123+
@Override
124+
public void clusterOpening(final ClusterOpeningEvent clusterOpeningEvent) {
125+
System.out.println(String.format("Cluster with unique client identifier %s opening",
126+
clusterOpeningEvent.getClusterId()));
127+
}
128+
129+
@Override
130+
public void clusterClosed(final ClusterClosedEvent clusterClosedEvent) {
131+
System.out.println(String.format("Cluster with unique client identifier %s closed",
132+
clusterClosedEvent.getClusterId()));
133+
}
134+
135+
@Override
136+
public void clusterDescriptionChanged(final ClusterDescriptionChangedEvent event) {
137+
if (!isWritable) {
138+
if (event.getNewDescription().hasWritableServer()) {
139+
isWritable = true;
140+
System.out.println("Writable server available!");
141+
}
142+
} else {
143+
if (!event.getNewDescription().hasWritableServer()) {
144+
isWritable = false;
145+
System.out.println("No writable server available!");
146+
}
147+
}
148+
149+
if (!isReadable) {
150+
if (event.getNewDescription().hasReadableServer(readPreference)) {
151+
isReadable = true;
152+
System.out.println("Readable server available!");
153+
}
154+
} else {
155+
if (!event.getNewDescription().hasReadableServer(readPreference)) {
156+
isReadable = false;
157+
System.out.println("No readable server available!");
158+
}
159+
}
160+
}
161+
}
162+
```
163+
164+
and an instance of `MongoClientSettings` configured with an instance of `TestClusterListener`:
165+
166+
```java
167+
List<ServerAddress> seedList = ...
168+
ClusterSettings clusterSettings = ClusterSettings.builder()
169+
.hosts(seedList)
170+
.addClusterListener(new TestClusterListener(ReadPreference.secondary()))
171+
.build();
172+
MongoClientSettings settings = MongoClientSettings.builder()
173+
.clusterSettings(clusterSettings)
174+
.build();
175+
MongoClient client = MongoClients.create(settings);
176+
```
177+
178+
A `MongoClient` configured with these settings will print a message to `System.out` when the MongoClient is created with these options,
179+
and when that MongoClient is closed. In addition, it will print a message when the client enters a state:
180+
181+
* with an available server that will accept writes
182+
* without an available server that will accept writes
183+
* with an available server that will accept reads using the configured `ReadPreference`
184+
* without an available server that will accept reads using the configured `ReadPreference`

‎docs/reference/content/driver/reference/management/monitoring.md‎

Lines changed: 91 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,13 @@ application has multiple `MongoClient` instances connected to the same MongoDB s
3535

3636
# Command Monitoring
3737

38-
The driver implements the
39-
[command monitoring specification](https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst),
40-
which allows an application to attach its own event listeners that are notified when commands are started and when they sucessfully
41-
completed or fail.
42-
43-
Command listeners are registered individually for each instance of `MongoClient` by configuring `MongoClientOptions` with one or more
44-
instances of a class that implements the [`CommandListener`]({{< apiref "com/mongodb/event/CommandListener" >}}) interface. Consider
45-
the following, obviously simplistic, implementation of the `CommandListener` interface:
38+
The driver implements the
39+
[command monitoring specification](https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst),
40+
allowing an application to be notified when a command starts and when it either succeeds or fails.
41+
42+
An application registers command listeners with a `MongoClient` by configuring `MongoClientOptions` with instances of classes
43+
that implement the [`CommandListener`]({{< apiref "com/mongodb/event/CommandListener" >}}) interface. Consider the following, somewhat
44+
simplistic, implementation of the `CommandListener` interface:
4645

4746
```java
4847
public class TestCommandListener implements CommandListener {
@@ -88,10 +87,92 @@ and an instance of `MongoClientOptions` configured with an instance of `TestComm
8887

8988
```java
9089
MongoClientOptions options = MongoClientOptions.builder()
91-
.addCommandListener(new TestCommandListener())
92-
.build();
90+
.addCommandListener(new TestCommandListener())
91+
.build();
9392
```
9493

9594
A `MongoClient` configured with these options will print a message to `System.out` before sending each command to a MongoDB server, and
9695
another message upon either successful completion or failure of each command.
9796

97+
# Cluster Monitoring
98+
99+
The driver implements the
100+
[SDAM Monitoring specification](https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst),
101+
allowing an application to be notified when the driver detects changes to the topology of the MongoDB cluster to which it is connected.
102+
103+
An application registers listeners with a `MongoClient` by configuring `MongoClientOptions` with instances of classes that
104+
implement any of the [`ClusterListener`]({{< apiref "com/mongodb/event/ClusterListener" >}}),
105+
[`ServerListener`]({{< apiref "com/mongodb/event/ServerListener" >}}),
106+
or [`ServerMonitorListener`]({{< apiref "com/mongodb/event/ServerMonitorListener" >}}) interfaces.
107+
108+
Consider the following, somewhat simplistic, example of a cluster listener:
109+
110+
```java
111+
public class TestClusterListener implements ClusterListener {
112+
private final ReadPreference readPreference;
113+
private boolean isWritable;
114+
private boolean isReadable;
115+
116+
public TestClusterListener(final ReadPreference readPreference) {
117+
this.readPreference = readPreference;
118+
}
119+
120+
@Override
121+
public void clusterOpening(final ClusterOpeningEvent clusterOpeningEvent) {
122+
System.out.println(String.format("Cluster with unique client identifier %s opening",
123+
clusterOpeningEvent.getClusterId()));
124+
}
125+
126+
@Override
127+
public void clusterClosed(final ClusterClosedEvent clusterClosedEvent) {
128+
System.out.println(String.format("Cluster with unique client identifier %s closed",
129+
clusterClosedEvent.getClusterId()));
130+
}
131+
132+
@Override
133+
public void clusterDescriptionChanged(final ClusterDescriptionChangedEvent event) {
134+
if (!isWritable) {
135+
if (event.getNewDescription().hasWritableServer()) {
136+
isWritable = true;
137+
System.out.println("Writable server available!");
138+
}
139+
} else {
140+
if (!event.getNewDescription().hasWritableServer()) {
141+
isWritable = false;
142+
System.out.println("No writable server available!");
143+
}
144+
}
145+
146+
if (!isReadable) {
147+
if (event.getNewDescription().hasReadableServer(readPreference)) {
148+
isReadable = true;
149+
System.out.println("Readable server available!");
150+
}
151+
} else {
152+
if (!event.getNewDescription().hasReadableServer(readPreference)) {
153+
isReadable = false;
154+
System.out.println("No readable server available!");
155+
}
156+
}
157+
}
158+
}
159+
```
160+
161+
and an instance of `MongoClientOptions` configured with an instance of `TestClusterListener`:
162+
163+
```java
164+
List<ServerAddress> seedList = ...
165+
MongoClientOptions options = MongoClientOptions.builder()
166+
.addClusterListener(new TestClusterListener(ReadPreference.secondary()))
167+
.build();
168+
MongoClient client = new MongoClient(seedList, options);
169+
```
170+
171+
A `MongoClient` configured with these options will print a message to `System.out` when the MongoClient is constructed with these options,
172+
and when that MongoClient is closed. In addition, it will print a message when the client enters a state:
173+
174+
* with an available server that will accept writes
175+
* without an available server that will accept writes
176+
* with an available server that will accept reads using the configured `ReadPreference`
177+
* without an available server that will accept reads using the configured `ReadPreference`
178+

0 commit comments

Comments
 (0)