-
Notifications
You must be signed in to change notification settings - Fork 235
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
DRIVERS-1204 add general spec, unified format changes, and command lo…
…gging
- Loading branch information
Showing
90 changed files
with
4,732 additions
and
80 deletions.
There are no files selected for viewing
293 changes: 236 additions & 57 deletions
293
...command-monitoring/command-monitoring.rst → ...toring/command-logging-and-monitoring.rst
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
.. role:: javascript(code) | ||
:language: javascript | ||
|
||
============================== | ||
Command Logging and Monitoring | ||
============================== | ||
|
||
.. contents:: | ||
|
||
-------- | ||
|
||
Testing | ||
======= | ||
|
||
Automated Tests | ||
^^^^^^^^^^^^^^^ | ||
There are tests in the `Unified Test Format <../../unified-test-format/unified-test-format.rst>`__ for both logging and | ||
monitoring in `/logging/unified </logging/unified>`_ and `/monitoring/unified </monitoring/unified>`_, respectively. | ||
|
||
|
||
Prose Tests | ||
~~~~~~~~~~~ | ||
Drivers MUST implement the following logging prose tests. These tests require the ability to capture log message data in a | ||
structured form as described in the | ||
`Unified Test Format specification <../../unified-test-format/unified-test-format.rst#expectedLogMessage>`__. | ||
|
||
*Test 1: Default truncation limit* | ||
|
||
1. Configure logging with a minimum severity level of "debug" for the "command" component. Do not explicitly configure the max document length. | ||
2. Construct an array ``docs`` containing the document ``{"x" : "y"}`` repeated 100 times. | ||
3. Insert ``docs`` to a collection via ``insertMany``. | ||
4. Inspect the resulting "command started" log message and assert that the "command" value is a string of length 1000. | ||
5. Inspect the resulting "command succeeded" log message and assert that the "reply" value is a string of length <= 1000. | ||
6. Run ``find()`` on the collection where the document was inserted. | ||
7. Inspect the resulting "command succeeded" log message and assert that the reply is a string of length 1000. | ||
|
||
*Test 2: Explicitly configured truncation limit* | ||
|
||
1. Configure logging with a minimum severity level of "debug" for the "command" component. Set the max document length to 5 of (your driver's unit of choice for truncation). | ||
2. Run the command ``{"hello": true}```. | ||
3. Inspect the resulting "command started" log message and assert that the "command" value is a string of length 5. | ||
4. Inspect the resulting "command succeeded" log message and assert that the "reply" value is a string of length 5. | ||
5. If the driver attaches raw server responses to failures and can access these via log messages to assert on, run the command | ||
``{"notARealCommand": true}``. Inspect the resulting "command failed" log message and confirm that the server error is | ||
a string of length 5. | ||
|
||
*Test 3: Truncation with multi-byte codepoints* | ||
|
||
A specific test case is not provided here due to the allowed variations in truncation logic as well as varying extended JSON whitespace usage. | ||
Drivers MUST write language-specific tests that confirm truncation of commands, replies, and (if applicable) server responses included in error | ||
messages work as expected when the data being truncated includes multi-byte Unicode codepoints. | ||
If the driver uses bytes as the unit for max document length, there also MUST be tests confirming that cases where the max byte length falls in | ||
the middle of a multi-byte codepoint are handled gracefully. |
193 changes: 193 additions & 0 deletions
193
source/command-logging-and-monitoring/tests/logging/unified/command.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,193 @@ | ||
{ | ||
"description": "command-logging", | ||
"schemaVersion": "1.11", | ||
"createEntities": [ | ||
{ | ||
"client": { | ||
"id": "client", | ||
"observeLogMessages": { | ||
"command": "debug" | ||
} | ||
} | ||
}, | ||
{ | ||
"database": { | ||
"id": "database", | ||
"client": "client", | ||
"databaseName": "logging-tests" | ||
} | ||
}, | ||
{ | ||
"collection": { | ||
"id": "collection", | ||
"database": "database", | ||
"collectionName": "logging-tests-collection" | ||
} | ||
} | ||
], | ||
"initialData": [ | ||
{ | ||
"collectionName": "logging-tests-collection", | ||
"databaseName": "logging-tests", | ||
"documents": [ | ||
{ | ||
"_id": 1, | ||
"x": 11 | ||
} | ||
] | ||
} | ||
], | ||
"tests": [ | ||
{ | ||
"description": "A successful command", | ||
"operations": [ | ||
{ | ||
"name": "runCommand", | ||
"object": "database", | ||
"arguments": { | ||
"command": { | ||
"ping": 1 | ||
}, | ||
"commandName": "ping" | ||
} | ||
} | ||
], | ||
"expectLogMessages": [ | ||
{ | ||
"client": "client", | ||
"messages": [ | ||
{ | ||
"level": "debug", | ||
"component": "command", | ||
"data": { | ||
"message": "Command started", | ||
"databaseName": "logging-tests", | ||
"commandName": "ping", | ||
"command": { | ||
"$$matchAsDocument": { | ||
"$$matchAsRoot": { | ||
"ping": 1, | ||
"$db": "logging-tests" | ||
} | ||
} | ||
}, | ||
"requestId": { | ||
"$$exists": true | ||
}, | ||
"driverConnectionId": { | ||
"$$exists": true | ||
}, | ||
"serverHost": { | ||
"$$exists": true | ||
}, | ||
"serverPort": { | ||
"$$exists": true | ||
} | ||
} | ||
}, | ||
{ | ||
"level": "debug", | ||
"component": "command", | ||
"data": { | ||
"message": "Command succeeded", | ||
"commandName": "ping", | ||
"reply": { | ||
"$$type": "string" | ||
}, | ||
"requestId": { | ||
"$$exists": true | ||
}, | ||
"driverConnectionId": { | ||
"$$exists": true | ||
}, | ||
"serverHost": { | ||
"$$exists": true | ||
}, | ||
"serverPort": { | ||
"$$exists": true | ||
}, | ||
"durationMS": { | ||
"$$exists": true | ||
} | ||
} | ||
} | ||
] | ||
} | ||
] | ||
}, | ||
{ | ||
"description": "A failed command", | ||
"operations": [ | ||
{ | ||
"name": "find", | ||
"object": "collection", | ||
"arguments": { | ||
"filter": { | ||
"$or": true | ||
} | ||
}, | ||
"expectError": { | ||
"isClientError": false | ||
} | ||
} | ||
], | ||
"expectLogMessages": [ | ||
{ | ||
"client": "client", | ||
"messages": [ | ||
{ | ||
"level": "debug", | ||
"component": "command", | ||
"data": { | ||
"message": "Command started", | ||
"databaseName": "logging-tests", | ||
"commandName": "find", | ||
"command": { | ||
"$$type": "string" | ||
}, | ||
"requestId": { | ||
"$$exists": true | ||
}, | ||
"driverConnectionId": { | ||
"$$exists": true | ||
}, | ||
"serverHost": { | ||
"$$exists": true | ||
}, | ||
"serverPort": { | ||
"$$exists": true | ||
} | ||
} | ||
}, | ||
{ | ||
"level": "debug", | ||
"component": "command", | ||
"data": { | ||
"message": "Command failed", | ||
"commandName": "find", | ||
"failure": { | ||
"$$exists": true | ||
}, | ||
"requestId": { | ||
"$$exists": true | ||
}, | ||
"driverConnectionId": { | ||
"$$exists": true | ||
}, | ||
"serverHost": { | ||
"$$exists": true | ||
}, | ||
"serverPort": { | ||
"$$exists": true | ||
}, | ||
"durationMS": { | ||
"$$exists": true | ||
} | ||
} | ||
} | ||
] | ||
} | ||
] | ||
} | ||
] | ||
} |
97 changes: 97 additions & 0 deletions
97
source/command-logging-and-monitoring/tests/logging/unified/command.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,97 @@ | ||
description: "command-logging" | ||
|
||
schemaVersion: "1.11" | ||
|
||
createEntities: | ||
- client: | ||
id: &client client | ||
observeLogMessages: | ||
command: debug | ||
- database: | ||
id: &database database | ||
client: *client | ||
databaseName: &databaseName logging-tests | ||
- collection: | ||
id: &collection collection | ||
database: *database | ||
collectionName: &collectionName logging-tests-collection | ||
|
||
initialData: | ||
- collectionName: *collectionName | ||
databaseName: *databaseName | ||
documents: | ||
- { _id: 1, x: 11 } | ||
|
||
tests: | ||
- description: "A successful command" | ||
operations: | ||
- name: runCommand | ||
object: *database | ||
arguments: | ||
command: { ping: 1 } | ||
commandName: &commandName ping | ||
expectLogMessages: | ||
- client: *client | ||
messages: | ||
- level: debug | ||
component: command | ||
data: | ||
message: "Command started" | ||
databaseName: *databaseName | ||
commandName: *commandName | ||
command: | ||
$$matchAsDocument: | ||
$$matchAsRoot: | ||
ping: 1 | ||
$db: *databaseName | ||
requestId: { $$exists: true } | ||
driverConnectionId: { $$exists: true } | ||
serverHost: { $$exists: true } | ||
serverPort: { $$exists: true } | ||
|
||
- level: debug | ||
component: command | ||
data: | ||
message: "Command succeeded" | ||
commandName: *commandName | ||
reply: { $$type: string } | ||
requestId: { $$exists: true } | ||
driverConnectionId: { $$exists: true } | ||
serverHost: { $$exists: true } | ||
serverPort: { $$exists: true } | ||
durationMS: { $$exists: true } | ||
|
||
- description: "A failed command" | ||
operations: | ||
- name: &commandName find | ||
object: *collection | ||
arguments: | ||
filter: { $or: true } | ||
expectError: | ||
isClientError: false | ||
expectLogMessages: | ||
- client: *client | ||
messages: | ||
- level: debug | ||
component: command | ||
data: | ||
message: "Command started" | ||
databaseName: *databaseName | ||
commandName: *commandName | ||
command: { $$type: string } | ||
requestId: { $$exists: true } | ||
driverConnectionId: { $$exists: true } | ||
serverHost: { $$exists: true } | ||
serverPort: { $$exists: true } | ||
|
||
- level: debug | ||
component: command | ||
data: | ||
message: "Command failed" | ||
commandName: *commandName | ||
failure: { $$exists: true } | ||
requestId: { $$exists: true } | ||
driverConnectionId: { $$exists: true } | ||
serverHost: { $$exists: true } | ||
serverPort: { $$exists: true } | ||
durationMS: { $$exists: true } |
Oops, something went wrong.