Docs Menu
Docs Home
/ / /
Go Driver
/ /

Cluster Monitoring

On this page

  • Overview
  • Subscribe to Events
  • Event Descriptions
  • Example Event Documents
  • ServerDescriptionChangedEvent
  • ServerOpeningEvent
  • ServerClosedEvent
  • TopologyDescriptionChangedEvent
  • TopologyOpeningEvent
  • TopologyClosedEvent
  • ServerHeartbeatStartedEvent
  • ServerHeartbeatSucceededEvent
  • ServerHeartbeatFailedEvent
  • API Documentation

This guide shows you how to use the Go driver 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 are any changes in the state of the instance or cluster that you are connected to.

You might use information about topology events in your application to understand cluster changes, assess cluster health, or perform capacity planning.

Tip

Logging

You can also configure logging in your application to learn more about driver events. To learn more, see Logging.

You can access details about SDAM events by subscribing to them in your application. The following example demonstrates how to subscribe to the ServerClosed event by instantiating a ServerMonitor and connecting to a deployment:

var eventArray []*event.ServerClosedEvent
srvMonitor := &event.ServerMonitor{
ServerClosed: func(e *event.ServerClosedEvent) {
eventArray = append(eventArray, e)
},
}
clientOpts := options.Client().ApplyURI(uri).SetServerMonitor(srvMonitor)
client, err := mongo.Connect(context.TODO(), clientOpts)

You can subscribe to the following SDAM events by specifying properties of a ServerMonitor instance:

Event Name
Description
ServerDescriptionChangedEvent
Created when an instance state changes (such as from secondary to primary).
ServerOpeningEvent
Created when the server is initialized.
ServerClosedEvent
Created when the server is closed.
TopologyDescriptionChangedEvent
Created when the topology changes, such as an election of a new primary or disconnection of a mongos proxy.
TopologyOpeningEvent
Created when the topology is initialized.
TopologyClosedEvent
Created when the topology is closed.
ServerHeartbeatStartedEvent
Created when the heartbeat is started.
ServerHeartbeatSucceededEvent
Created when the heartbeat succeeds.
ServerHeartbeatFailedEvent
Created when the heartbeat fails.

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

*event.ServerDescriptionChangedEvent
{
"Address": "...",
"TopologyID": "...",
"PreviousDescription": {
"Addr": "...",
"Arbiters": null,
"AverageRTT": 0,
"AverageRTTSet": false,
"Compression": null,
"CanonicalAddr": "...",
"ElectionID": "...",
"HeartbeatInterval": 0,
"HelloOK": false,
"Hosts": null,
"LastError": null,
"LastUpdateTime": "...",
"LastWriteTime": "...",
"MaxBatchCount": 0,
"MaxDocumentSize": 0,
"MaxMessageSize": 0,
"Members": null,
"Passives": null,
"Passive": false,
"Primary": "...",
"ReadOnly": false,
"ServiceID": null,
"SessionTimeoutMinutes": 0,
"SetName": "...",
"SetVersion": 0,
"Tags": null,
"TopologyVersion": null,
"Kind": 0,
"WireVersion": null
},
"NewDescription": {
"Addr": "...",
"Arbiters": null,
"AverageRTT": ...,
"AverageRTTSet": true,
"Compression": null,
"CanonicalAddr": "...",
"ElectionID": "...",
"HeartbeatInterval": ...,
"HelloOK": true,
"Hosts": [...],
"LastError": null,
"LastUpdateTime": "...",
"LastWriteTime": "...",
"MaxBatchCount": ...,
"MaxDocumentSize": ...,
"MaxMessageSize": ...,
"Members": [...],
"Passives": null,
"Passive": false,
"Primary": "...",
"ReadOnly": false,
"ServiceID": null,
"SessionTimeoutMinutes": 30,
"SetName": "...",
"SetVersion": 9,
"Tags": [...],
"TopologyVersion": {...},
"Kind": 10,
"WireVersion": {...}
}
}

The Kind field in an event document represents the type of a single server in a topology and can have the following values:

Value
Description
0
Unknown instance
1
Standalone instance
2
Replica set member
6
Primary instance
10
Secondary instance
18
Arbiter instance
34
Replica set ghost (a member that cannot be queried)
256
mongos proxy instance
512
Load balancer instance
*event.ServerOpeningEvent
{
"Address": "...",
"TopologyID": "..."
}
*event.ServerClosedEvent
{
"Address": "...",
"TopologyID": "..."
}

Important

Because the driver calls TopologyDescriptionChangedEvent when the deployment topology is locked, the callback (function argument) for this event must not attempt any operation that requires server selection on the same client.

*event.TopologyDescriptionChangedEvent
{
"TopologyID": "...",
"PreviousDescription": {
"Servers": [
{
"Addr": "...",
"Arbiters": null,
"AverageRTT": 0,
"AverageRTTSet": false,
"Compression": null,
"CanonicalAddr": "...",
"ElectionID": "...",
"HeartbeatInterval": 0,
"HelloOK": false,
"Hosts": null,
"LastError": null,
"LastUpdateTime": "...",
"LastWriteTime": "...",
"MaxBatchCount": 0,
"MaxDocumentSize": 0,
"MaxMessageSize": 0,
"Members": null,
"Passives": null,
"Passive": false,
"Primary": "...",
"ReadOnly": false,
"ServiceID": null,
"SessionTimeoutMinutes": 0,
"SetName": "...",
"SetVersion": 0,
"Tags": null,
"TopologyVersion": null,
"Kind": 0,
"WireVersion": null
},
...
],
"SetName": "...",
"Kind": 10,
"SessionTimeoutMinutes": 30,
"CompatibilityErr": null
},
"NewDescription": {
"Servers": [...],
"SetName": "...",
"Kind": 10,
"SessionTimeoutMinutes": 30,
"CompatibilityErr": null
}
}

To interpret the value of the Kind field, see the Kind Field Value section.

*event.TopologyOpeningEvent
{
"TopologyID": "..."
}
*event.TopologyClosedEvent
{
"TopologyID": "..."
}
*event.ServerHeartbeatStartedEvent
{
"ConnectionID": "...",
"Awaited": true
}
*event.ServerHeartbeatSucceededEvent
{
"DurationNanos": ...,
"Reply": {
"Addr": "...",
"Arbiters": null,
"AverageRTT": 0,
"AverageRTTSet": false,
"Compression": null,
"CanonicalAddr": "...",
"ElectionID": "...",
"HeartbeatInterval": 0,
"HelloOK": true,
"Hosts": [...],
"LastError": null,
"LastUpdateTime": "...",
"LastWriteTime": "...",
"MaxBatchCount": ...,
"MaxDocumentSize": ...,
"MaxMessageSize": ...,
"Members": [...],
"Passives": null,
"Passive": false,
"Primary": "...",
"ReadOnly": false,
"ServiceID": null,
"SessionTimeoutMinutes": 30,
"SetName": "...",
"SetVersion": 9,
"Tags": [...],
"TopologyVersion": {...},
"Kind": 6,
"WireVersion": {...}
},
"ConnectionID": "...",
"Awaited": true
}

To interpret the value of the Kind field, see the Kind Field Value section.

*event.ServerHeartbeatFailedEvent
{
"DurationNanos": ...,
"Failure": "<error message>"
"ConnectionID": "...",
"Awaited": true
}
← Monitoring