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

Overview

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.

Subscribe to Events

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)

Event Descriptions

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.

Example Event Documents

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

ServerDescriptionChangedEvent

*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": {...}
    }
}

`Kind` Field Value

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

ServerOpeningEvent

*event.ServerOpeningEvent
{
    "Address": "...",
    "TopologyID": "..."
}

ServerClosedEvent

*event.ServerClosedEvent
{
    "Address": "...",
    "TopologyID": "..."
}

TopologyDescriptionChangedEvent

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.

TopologyOpeningEvent

*event.TopologyOpeningEvent
{
    "TopologyID": "..."
}

TopologyClosedEvent

*event.TopologyClosedEvent
{
    "TopologyID": "..."
}

ServerHeartbeatStartedEvent

*event.ServerHeartbeatStartedEvent
{
    "ConnectionID": "...",
    "Awaited": true
}

ServerHeartbeatSucceededEvent

*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.

ServerHeartbeatFailedEvent

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

API Documentation

Back

Monitoring

Command Monitoring