Skip to content

Commit d9b434d

Browse files
kevinAlbskevinAlbs
authored
DRIVERS-3089 document durationMS in logs may be Int32/Int64/Double (#1746)
1 parent 60fe09f commit d9b434d

File tree

3 files changed

+44
-38
lines changed

3 files changed

+44
-38
lines changed

‎source/command-logging-and-monitoring/command-logging-and-monitoring.md

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -397,11 +397,11 @@ placeholders as appropriate:
397397

398398
In addition to the common fields, command succeeded messages MUST contain the following key-value pairs:
399399

400-
| Key | Suggested Type | Value |
401-
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
402-
| message | String | "Command succeeded" |
403-
| durationMS | Int | The execution time for the command in milliseconds. The calculated value MUST be the time to send the message and receive the reply from the server and MAY include BSON serialization and/or deserialization. |
404-
| reply | String | Relaxed extJSON representation of the reply. This document MUST be truncated appropriately according to rules defined in the [logging specification](../logging/logging.md#configurable-max-document-length), and MUST be replaced with an empty document "{ }" if the command is considered sensitive. |
400+
| Key | Suggested Type | Value |
401+
| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
402+
| message | String | "Command succeeded" |
403+
| durationMS | Int32/Int64/Double | The execution time for the command in milliseconds. The calculated value MUST be the time to send the message and receive the reply from the server and MAY include BSON serialization and/or deserialization. |
404+
| reply | String | Relaxed extJSON representation of the reply. This document MUST be truncated appropriately according to rules defined in the [logging specification](../logging/logging.md#configurable-max-document-length), and MUST be replaced with an empty document "{ }" if the command is considered sensitive. |
405405

406406
The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in
407407
placeholders as appropriate:
@@ -415,11 +415,11 @@ placeholders as appropriate:
415415

416416
In addition to the common fields, command failed messages MUST contain the following key-value pairs:
417417

418-
| Key | Suggested Type | Value |
419-
| ---------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
420-
| message | String | "Command failed" |
421-
| durationMS | Int | The execution time for the command in milliseconds. The calculated value MUST be the time to send the message and receive the reply from the server and MAY include BSON serialization and/or deserialization. |
422-
| failure | Flexible | The error. The type and format of this value is flexible; see the [logging specification](../logging/logging.md#representing-errors-in-log-messages) for details on representing errors in log messages. If the command is considered sensitive, the error MUST be redacted and replaced with a language-appropriate alternative for a redacted error, e.g. an empty string, empty document, or null. |
418+
| Key | Suggested Type | Value |
419+
| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
420+
| message | String | "Command failed" |
421+
| durationMS | Int32/Int64/Double | The execution time for the command in milliseconds. The calculated value MUST be the time to send the message and receive the reply from the server and MAY include BSON serialization and/or deserialization. |
422+
| failure | Flexible | The error. The type and format of this value is flexible; see the [logging specification](../logging/logging.md#representing-errors-in-log-messages) for details on representing errors in log messages. If the command is considered sensitive, the error MUST be redacted and replaced with a language-appropriate alternative for a redacted error, e.g. an empty string, empty document, or null. |
423423

424424
The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in
425425
placeholders as appropriate:
@@ -444,6 +444,8 @@ penalties, particularly when event listeners are introduced.
444444

445445
## Changelog
446446

447+
- 2025-01-22: Clarify durationMS in logs may be Int32/Int64/Double.
448+
447449
- 2024-09-11: Migrated from reStructuredText to Markdown.
448450

449451
- 2015-09-16: Removed `limit` from find test with options to support 3.2.\

‎source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1105,11 +1105,11 @@ placeholders as appropriate:
11051105

11061106
In addition to the common fields defined above, this message MUST contain the following key-value pairs:
11071107

1108-
| Key | Suggested Type | Value |
1109-
| ------------------ | -------------- | ----------------------------------------------------------------------------------- |
1110-
| message | String | "Connection ready" |
1111-
| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). |
1112-
| durationMS | Int64 | `ConnectionReadyEvent.duration` converted to milliseconds. |
1108+
| Key | Suggested Type | Value |
1109+
| ------------------ | ------------------ | ----------------------------------------------------------------------------------- |
1110+
| message | String | "Connection ready" |
1111+
| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). |
1112+
| durationMS | Int32/Int64/Double | `ConnectionReadyEvent.duration` converted to milliseconds. |
11131113

11141114
The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in
11151115
placeholders as appropriate:
@@ -1151,12 +1151,12 @@ placeholders as appropriate:
11511151

11521152
In addition to the common fields defined above, this message MUST contain the following key-value pairs:
11531153

1154-
| Key | Suggested Type | Value |
1155-
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1156-
| message | String | "Connection checkout failed" |
1157-
| reason | String | A string describing the reason checkout. The following strings MUST be used for each possible reason as defined in [Events](#events) above:<br>- Timeout: "Wait queue timeout elapsed without a connection becoming available"<br>- ConnectionError: "An error occurred while trying to establish a new connection"<br>- Pool closed: "Connection pool was closed" |
1158-
| error | Flexible | If `reason` is `ConnectionError`, the associated error. The type and format of this value is flexible; see the [logging specification](../logging/logging.md#representing-errors-in-log-messages) for details on representing errors in log messages. |
1159-
| durationMS | Int64 | `ConnectionCheckOutFailedEvent.duration` converted to milliseconds. |
1154+
| Key | Suggested Type | Value |
1155+
| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1156+
| message | String | "Connection checkout failed" |
1157+
| reason | String | A string describing the reason checkout. The following strings MUST be used for each possible reason as defined in [Events](#events) above:<br>- Timeout: "Wait queue timeout elapsed without a connection becoming available"<br>- ConnectionError: "An error occurred while trying to establish a new connection"<br>- Pool closed: "Connection pool was closed" |
1158+
| error | Flexible | If `reason` is `ConnectionError`, the associated error. The type and format of this value is flexible; see the [logging specification](../logging/logging.md#representing-errors-in-log-messages) for details on representing errors in log messages. |
1159+
| durationMS | Int32/Int64/Double | `ConnectionCheckOutFailedEvent.duration` converted to milliseconds. |
11601160

11611161
The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in
11621162
placeholders as appropriate:
@@ -1168,11 +1168,11 @@ placeholders as appropriate:
11681168

11691169
In addition to the common fields defined above, this message MUST contain the following key-value pairs:
11701170

1171-
| Key | Suggested Type | Value |
1172-
| ------------------ | -------------- | ----------------------------------------------------------------------------------- |
1173-
| message | String | "Connection checked out" |
1174-
| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). |
1175-
| durationMS | Int64 | `ConnectionCheckedOutEvent.duration` converted to milliseconds. |
1171+
| Key | Suggested Type | Value |
1172+
| ------------------ | ------------------ | ----------------------------------------------------------------------------------- |
1173+
| message | String | "Connection checked out" |
1174+
| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). |
1175+
| durationMS | Int32/Int64/Double | `ConnectionCheckedOutEvent.duration` converted to milliseconds. |
11761176

11771177
The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in
11781178
placeholders as appropriate:
@@ -1375,6 +1375,8 @@ to close and remove from its pool a [Connection](#connection) which has unread e
13751375

13761376
## Changelog
13771377

1378+
- 2025-01-22: Clarify durationMS in logs may be Int32/Int64/Double.
1379+
13781380
- 2024-11-27: Relaxed the WaitQueue fairness requirement.
13791381

13801382
- 2024-11-01: Fixed race condition in pool-checkout-returned-connection-maxConnecting.yml test.

0 commit comments

Comments
 (0)