Docs Menu

Docs Home → Develop Applications → MongoDB Drivers → Node.js

Cluster Monitoring

On this page

  • Overview
  • Event Subscription Example
  • Event Descriptions
  • Example Event Documents
  • serverDescriptionChanged
  • serverHeartbeatStarted
  • serverHeartbeatSucceeded
  • serverHeartbeatFailed
  • serverOpening
  • serverClosed
  • topologyOpening
  • topologyClosed
  • topologyDescriptionChanged

Overview

This guide shows you how to monitor topology events in a MongoDB instance, replica set, or sharded cluster. The driver creates topology events, also known as Server Discovery and Monitoring (SDAM) events, when there is a change in the state of the instance or cluster that you connected to. For example, the driver creates an event when you establish a new connection or if the cluster elects a new primary.

Read this guide if you need to record topology changes in your application or want to explore the information provided in these events.

Event Subscription Example

You can access one or more SDAM 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 SDAM 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>";
client.on(eventName, event => {
  console.log(`received ${eventName}: ${JSON.stringify(event, null, 2)}`);
});
async function run() {
  try {
    await client.connect();
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

Event Descriptions

You can subscribe to any of the following SDAM events:

Event Name
Description
serverOpening
Created when a connection to an instance opens.
serverClosed
Created when a connection to an instance closes.
serverDescriptionChanged
Created when an instance state changes (such as from secondary to primary).
topologyOpening
Created prior to attempting a connection to an instance.
topologyClosed
Created after all instance connections in the topology close.
topologyDescriptionChanged
Created when the topology changes, such as an election of a new primary or a mongos proxy disconnecting.
serverHeartbeatStarted
Created prior to issuing a hello command to a MongoDB instance.
serverHeartbeatSucceeded
Created when the hello command returns successfully from a MongoDB instance.
serverHeartbeatFailed
Created when a hello command issued to a specific MongoDB instance fails to return a successful response.

Example Event Documents

The following sections show sample output for each type of SDAM event.

serverDescriptionChanged

ServerDescriptionChangedEvent {
  topologyId: 0,
  address: 'localhost:27017',
  previousDescription: ServerDescription {
    address: 'localhost:27017',
    error: null,
    roundTripTime: 0,
    lastUpdateTime: 1571251089030,
    lastWriteDate: null,
    opTime: null,
    type: 'Unknown',
    minWireVersion: 0,
    maxWireVersion: 0,
    hosts: [],
    passives: [],
    arbiters: [],
    tags: []
  },
  newDescription: ServerDescription {
    address: 'localhost:27017',
    error: null,
    roundTripTime: 0,
    lastUpdateTime: 1571251089051,
    lastWriteDate: 2019-10-16T18:38:07.000Z,
    opTime: { ts: Timestamp, t: 18 },
    type: 'RSPrimary',
    minWireVersion: 0,
    maxWireVersion: 7,
    maxBsonObjectSize: 16777216,
    maxMessageSizeBytes: 48000000,
    maxWriteBatchSize: 100000,
    me: 'localhost:27017',
    hosts: [ 'localhost:27017' ],
    passives: [],
    arbiters: [],
    tags: [],
    setName: 'rs',
    setVersion: 1,
    electionId: ObjectID,
    primary: 'localhost:27017',
    logicalSessionTimeoutMinutes: 30,
    '$clusterTime': ClusterTime
  }
}

The type field of the ServerDescription object in this event contains one of the following possible values:

Type
Description
Unknown
Unknown instance
Standalone
Standalone instance
Mongos
Mongos proxy instance
PossiblePrimary
At least one server recognizes this as the primary, but is not yet verified by all instances.
RSPrimary
Primary instance
RSSecondary
Secondary instance
RSArbiter
Arbiter instance
RSOther
See the RSGhost specification for more details
RSGhost
See the RSOther specification for more details

serverHeartbeatStarted

ServerHeartbeatStartedEvent {
  connectionId: 'localhost:27017'
}

serverHeartbeatSucceeded

ServerHeartbeatSucceededEvent {
  duration: 1.939997,
  reply:{
    hosts: [ 'localhost:27017' ],
    setName: 'rs',
    setVersion: 1,
    isWritablePrimary: true,
    secondary: false,
    primary: 'localhost:27017',
    me: 'localhost:27017',
    electionId: ObjectID,
    lastWrite: {
      opTime: { ts: [Timestamp], t: 18 },
      lastWriteDate: 2019-10-16T18:38:17.000Z,
      majorityOpTime: { ts: [Timestamp], t: 18 },
      majorityWriteDate: 2019-10-16T18:38:17.000Z
    },
    maxBsonObjectSize: 16777216,
    maxMessageSizeBytes: 48000000,
    maxWriteBatchSize: 100000,
    localTime: 2019-10-16T18:38:19.589Z,
    logicalSessionTimeoutMinutes: 30,
    minWireVersion: 0,
    maxWireVersion: 7,
    readOnly: false,
    ok: 1,
    operationTime: Timestamp,
    '$clusterTime': ClusterTime
  },
  connectionId: 'localhost:27017'
}

serverHeartbeatFailed

ServerHeartbeatFailed {
  duration: 20,
  failure: MongoError('some error'),
  connectionId: 'localhost:27017'
}

serverOpening

ServerOpeningEvent {
  topologyId: 0,
  address: 'localhost:27017'
}

serverClosed

ServerClosedEvent {
  topologyId: 0,
  address: 'localhost:27017'
}

topologyOpening

TopologyOpeningEvent {
  topologyId: 0
}

topologyClosed

TopologyClosedEvent {
  topologyId: 0
}

topologyDescriptionChanged

TopologyDescriptionChangedEvent {
  topologyId: 0,
  previousDescription: TopologyDescription {
    type: 'ReplicaSetNoPrimary',
    setName: null,
    maxSetVersion: null,
    maxElectionId: null,
    servers: Map {
      'localhost:27017' => ServerDescription
    },
    stale: false,
    compatible: true,
    compatibilityError: null,
    logicalSessionTimeoutMinutes: null,
    heartbeatFrequencyMS: 10000,
    localThresholdMS: 15,
    options: Object,
    error: undefined,
    commonWireVersion: null
  },
  newDescription: TopologyDescription {
    type: 'ReplicaSetWithPrimary',
    setName: 'rs',
    maxSetVersion: 1,
    maxElectionId: null,
    servers: Map {
      'localhost:27017' => ServerDescription
    },
    stale: false,
    compatible: true,
    compatibilityError: null,
    logicalSessionTimeoutMinutes: 30,
    heartbeatFrequencyMS: 10000,
    localThresholdMS: 15,
    options: Object,
    error: undefined,
    commonWireVersion: 7
  }
}

The type field of the TopologyDescription object in this event contains one of the following possible values:

Type
Description
Single
Standalone instance
ReplicaSetWithPrimary
Replica set with a primary
ReplicaSetNoPrimary
Replica set with no primary
Sharded
Sharded cluster
Unknown
Unknown topology
←  MonitoringCommand Monitoring →

On this page