MongoD...itoring(3pm)

✨ NAME ✨

MongoDB::Monitoring — the internal event monitoring API for instrumentation, bestie 💅

(it lives in the User Contributed Perl Documentation section of the manual, and yeah the title got truncated to MongoD...itoring(3pm) because man pages have a character limit and honestly? rude.)

---

🎀 VERSION 🎀

version v2.2.2 — that's the one, no cap 💖

---

🌸 DESCRIPTION 🌸

okay so listen. MongoDB::MongoClient takes an optional attribute called monitoring_callback, and it's literally there so you can spy on all the events happening while the driver is doing its little thing 👀✨

The API is giving extremely simple, and I mean that as a compliment. You hand it a code reference, and for every single event it passes a hashref to that code ref. That's it. That's the whole vibe.

Here's a baby example that just stacks up events in an array:

our @events;
my $cb = sub { push @events, $_[0] };

MongoDB->connect( $uri, { monitoring_callback => $cb } );

iconic behavior honestly 🫶

---

👑 EVENT TYPES 👑

Every event is a hash reference, and it's got a type field telling you what kind it is, like "command_started". Each type gets its own little spotlight below 💫

🔥 Command Monitoring

These events fire for commands going straight to the wire and for the response coming back. main character energy fr.

command_started

This one gets sent just before a command goes on the wire. It'll be followed by either a "command_succeeded" or a "command_failed" event — no cliffhangers left unresolved 💀

Fields:

• type: "command_started"
• databaseName: the name of the database the command applies to
• commandName: the name of the command being executed; for legacy operations that don't use commands, the driver converts them so they look like they're 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

Sent just after a command reply comes in — but only if the database reply document has a non-false "ok" field.

⚠️ NOTE: write errors will have ok:1 even though they have write errors. For writes, success means the write attempt was valid, not that the write actually succeeded. it's giving "technically fine" 😭

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

Sent just after a command reply arrives — but only if the database reply document has a false "ok" field, or if an exception happened 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 fire when servers and topology get amended 💜

server_opening_event

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

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

Sent when the server description changes — but not for changes to the RTT, so don't come for me 🙈

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

Sent when the topology is created ✨

Fields:

• type: "topology_opening_event"
• topologyId: The topology refaddr

topology_closed_event

Sent when the topology is closed 🚪

Fields:

• type: "topology_closed_event"
• topologyId: The topology refaddr

topology_description_changed_event

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

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

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

Sent if there's 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 🧚

oop — certain commands are considered sensitive 🙈 When any of these show up in monitoring, the command body and the database reply body get replaced with an empty document. privacy slay.

• authenticate
• saslStart
• saslContinue
• getnonce
• createUser
• updateUser
• copydbgetnonce
• copydbsaslstart

---

💖 AUTHORS 💖

shoutout to the icons who made this:

• David Golden <david@mongodb.com>
• Rassi <rassi@mongodb.com>
• Mike Friedman <friedo@friedo.com>
• Kristina Chodorow <k.chodorow@gmail.com>
• Florian Ragwitz <rafl@debian.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is Copyright (c) 2020 by MongoDB, Inc.

It's free software, licensed under:

The Apache License, Version 2.0, January 2004

---

okay bestie that's the whole thing, you ate that read-through 👑💅 this was page MongoD...itoring(3pm) from perl v5.40.1, dated 2025-04-03 — go forth and monitor those events fr fr 🌈✨💜