--- name: "MongoDB::Monitoring" section: "3pm" platform: "linux" package: "libmongodb-perl" version: "2.2.2-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/MongoDB::Monitoring" --- # MongoDB::Monitoring(3pm) Internal event monitoring API for instrumentation ## NAME MongoDB::Monitoring - Internal event monitoring API for instrumentation ## VERSION version v2.2.2 ## DESCRIPTION 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 `"command_started"` event. - • 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 ## AUTHORS - • David Golden \ - • Rassi \ - • Mike Friedman \ - • Kristina Chodorow \ - • Florian Ragwitz \ ## 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 2004 ```