Connection Pool Monitoring
On this page
Overview
This guide shows you how to monitor the driver's connection pool. A connection pool is a set of open TCP connections your driver maintains with a MongoDB instance. Connection pools help reduce the number of network handshakes your application needs to perform and can help your application run faster.
The following sections demonstrate how to record connection pool events in your application and explore the information provided in these events.
Event Subscription Examples
You can access one or more connection pool events using the driver by subscribing to them in your application. The following example demonstrates connecting to a replica set and subscribing to one of the connection pool monitoring events created by the MongoDB deployment:
const { MongoClient } = require("mongodb"); // Replace the following with your MongoDB deployment's connection // string. const uri = "mongodb+srv://<clusterUrl>/?replicaSet=rs&writeConcern=majority"; const client = new MongoClient(uri); // Replace <event name> with the name of the event you are subscribing to. const eventName = "<event name>"; // Subscribe to the event client.on(eventName, (event) => console.log("\nreceived event:\n", event) ); async function run() { try { // Establish and verify connection await client.db("admin").command({ ping: 1 }); console.log("\nConnected successfully!\n"); } finally { // Ensures that the client will close when you finish/error await client.close(); } } run().catch(console.dir);
Connection pool monitoring events can aid you in debugging and understanding the behavior of your application's connection pool. The following example uses connection pool monitoring events to return a count of checked-out connections in the pool:
function connectionPoolStatus(client) { let checkedOut = 0; function onCheckout() { checkedOut++; } function onCheckin() { checkedOut--; } function onClose() { client.removeListener('connectionCheckedOut', onCheckout); client.removeListener('connectionCheckedIn', onCheckin); checkedOut = NaN; } // Decreases count of connections checked out of the pool when connectionCheckedIn event is triggered client.on('connectionCheckedIn', onCheckin); // Increases count of connections checked out of the pool when connectionCheckedOut event is triggered client.on('connectionCheckedOut', onCheckout); // Cleans up event listeners when client is closed client.on('close', onClose); return { count: () => checkedOut, cleanUp: onClose }; }
Event Descriptions
You can subscribe to any of the following connection pool monitoring events:
Event Name | Description |
---|---|
connectionPoolCreated | Created when a connection pool is created. |
connectionPoolReady | Created when a connection pool is ready. |
connectionPoolClosed | Created when a connection pool is closed, prior to server
instance destruction. |
connectionCreated | Created when a connection is created, but not necessarily
when it is used for an operation. |
connectionReady | Created after a connection has successfully completed a
handshake and is ready to be used for operations. |
connectionClosed | Created when a connection is closed. |
connectionCheckOutStarted | Created when an operation attempts to acquire a connection for
execution. |
connectionCheckOutFailed | Created when an operation fails to acquire a connection for
execution. |
connectionCheckedOut | Created when an operation successfully acquires a connection for
execution. |
connectionCheckedIn | Created when a connection is checked back into the pool after an operation
is executed. |
connectionPoolCleared | Created when a connection pool is cleared. |
Example Event Documents
The following sections show sample output for each type of connection pool monitoring event.
connectionPoolCreated
ConnectionPoolCreatedEvent { time: 2023-02-13T15:54:06.944Z, address: '...', options: {...} }
connectionPoolReady
ConnectionPoolReadyEvent { time: 2023-02-13T15:56:38.440Z, address: '...' }
connectionPoolClosed
ConnectionPoolClosedEvent { time: 2023-02-13T15:56:38.440Z, address: '...' }
connectionCreated
ConnectionCreatedEvent { time: 2023-02-13T15:56:38.291Z, address: '...', connectionId: 1 }
connectionReady
ConnectionReadyEvent { time: 2023-02-13T15:56:38.291Z, address: '...', connectionId: 1 }
connectionClosed
ConnectionClosedEvent { time: 2023-02-13T15:56:38.439Z, address: '...', connectionId: 1, reason: 'poolClosed', serviceId: undefined }
connectionCheckOutStarted
ConnectionCheckOutStartedEvent { time: 2023-02-13T15:56:38.291Z, address: '...', }
connectionCheckOutFailed
ConnectionCheckOutFailedEvent { time: 2023-02-13T15:56:38.291Z, address: '...', reason: ... }
connectionCheckedOut
ConnectionCheckedOutEvent { time: 2023-02-13T15:54:07.188Z, address: '...', connectionId: 1 }
connectionCheckedIn
ConnectionCheckedInEvent { time: 2023-02-13T15:54:07.189Z, address: '...', connectionId: 1 }
connectionPoolCleared
ConnectionPoolClearedEvent { time: 2023-02-13T15:56:38.439Z, address: '...', serviceId: undefined, interruptInUseConnections: true, }