Skip to content

Commit f2912ba

Browse files
nhachichacomandeo-mongojmikola
authored
DRIVERS-719 OpenTelemetry specification (#1826)
Co-authored-by: nhachicha <[email protected]> Co-authored-by: Dmitry Rybakov <[email protected]> Co-authored-by: Jeremy Mikola <[email protected]> Co-authored-by: Dmitry Rybakov <[email protected]>
1 parent 4a46628 commit f2912ba

File tree

78 files changed

+7986
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

78 files changed

+7986
-1
lines changed

‎source/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
- [MongoDB Handshake](mongodb-handshake/handshake.md)
3737
- [OCSP Support](ocsp-support/ocsp-support.md)
3838
- [OP_MSG](message/OP_MSG.md)
39+
- [OpenTelemetry](open-telemetry/open-telemetry.md)
3940
- [Performance Benchmarking](benchmarking/benchmarking.md)
4041
- [Polling SRV Records for mongos Discovery](polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md)
4142
- [Read and Write Concern](read-write-concern/read-write-concern.md)

‎source/open-telemetry/open-telemetry.md‎

Lines changed: 424 additions & 0 deletions
Large diffs are not rendered by default.

‎source/open-telemetry/tests/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# OpenTelemetry Tests
2+
3+
______________________________________________________________________
4+
5+
## Testing
6+
7+
### Automated Tests
8+
9+
The YAML and JSON files in this directory are platform-independent tests meant to exercise a driver's implementation of
10+
the OpenTelemetry specification. These tests utilize the
11+
[Unified Test Format](../../unified-test-format/unified-test-format.md).
12+
13+
For each test, create a MongoClient, configure it to enable tracing.
14+
15+
```yaml
16+
createEntities:
17+
- client:
18+
id: client0
19+
observeTracingMessages:
20+
enableCommandPayload: true
21+
```
22+
23+
These tests require the ability to collect tracing [spans](../open-telemetry.md) data in a structured form as described
24+
in the
25+
[Unified Test Format specification.expectTracingMessages](../../unified-test-format/unified-test-format.md#expectTracingMessages).
26+
For example the Java driver uses [Micrometer](https://jira.mongodb.org/browse/JAVA-5732) to collect tracing spans.
27+
28+
```yaml
29+
expectTracingMessages:
30+
client: client0
31+
ignoreExtraSpans: false
32+
spans:
33+
...
34+
```
35+
36+
### Prose Tests
37+
38+
*Test 1: Tracing Enable/Disable via Environment Variable*
39+
40+
1. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_ENABLED` to `false`.
41+
2. Create a `MongoClient` without explicitly enabling tracing.
42+
3. Perform a database operation (e.g., `find()` on a test collection).
43+
4. Assert that no OpenTelemetry tracing spans are emitted for the operation.
44+
5. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_ENABLED` to `true`.
45+
6. Create a new `MongoClient` without explicitly enabling tracing.
46+
7. Perform the same database operation.
47+
8. Assert that OpenTelemetry tracing spans are emitted for the operation.
48+
49+
*Test 2: Command Payload Emission via Environment Variable*
50+
51+
1. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_ENABLED` to `true`.
52+
2. Set the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH` to a positive integer
53+
(e.g., 1024).
54+
3. Create a `MongoClient` without explicitly enabling command payload emission.
55+
4. Perform a database operation (e.g., `find()`).
56+
5. Assert that the emitted tracing span includes the `db.query.text` attribute.
57+
6. Unset the environment variable `OTEL_#{LANG}_INSTRUMENTATION_MONGODB_QUERY_TEXT_MAX_LENGTH`.
58+
7. Create a new `MongoClient`.
59+
8. Perform the same database operation.
60+
9. Assert that the emitted tracing span does not include the `db.query.text` attribute.

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
{
2+
"description": "operation aggregate",
3+
"schemaVersion": "1.27",
4+
"createEntities": [
5+
{
6+
"client": {
7+
"id": "client0",
8+
"useMultipleMongoses": false,
9+
"observeTracingMessages": {
10+
"enableCommandPayload": true
11+
}
12+
}
13+
},
14+
{
15+
"database": {
16+
"id": "database0",
17+
"client": "client0",
18+
"databaseName": "operation-aggregate"
19+
}
20+
},
21+
{
22+
"collection": {
23+
"id": "collection0",
24+
"database": "database0",
25+
"collectionName": "test"
26+
}
27+
}
28+
],
29+
"tests": [
30+
{
31+
"description": "aggregation",
32+
"operations": [
33+
{
34+
"name": "aggregate",
35+
"object": "collection0",
36+
"arguments": {
37+
"pipeline": [
38+
{
39+
"$match": {
40+
"_id": 1
41+
}
42+
}
43+
]
44+
}
45+
}
46+
],
47+
"expectTracingMessages": [
48+
{
49+
"client": "client0",
50+
"ignoreExtraSpans": false,
51+
"spans": [
52+
{
53+
"name": "aggregate operation-aggregate.test",
54+
"attributes": {
55+
"db.system": "mongodb",
56+
"db.namespace": "operation-aggregate",
57+
"db.collection.name": "test",
58+
"db.operation.name": "aggregate",
59+
"db.operation.summary": "aggregate operation-aggregate.test"
60+
},
61+
"nested": [
62+
{
63+
"name": "aggregate",
64+
"attributes": {
65+
"db.system": "mongodb",
66+
"db.namespace": "operation-aggregate",
67+
"db.collection.name": "test",
68+
"db.command.name": "aggregate",
69+
"network.transport": "tcp",
70+
"db.mongodb.cursor_id": {
71+
"$$exists": false
72+
},
73+
"db.response.status_code": {
74+
"$$exists": false
75+
},
76+
"exception.message": {
77+
"$$exists": false
78+
},
79+
"exception.type": {
80+
"$$exists": false
81+
},
82+
"exception.stacktrace": {
83+
"$$exists": false
84+
},
85+
"server.address": {
86+
"$$type": "string"
87+
},
88+
"server.port": {
89+
"$$type": [
90+
"int",
91+
"long"
92+
]
93+
},
94+
"db.query.summary": "aggregate operation-aggregate.test",
95+
"db.query.text": {
96+
"$$matchAsDocument": {
97+
"$$matchAsRoot": {
98+
"aggregate": "test",
99+
"pipeline": [
100+
{
101+
"$match": {
102+
"_id": 1
103+
}
104+
}
105+
]
106+
}
107+
}
108+
},
109+
"db.mongodb.server_connection_id": {
110+
"$$type": [
111+
"int",
112+
"long"
113+
]
114+
},
115+
"db.mongodb.driver_connection_id": {
116+
"$$type": [
117+
"int",
118+
"long"
119+
]
120+
}
121+
}
122+
}
123+
]
124+
}
125+
]
126+
}
127+
]
128+
}
129+
]
130+
}

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
description: operation aggregate
2+
schemaVersion: '1.27'
3+
createEntities:
4+
- client:
5+
id: &client0 client0
6+
useMultipleMongoses: false
7+
observeTracingMessages:
8+
enableCommandPayload: true
9+
- database:
10+
id: &database0 database0
11+
client: *client0
12+
databaseName: operation-aggregate
13+
- collection:
14+
id: &collection0 collection0
15+
database: *database0
16+
collectionName: &collectionName0 test
17+
18+
tests:
19+
- description: aggregation
20+
operations:
21+
- name: aggregate
22+
object: *collection0
23+
arguments:
24+
pipeline: &pipeline0
25+
- $match: { _id: 1 }
26+
27+
expectTracingMessages:
28+
- client: *client0
29+
ignoreExtraSpans: false
30+
spans:
31+
- name: aggregate operation-aggregate.test
32+
attributes:
33+
db.system: mongodb
34+
db.namespace: operation-aggregate
35+
db.collection.name: test
36+
db.operation.name: aggregate
37+
db.operation.summary: aggregate operation-aggregate.test
38+
nested:
39+
- name: aggregate
40+
attributes:
41+
db.system: mongodb
42+
db.namespace: operation-aggregate
43+
db.collection.name: *collectionName0
44+
db.command.name: aggregate
45+
network.transport: tcp
46+
db.mongodb.cursor_id: { $$exists: false }
47+
db.response.status_code: { $$exists: false }
48+
exception.message: { $$exists: false }
49+
exception.type: { $$exists: false }
50+
exception.stacktrace: { $$exists: false }
51+
server.address: { $$type: string }
52+
server.port: { $$type: [int, long] }
53+
db.query.summary: aggregate operation-aggregate.test
54+
db.query.text:
55+
$$matchAsDocument:
56+
$$matchAsRoot:
57+
aggregate: test
58+
pipeline: *pipeline0
59+
db.mongodb.server_connection_id:
60+
$$type: [ int, long ]
61+
db.mongodb.driver_connection_id:
62+
$$type: [ int, long ]

0 commit comments

Comments
 (0)