DRIVERS-719 OpenTelemetry specification

source/index.md

@@ -36,6 +36,7 @@
 - [MongoDB Handshake](mongodb-handshake/handshake.md)
 - [OCSP Support](ocsp-support/ocsp-support.md)
 - [OP_MSG](message/OP_MSG.md)
+- [OpenTelemetry](open-telemetry/open-telemetry.md)
 - [Performance Benchmarking](benchmarking/benchmarking.md)
 - [Polling SRV Records for mongos Discovery](polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md)
 - [Read and Write Concern](read-write-concern/read-write-concern.md)

source/open-telemetry/tests/README.md

@@ -0,0 +1,60 @@
+# OpenTelemetry Tests
+
+______________________________________________________________________
+
+## Testing
+
+### Automated Tests
+
+The YAML and JSON files in this directory are platform-independent tests meant to exercise a driver's implementation of
+the OpenTelemetry specification. These tests utilize the
+[Unified Test Format](../../unified-test-format/unified-test-format.md).
+
+For each test, create a MongoClient, configure it to enable tracing.
+
+```yaml
+createEntities:
+  - client:
+      id: client0
+      observeTracingMessages:
+        enableCommandPayload: true
+```
+
+These tests require the ability to collect tracing [spans](../open-telemetry.md) data in a structured form as described
+in the
+[Unified Test Format specification.expectTracingMessages](../../unified-test-format/unified-test-format.md#expectTracingMessages).
+For example the Java driver uses [Micrometer](https://jira.mongodb.org/browse/JAVA-5732) to collect tracing spans.
+
+```yaml
+expectTracingMessages:
+  client: client0
+  ignoreExtraSpans: false
+  spans:
+   ...
+```
+
+### Prose Tests
+
+*Test 1: Tracing Enable/Disable via Environment Variable*
+
+1. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_ENABLED` to `false`.
+2. Create a `MongoClient` without explicitly enabling tracing.
+3. Perform a database operation (e.g., `find()` on a test collection).
+4. Assert that no OpenTelemetry tracing spans are emitted for the operation.
+5. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_ENABLED` to `true`.
+6. Create a new `MongoClient` without explicitly enabling tracing.
+7. Perform the same database operation.
+8. Assert that OpenTelemetry tracing spans are emitted for the operation.
+
+*Test 2: Command Payload Emission via Environment Variable*
+
+1. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_ENABLED` to `true`.
+2. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH` to a positive integer
+    (e.g., 1024).
+3. Create a `MongoClient` without explicitly enabling command payload emission.
+4. Perform a database operation (e.g., `find()`).
+5. Assert that the emitted tracing span includes the `db.query.text` attribute.
+6. Unset the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH`.
+7. Create a new `MongoClient`.
+8. Perform the same database operation.
+9. Assert that the emitted tracing span does not include the `db.query.text` attribute.

source/open-telemetry/tests/operation/aggregate.json

@@ -0,0 +1,130 @@
+{
+  "description": "operation aggregate",
+  "schemaVersion": "1.27",
+  "createEntities": [
+    {
+      "client": {
+        "id": "client0",
+        "useMultipleMongoses": false,
+        "observeTracingMessages": {
+          "enableCommandPayload": true
+        }
+      }
+    },
+    {
+      "database": {
+        "id": "database0",
+        "client": "client0",
+        "databaseName": "operation-aggregate"
+      }
+    },
+    {
+      "collection": {
+        "id": "collection0",
+        "database": "database0",
+        "collectionName": "test"
+      }
+    }
+  ],
+  "tests": [
+    {
+      "description": "aggregation",
+      "operations": [
+        {
+          "name": "aggregate",
+          "object": "collection0",
+          "arguments": {
+            "pipeline": [
+              {
+                "$match": {
+                  "_id": 1
+                }
+              }
+            ]
+          }
+        }
+      ],
+      "expectTracingMessages": [
+        {
+          "client": "client0",
+          "ignoreExtraSpans": false,
+          "spans": [
+            {
+              "name": "aggregate operation-aggregate.test",
+              "attributes": {
+                "db.system": "mongodb",
+                "db.namespace": "operation-aggregate",
+                "db.collection.name": "test",
+                "db.operation.name": "aggregate",
+                "db.operation.summary": "aggregate operation-aggregate.test"
+              },
+              "nested": [
+                {
+                  "name": "aggregate",
+                  "attributes": {
+                    "db.system": "mongodb",
+                    "db.namespace": "operation-aggregate",
+                    "db.collection.name": "test",
+                    "db.command.name": "aggregate",
+                    "network.transport": "tcp",
+                    "db.mongodb.cursor_id": {
+                      "$$exists": false
+                    },
+                    "db.response.status_code": {
+                      "$$exists": false
+                    },
+                    "exception.message": {
+                      "$$exists": false
+                    },
+                    "exception.type": {
+                      "$$exists": false
+                    },
+                    "exception.stacktrace": {
+                      "$$exists": false
+                    },
+                    "server.address": {
+                      "$$type": "string"
+                    },
+                    "server.port": {
+                      "$$type": [
+                        "int",
+                        "long"
+                      ]
+                    },
+                    "db.query.summary": "aggregate operation-aggregate.test",
+                    "db.query.text": {
+                      "$$matchAsDocument": {
+                        "$$matchAsRoot": {
+                          "aggregate": "test",
+                          "pipeline": [
+                            {
+                              "$match": {
+                                "_id": 1
+                              }
+                            }
+                          ]
+                        }
+                      }
+                    },
+                    "db.mongodb.server_connection_id": {
+                      "$$type": [
+                        "int",
+                        "long"
+                      ]
+                    },
+                    "db.mongodb.driver_connection_id": {
+                      "$$type": [
+                        "int",
+                        "long"
+                      ]
+                    }
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

source/open-telemetry/tests/operation/aggregate.yml

@@ -0,0 +1,62 @@
+description: operation aggregate
+schemaVersion: '1.27'
+createEntities:
+  - client:
+      id: &client0 client0
+      useMultipleMongoses: false
+      observeTracingMessages:
+        enableCommandPayload: true
+  - database:
+      id: &database0 database0
+      client: *client0
+      databaseName: operation-aggregate
+  - collection:
+      id: &collection0 collection0
+      database: *database0
+      collectionName: &collectionName0 test
+
+tests:
+  - description: aggregation
+    operations:
+      - name: aggregate
+        object: *collection0
+        arguments:
+          pipeline: &pipeline0
+            - $match: { _id: 1 }
+
+    expectTracingMessages:
+      - client: *client0
+        ignoreExtraSpans: false
+        spans:
+          - name: aggregate operation-aggregate.test
+            attributes:
+              db.system: mongodb
+              db.namespace: operation-aggregate
+              db.collection.name: test
+              db.operation.name: aggregate
+              db.operation.summary: aggregate operation-aggregate.test
+            nested:
+              - name: aggregate
+                attributes:
+                  db.system: mongodb
+                  db.namespace: operation-aggregate
+                  db.collection.name: *collectionName0
+                  db.command.name: aggregate
+                  network.transport: tcp
+                  db.mongodb.cursor_id: { $$exists: false }
+                  db.response.status_code: { $$exists: false }
+                  exception.message: { $$exists: false }
+                  exception.type: { $$exists: false }
+                  exception.stacktrace: { $$exists: false }
+                  server.address: { $$type: string }
+                  server.port: { $$type: [int, long] }
+                  db.query.summary: aggregate operation-aggregate.test
+                  db.query.text:
+                    $$matchAsDocument:
+                      $$matchAsRoot:
+                        aggregate: test
+                        pipeline: *pipeline0
+                  db.mongodb.server_connection_id:
+                    $$type: [ int, long ]
+                  db.mongodb.driver_connection_id:
+                    $$type: [ int, long ]