1 // Copyright (C) MongoDB, Inc. 2017-present. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may 4 // not use this file except in compliance with the License. You may obtain 5 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 6 7 package event // import "go.mongodb.org/mongo-driver/event" 8 9 import ( 10 "context" 11 "time" 12 13 "go.mongodb.org/mongo-driver/bson" 14 "go.mongodb.org/mongo-driver/bson/primitive" 15 "go.mongodb.org/mongo-driver/mongo/address" 16 "go.mongodb.org/mongo-driver/mongo/description" 17 ) 18 19 // CommandStartedEvent represents an event generated when a command is sent to a server. 20 type CommandStartedEvent struct { 21 Command bson.Raw 22 DatabaseName string 23 CommandName string 24 RequestID int64 25 ConnectionID string 26 // ServerConnectionID contains the connection ID from the server of the operation. If the server does not return 27 // this value (e.g. on MDB < 4.2), it is unset. If the server connection ID would cause an int32 overflow, then 28 // then this field will be nil. 29 // 30 // Deprecated: Use ServerConnectionID64. 31 ServerConnectionID *int32 32 // ServerConnectionID64 contains the connection ID from the server of the operation. If the server does not 33 // return this value (e.g. on MDB < 4.2), it is unset. 34 ServerConnectionID64 *int64 35 // ServiceID contains the ID of the server to which the command was sent if it is running behind a load balancer. 36 // Otherwise, it is unset. 37 ServiceID *primitive.ObjectID 38 } 39 40 // CommandFinishedEvent represents a generic command finishing. 41 type CommandFinishedEvent struct { 42 // Deprecated: Use Duration instead. 43 DurationNanos int64 44 Duration time.Duration 45 CommandName string 46 DatabaseName string 47 RequestID int64 48 ConnectionID string 49 // ServerConnectionID contains the connection ID from the server of the operation. If the server does not return 50 // this value (e.g. on MDB < 4.2), it is unset.If the server connection ID would cause an int32 overflow, then 51 // this field will be nil. 52 // 53 // Deprecated: Use ServerConnectionID64. 54 ServerConnectionID *int32 55 // ServerConnectionID64 contains the connection ID from the server of the operation. If the server does not 56 // return this value (e.g. on MDB < 4.2), it is unset. 57 ServerConnectionID64 *int64 58 // ServiceID contains the ID of the server to which the command was sent if it is running behind a load balancer. 59 // Otherwise, it is unset. 60 ServiceID *primitive.ObjectID 61 } 62 63 // CommandSucceededEvent represents an event generated when a command's execution succeeds. 64 type CommandSucceededEvent struct { 65 CommandFinishedEvent 66 Reply bson.Raw 67 } 68 69 // CommandFailedEvent represents an event generated when a command's execution fails. 70 type CommandFailedEvent struct { 71 CommandFinishedEvent 72 Failure string 73 } 74 75 // CommandMonitor represents a monitor that is triggered for different events. 76 type CommandMonitor struct { 77 Started func(context.Context, *CommandStartedEvent) 78 Succeeded func(context.Context, *CommandSucceededEvent) 79 Failed func(context.Context, *CommandFailedEvent) 80 } 81 82 // strings for pool command monitoring reasons 83 const ( 84 ReasonIdle = "idle" 85 ReasonPoolClosed = "poolClosed" 86 ReasonStale = "stale" 87 ReasonConnectionErrored = "connectionError" 88 ReasonTimedOut = "timeout" 89 ReasonError = "error" 90 ) 91 92 // strings for pool command monitoring types 93 const ( 94 PoolCreated = "ConnectionPoolCreated" 95 PoolReady = "ConnectionPoolReady" 96 PoolCleared = "ConnectionPoolCleared" 97 PoolClosedEvent = "ConnectionPoolClosed" 98 ConnectionCreated = "ConnectionCreated" 99 ConnectionReady = "ConnectionReady" 100 ConnectionClosed = "ConnectionClosed" 101 GetStarted = "ConnectionCheckOutStarted" 102 GetFailed = "ConnectionCheckOutFailed" 103 GetSucceeded = "ConnectionCheckedOut" 104 ConnectionReturned = "ConnectionCheckedIn" 105 ) 106 107 // MonitorPoolOptions contains pool options as formatted in pool events 108 type MonitorPoolOptions struct { 109 MaxPoolSize uint64 `json:"maxPoolSize"` 110 MinPoolSize uint64 `json:"minPoolSize"` 111 WaitQueueTimeoutMS uint64 `json:"maxIdleTimeMS"` 112 } 113 114 // PoolEvent contains all information summarizing a pool event 115 type PoolEvent struct { 116 Type string `json:"type"` 117 Address string `json:"address"` 118 ConnectionID uint64 `json:"connectionId"` 119 PoolOptions *MonitorPoolOptions `json:"options"` 120 Duration time.Duration `json:"duration"` 121 Reason string `json:"reason"` 122 // ServiceID is only set if the Type is PoolCleared and the server is deployed behind a load balancer. This field 123 // can be used to distinguish between individual servers in a load balanced deployment. 124 ServiceID *primitive.ObjectID `json:"serviceId"` 125 Interruption bool `json:"interruptInUseConnections"` 126 Error error `json:"error"` 127 } 128 129 // PoolMonitor is a function that allows the user to gain access to events occurring in the pool 130 type PoolMonitor struct { 131 Event func(*PoolEvent) 132 } 133 134 // ServerDescriptionChangedEvent represents a server description change. 135 type ServerDescriptionChangedEvent struct { 136 Address address.Address 137 TopologyID primitive.ObjectID // A unique identifier for the topology this server is a part of 138 PreviousDescription description.Server 139 NewDescription description.Server 140 } 141 142 // ServerOpeningEvent is an event generated when the server is initialized. 143 type ServerOpeningEvent struct { 144 Address address.Address 145 TopologyID primitive.ObjectID // A unique identifier for the topology this server is a part of 146 } 147 148 // ServerClosedEvent is an event generated when the server is closed. 149 type ServerClosedEvent struct { 150 Address address.Address 151 TopologyID primitive.ObjectID // A unique identifier for the topology this server is a part of 152 } 153 154 // TopologyDescriptionChangedEvent represents a topology description change. 155 type TopologyDescriptionChangedEvent struct { 156 TopologyID primitive.ObjectID // A unique identifier for the topology this server is a part of 157 PreviousDescription description.Topology 158 NewDescription description.Topology 159 } 160 161 // TopologyOpeningEvent is an event generated when the topology is initialized. 162 type TopologyOpeningEvent struct { 163 TopologyID primitive.ObjectID // A unique identifier for the topology this server is a part of 164 } 165 166 // TopologyClosedEvent is an event generated when the topology is closed. 167 type TopologyClosedEvent struct { 168 TopologyID primitive.ObjectID // A unique identifier for the topology this server is a part of 169 } 170 171 // ServerHeartbeatStartedEvent is an event generated when the heartbeat is started. 172 type ServerHeartbeatStartedEvent struct { 173 ConnectionID string // The address this heartbeat was sent to with a unique identifier 174 Awaited bool // If this heartbeat was awaitable 175 } 176 177 // ServerHeartbeatSucceededEvent is an event generated when the heartbeat succeeds. 178 type ServerHeartbeatSucceededEvent struct { 179 // Deprecated: Use Duration instead. 180 DurationNanos int64 181 Duration time.Duration 182 Reply description.Server 183 ConnectionID string // The address this heartbeat was sent to with a unique identifier 184 Awaited bool // If this heartbeat was awaitable 185 } 186 187 // ServerHeartbeatFailedEvent is an event generated when the heartbeat fails. 188 type ServerHeartbeatFailedEvent struct { 189 // Deprecated: Use Duration instead. 190 DurationNanos int64 191 Duration time.Duration 192 Failure error 193 ConnectionID string // The address this heartbeat was sent to with a unique identifier 194 Awaited bool // If this heartbeat was awaitable 195 } 196 197 // ServerMonitor represents a monitor that is triggered for different server events. The client 198 // will monitor changes on the MongoDB deployment it is connected to, and this monitor reports 199 // the changes in the client's representation of the deployment. The topology represents the 200 // overall deployment, and heartbeats are sent to individual servers to check their current status. 201 type ServerMonitor struct { 202 ServerDescriptionChanged func(*ServerDescriptionChangedEvent) 203 ServerOpening func(*ServerOpeningEvent) 204 ServerClosed func(*ServerClosedEvent) 205 // TopologyDescriptionChanged is called when the topology is locked, so the callback should 206 // not attempt any operation that requires server selection on the same client. 207 TopologyDescriptionChanged func(*TopologyDescriptionChangedEvent) 208 TopologyOpening func(*TopologyOpeningEvent) 209 TopologyClosed func(*TopologyClosedEvent) 210 ServerHeartbeatStarted func(*ServerHeartbeatStartedEvent) 211 ServerHeartbeatSucceeded func(*ServerHeartbeatSucceededEvent) 212 ServerHeartbeatFailed func(*ServerHeartbeatFailedEvent) 213 } 214