Skip to content

Commit

Permalink
DRIVERS-1204 add general spec, unified format changes, and command lo…
Browse files Browse the repository at this point in the history 
…gging
  • Loading branch information
@kmahar
kmahar committed Sep 9, 2022
1 parent cab0e8a commit 0fb43c7
Show file tree
Hide file tree
Showing 90 changed files with 4,732 additions and 80 deletions.
293 changes: 236 additions & 57 deletions ...command-monitoring/command-monitoring.rst → ...toring/command-logging-and-monitoring.rst
View file

Large diffs are not rendered by default.

53 changes: 53 additions & 0 deletions source/command-logging-and-monitoring/tests/README.rst
View file
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 source/command-logging-and-monitoring/tests/logging/unified/command.json
View file
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 source/command-logging-and-monitoring/tests/logging/unified/command.yml
View file
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 }

0 comments on commit 0fb43c7

Please sign in to comment.