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 version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of the MongoDB Go Driver.

Overview

In this guide, you can learn 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 are changes in the state of the instance or cluster that you are connected to. For example, the driver creates an SDAM event when you establish a new connection or when the cluster elects a new primary.

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

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(svrMonitor)
client, err := mongo.Connect(context.Background(), 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 TopologyDescriptionChanged when the deployment topology is locked, the callback (function argument) for this event should 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
}