1MongoDB::Monitoring(3)User Contributed Perl DocumentationMongoDB::Monitoring(3)
2
3
4

NAME

6       MongoDB::Monitoring - Internal event monitoring API for instrumentation
7

VERSION

9       version v2.2.2
10

DESCRIPTION

12       The MongoDB::MongoClient takes an optional "monitoring_callback"
13       attribute, which can be used to monitor events that occur during the
14       operation of the driver.
15
16       The API is very simple: given a code reference, a hashref for each
17       event is passed to the code reference.  Here is a simple example that
18       just accumulates events in an array:
19
20           our @events;
21           my $cb = sub { push @events, $_[0] };
22
23           MongoDB->connect( $uri, { monitoring_callback => $cb } );
24

EVENT TYPES

26       Every event is a hash reference, with a "type" field indicating the
27       type, e.g. "command_started".  Each type is described below.
28
29   Command Monitoring
30       These events are fired for commands directly to the wire and the
31       response.
32
33       command_started
34
35       This event is sent just before a command is put one the wire.  It will
36       be followed by either a "command_succeeded" or "command_failed" event.
37
38       Fields:
39
40       •   type: "command_started"
41
42       •   databaseName: the name of the database to which the command applies
43
44       •   commandName: the name of the command being executed; for legacy
45           operations that don't use commands, the driver will convert them to
46           appear as if they are in command form.
47
48       •   command: a hash reference representing the full command to be sent
49
50       •   requestId: the request identifier sent to the server
51
52       •   connectionId: address and port of the destination server
53
54       command_succeeded
55
56       This event is sent just after a command reply is received, but only if
57       the database reply document contains a non-false "ok" field.  NOTE:
58       write errors will have "ok:1" even though they have write errors; for
59       writes, success indicates that the write attempt was valid, not that
60       the write succeeded.
61
62       Fields:
63
64       •   type: "command_succeeded"
65
66       •   commandName: the name of the command being executed
67
68       •   durationSecs: the elapsed time in seconds since the
69           "command_started" event.
70
71       •   reply: a hash reference representing the full database reply
72
73       •   requestId: the request identifier sent to the server
74
75       •   connectionId: address and port of the destination server
76
77       command_failed
78
79       This event is sent just after a command reply is received, but only if
80       the database reply document contains a false "ok" field or if an
81       exception occurred during send or receive operations.
82
83       Fields:
84
85       •   type: "command_failed"
86
87       •   commandName: the name of the command being executed
88
89       •   durationSecs: the elapsed time in seconds since the
90           "command_started" event.
91
92       •   failure: a string with a error message about the failure
93
94       •   eval_error: if an exception occurs, this contains the value of $@
95           when the exception was caught
96
97       •   reply: a hash reference representing the full database reply or an
98           empty hashref if the failure is due to an exception
99
100       •   requestId: the request identifier sent to the server
101
102       •   connectionId: address and port of the destination server
103
104   Server Discovery and Monitoring
105       These events are fired when servers and topology are amended.
106
107       server_opening_event
108
109       This event is sent when a new server is added to the topology.
110
111       Fields:
112
113       •   type: "server_opening_event"
114
115       •   topologyId: The topology refaddr
116
117       •   address: address of the server
118
119       server_closed_event
120
121       This event is sent when a server is removed from the topology.
122
123       Fields:
124
125       •   type: "server_closed_event"
126
127       •   topologyId: The topology refaddr
128
129       •   address: address of the server
130
131       server_description_changed_event
132
133       This event is sent when the server description changes, but does not
134       include changes to the RTT.
135
136       Fields:
137
138       •   type: "server_description_changed_event"
139
140       •   address: address of the server
141
142       •   topologyId: The topology refaddr
143
144       •   previousDescription: Server Description before the change
145
146       •   newDescription: Server Description after the change
147
148       topology_opening_event
149
150       This event is sent when the topology is created.
151
152       Fields:
153
154       •   type: "topology_opening_event"
155
156       •   topologyId: The topology refaddr
157
158       topology_closed_event
159
160       This event is sent when the topology is closed.
161
162       Fields:
163
164       •   type: "topology_closed_event"
165
166       •   topologyId: The topology refaddr
167
168       topology_description_changed_event
169
170       This event is sent when the topology description changes.
171
172       Fields:
173
174       •   type: "topology_description_changed_event"
175
176       •   topologyId: The topology refaddr
177
178       •   previousDescription: Topology Description before the change
179
180       •   newDescription: Topology Description after the change
181
182       server_heartbeat_started_event
183
184       This event is sent before the ismaster command is sent to the server.
185
186       Fields:
187
188       •   type: "server_heartbeat_started_event"
189
190       •   connectionId: address of the link to connect to
191
192       server_heartbeat_succeeded_event
193
194       This event is sent after the reply from the ismaster command arrives
195       from a successful reply.
196
197       Fields:
198
199       •   type: "server_heartbeat_succeeded_event"
200
201       •   duration: time it took to send and receive a reply
202
203       •   reply: the ismaster command reply
204
205       •   connectionId: address of the server
206
207       server_heartbeat_failed_event
208
209       This event is sent if there is a failure from the ismaster command,
210       which returns an error string of some sort.
211
212       Fields:
213
214       •   type: "server_heartbeat_failed_event"
215
216       •   duration: time it took to send and receive a reply
217
218       •   failure: Returns an error string of the failure
219
220       •   connectionId: address of the server
221

REDACTION

223       Certain commands are considered sensitive.  When any of the following
224       commands are seen in monitoring, the command body and database reply
225       body are replaced with an empty document:
226
227       •   authenticate
228
229       •   saslStart
230
231       •   saslContinue
232
233       •   getnonce
234
235       •   createUser
236
237       •   updateUser
238
239       •   copydbgetnonce
240
241       •   copydbsaslstart
242

AUTHORS

244       •   David Golden <david@mongodb.com>
245
246       •   Rassi <rassi@mongodb.com>
247
248       •   Mike Friedman <friedo@friedo.com>
249
250       •   Kristina Chodorow <k.chodorow@gmail.com>
251
252       •   Florian Ragwitz <rafl@debian.org>
253

255       This software is Copyright (c) 2020 by MongoDB, Inc.
256
257       This is free software, licensed under:
258
259         The Apache License, Version 2.0, January 2004
260
261
262
263perl v5.36.0                      2023-01-20            MongoDB::Monitoring(3)
Impressum