MongoDB::Monitoring3pm
Internal event monitoring api for instrumentation
Version
version v2.2.2
Overview
The MongoDB::MongoClient takes an optional "monitoring_callback" attribute, which can be used to monitor events that occur during the operation of the driver.
The API is very simple: given a code reference, a hashref for each event is passed to the code reference. Here is a simple example that just accumulates events in an array:
our @events;my $cb = sub { push @events, $_[0] };MongoDB->connect( $uri, { monitoring_callback => $cb } );
Event types
Every event is a hash reference, with a "type" field indicating the type, e.g. "command_started". Each type is described below.
Command Monitoring
These events are fired for commands directly to the wire and the response.
command_started
This event is sent just before a command is put one the wire. It will be followed by either a "command_succeeded" or "command_failed" event.
Fields:
- •
-
type: "command_started"
- •
-
databaseName: the name of the database to which the command applies
- •
-
commandName: the name of the command being executed; for legacy operations that don't use commands, the driver will convert them to appear as if they are in command form.
- •
-
command: a hash reference representing the full command to be sent
- •
-
requestId: the request identifier sent to the server
- •
-
connectionId: address and port of the destination server
command_succeeded
This event is sent just after a command reply is received, but only if the database reply document contains a non-false "ok" field. NOTE: write errors will have "ok:1" even though they have write errors; for writes, success indicates that the write attempt was valid, not that the write succeeded.
Fields:
•
|
type: "command_succeeded" |
|---|---|
•
|
commandName: the name of the command being executed |
•
|
durationSecs: the elapsed time in seconds since the |
•
|
reply: a hash reference representing the full database reply |
•
|
requestId: the request identifier sent to the server |
•
|
connectionId: address and port of the destination server |
command_failed
This event is sent just after a command reply is received, but only if the database reply document contains a false "ok" field or if an exception occurred during send or receive operations.
Fields:
- •
-
type: "command_failed"
- •
-
commandName: the name of the command being executed
- •
-
durationSecs: the elapsed time in seconds since the
"command_started"event.
- •
-
failure: a string with a error message about the failure
- •
-
eval_error: if an exception occurs, this contains the value of
$@when the exception was caught
- •
-
reply: a hash reference representing the full database reply or an empty hashref if the failure is due to an exception
- •
-
requestId: the request identifier sent to the server
- •
-
connectionId: address and port of the destination server
Server Discovery and Monitoring
These events are fired when servers and topology are amended.
server_opening_event
This event is sent when a new server is added to the topology.
Fields:
•
|
type: "server_opening_event" |
|---|---|
•
|
topologyId: The topology refaddr |
•
|
address: address of the server |
server_closed_event
This event is sent when a server is removed from the topology.
Fields:
•
|
type: "server_closed_event" |
|---|---|
•
|
topologyId: The topology refaddr |
•
|
address: address of the server |
server_description_changed_event
This event is sent when the server description changes, but does not include changes to the RTT.
Fields:
•
|
type: "server_description_changed_event" |
|---|---|
•
|
address: address of the server |
•
|
topologyId: The topology refaddr |
•
|
previousDescription: Server Description before the change |
•
|
newDescription: Server Description after the change |
topology_opening_event
This event is sent when the topology is created.
Fields:
•
|
type: "topology_opening_event" |
|---|---|
•
|
topologyId: The topology refaddr |
topology_closed_event
This event is sent when the topology is closed.
Fields:
•
|
type: "topology_closed_event" |
|---|---|
•
|
topologyId: The topology refaddr |
topology_description_changed_event
This event is sent when the topology description changes.
Fields:
•
|
type: "topology_description_changed_event" |
|---|---|
•
|
topologyId: The topology refaddr |
•
|
previousDescription: Topology Description before the change |
•
|
newDescription: Topology Description after the change |
server_heartbeat_started_event
This event is sent before the ismaster command is sent to the server.
Fields:
•
|
type: "server_heartbeat_started_event" |
|---|---|
•
|
connectionId: address of the link to connect to |
server_heartbeat_succeeded_event
This event is sent after the reply from the ismaster command arrives from a successful reply.
Fields:
•
|
type: "server_heartbeat_succeeded_event" |
|---|---|
•
|
duration: time it took to send and receive a reply |
•
|
reply: the ismaster command reply |
•
|
connectionId: address of the server |
server_heartbeat_failed_event
This event is sent if there is a failure from the ismaster command, which returns an error string of some sort.
Fields:
•
|
type: "server_heartbeat_failed_event" |
|---|---|
•
|
duration: time it took to send and receive a reply |
•
|
failure: Returns an error string of the failure |
•
|
connectionId: address of the server |
Redaction
Certain commands are considered sensitive. When any of the following commands are seen in monitoring, the command body and database reply body are replaced with an empty document:
•
|
authenticate |
|---|---|
•
|
saslStart |
•
|
saslContinue |
•
|
getnonce |
•
|
createUser |
•
|
updateUser |
•
|
copydbgetnonce |
•
|
copydbsaslstart |
Copyright and license
This software is Copyright (c) 2020 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004Releases
4 releases since Debian 10 (Buster); the text changed 3 times.