DRIVERS-1670: Add log messages to SDAM spec (#1419)

Co-authored-by: Kaitlin Mahar <kaitlinmahar@gmail.com>
mongodb · Jul 20, 2023 · 9f68487 · 9f68487
1 parent 9d7ceed
commit 9f68487
Show file tree

Hide file tree

Showing 19 changed files with 3,834 additions and 84 deletions.
diff --git a/source/load-balancers/load-balancers.rst b/source/load-balancers/load-balancers.rst
@@ -82,8 +82,8 @@ When a MongoClient is configured with an SRV URI and :code:`loadBalanced=true`,
 driver MUST NOT poll for changes in the SRV record as is done for non-load balanced
 sharded clusters.
 
-Server Discovery and Monitoring
--------------------------------
+Server Discovery Logging and Monitoring
+---------------------------------------
 
 Monitoring
 ^^^^^^^^^^
@@ -116,6 +116,18 @@ the following series of SDAM events:
 Drivers MUST also emit a :code:`ServerClosedEvent` and :code:`TopologyClosedEvent` when
 the topology is closed and MUST NOT emit any other events when operating in this mode.
 
+Log Messages
+^^^^^^^^^^^^
+
+SDAM events details described in `Monitoring <#monitoring>_` apply to corresponding log messages.
+Please refer to the `SDAM logging specification <../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring#log-messages>`_ 
+for details on SDAM logging. Drivers MUST emit the relevant SDAM log messages, such as:
+
+- `Starting Topology Monitoring <../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst#starting-topology-monitoring-log-message>`_ 
+- `Stopped Topology Mmonitoring <../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst#stopped-topology-monitoring-log-message>`_ 
+- `Starting Server Monitoring <../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst#starting-server-monitoring-log-message>`_ 
+- `Stopped Server Monitoring <../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst#stopped-server-monitoring-log-message>`_ 
+- `Topology Description Changed <../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst#topology-description-changed-log-message>`_ 
 
 Driver Sessions
 ---------------

diff --git a/.../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst b/.../server-discovery-and-monitoring/server-discovery-and-monitoring-monitoring.rst
diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst b/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst
@@ -101,7 +101,7 @@ Terms
 Server
 ``````
 
-A mongod or mongos process.
+A mongod or mongos process, or a load balancer.
 
 Deployment
 ``````````
@@ -853,7 +853,7 @@ type Unknown.
 TopologyType LoadBalanced
 `````````````````````````
 
-See the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-discovery-and-monitoring>`__ for details.
+See the `Load Balancer Specification <../load-balancers/load-balancers.rst#server-discovery-logging-and-monitoring>`__ for details.
 
 Other TopologyTypes
 ```````````````````

diff --git a/source/server-discovery-and-monitoring/tests/unified/logging-loadbalanced.json b/source/server-discovery-and-monitoring/tests/unified/logging-loadbalanced.json
@@ -0,0 +1,150 @@
+{
+  "description": "loadbalanced-logging",
+  "schemaVersion": "1.16",
+  "runOnRequirements": [
+    {
+      "topologies": [
+        "load-balanced"
+      ],
+      "minServerVersion": "4.4"
+    }
+  ],
+  "tests": [
+    {
+      "description": "Topology lifecycle",
+      "operations": [
+        {
+          "name": "createEntities",
+          "object": "testRunner",
+          "arguments": {
+            "entities": [
+              {
+                "client": {
+                  "id": "client",
+                  "observeLogMessages": {
+                    "topology": "debug"
+                  },
+                  "observeEvents": [
+                    "topologyDescriptionChangedEvent"
+                  ]
+                }
+              }
+            ]
+          }
+        },
+        {
+          "name": "waitForEvent",
+          "object": "testRunner",
+          "arguments": {
+            "client": "client",
+            "event": {
+              "topologyDescriptionChangedEvent": {}
+            },
+            "count": 2
+          }
+        },
+        {
+          "name": "close",
+          "object": "client"
+        }
+      ],
+      "expectLogMessages": [
+        {
+          "client": "client",
+          "messages": [
+            {
+              "level": "debug",
+              "component": "topology",
+              "data": {
+                "message": "Starting topology monitoring",
+                "topologyId": {
+                  "$$exists": true
+                }
+              }
+            },
+            {
+              "level": "debug",
+              "component": "topology",
+              "data": {
+                "message": "Topology description changed",
+                "topologyId": {
+                  "$$exists": true
+                },
+                "previousDescription": {
+                  "$$exists": true
+                },
+                "newDescription": {
+                  "$$exists": true
+                }
+              }
+            },
+            {
+              "level": "debug",
+              "component": "topology",
+              "data": {
+                "message": "Starting server monitoring",
+                "topologyId": {
+                  "$$exists": true
+                },
+                "serverHost": {
+                  "$$type": "string"
+                },
+                "serverPort": {
+                  "$$type": [
+                    "int",
+                    "long"
+                  ]
+                }
+              }
+            },
+            {
+              "level": "debug",
+              "component": "topology",
+              "data": {
+                "message": "Topology description changed",
+                "topologyId": {
+                  "$$exists": true
+                },
+                "previousDescription": {
+                  "$$exists": true
+                },
+                "newDescription": {
+                  "$$exists": true
+                }
+              }
+            },
+            {
+              "level": "debug",
+              "component": "topology",
+              "data": {
+                "message": "Stopped server monitoring",
+                "topologyId": {
+                  "$$exists": true
+                },
+                "serverHost": {
+                  "$$type": "string"
+                },
+                "serverPort": {
+                  "$$type": [
+                    "int",
+                    "long"
+                  ]
+                }
+              }
+            },
+            {
+              "level": "debug",
+              "component": "topology",
+              "data": {
+                "message": "Stopped topology monitoring",
+                "topologyId": {
+                  "$$exists": true
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/source/server-discovery-and-monitoring/tests/unified/logging-loadbalanced.yml b/source/server-discovery-and-monitoring/tests/unified/logging-loadbalanced.yml
@@ -0,0 +1,74 @@
+description: "loadbalanced-logging"
+
+schemaVersion: "1.16"
+
+runOnRequirements:
+  - topologies:
+      - load-balanced
+    minServerVersion: "4.4" # awaitable hello
+
+tests:
+  - description: "Topology lifecycle"
+    operations:
+      - name: createEntities
+        object: testRunner
+        arguments:
+          entities:
+            - client:
+                id: &client client
+                observeLogMessages:
+                  topology: debug
+                observeEvents:
+                  - topologyDescriptionChangedEvent
+      # ensure the topology has been fully discovered before closing the client.
+      # expected events are initial server discovery and server connect event.
+      - name: waitForEvent
+        object: testRunner
+        arguments:
+          client: *client
+          event:
+            topologyDescriptionChangedEvent: {}
+          count: 2
+      - name: close
+        object: *client
+    expectLogMessages:
+      - client: *client
+        messages:
+          - level: debug
+            component: topology
+            data:
+              message: "Starting topology monitoring"
+              topologyId: { $$exists: true }
+          - level: debug
+            component: topology
+            data:
+              message: "Topology description changed"
+              topologyId: { $$exists: true }
+              previousDescription:  { $$exists: true } # unknown topology
+              newDescription: { $$exists: true } # unknown topology, disconnected server
+          - level: debug
+            component: topology
+            data:
+              message: "Starting server monitoring"
+              topologyId: { $$exists: true }
+              serverHost: { $$type: string }
+              serverPort: { $$type: [int, long] }
+          - level: debug
+            component: topology
+            data:
+              message: "Topology description changed"
+              topologyId: { $$exists: true }
+              previousDescription:  { $$exists: true }
+              newDescription: { $$exists: true } # loadBalanced topology
+          - level: debug
+            component: topology
+            data:
+              message: "Stopped server monitoring"
+              topologyId: { $$exists: true }
+              serverHost: { $$type: string }
+              serverPort: { $$type: [int, long] }
+          - level: debug
+            component: topology
+            data:
+              message: "Stopped topology monitoring"
+              topologyId: { $$exists: true }