From d9b434db87abec375df46864d4fedb2297bc80ec Mon Sep 17 00:00:00 2001 From: Kevin Albertson Date: Fri, 24 Jan 2025 15:48:47 -0500 Subject: [PATCH] DRIVERS-3089 document durationMS in logs may be Int32/Int64/Double (#1746) --- .../command-logging-and-monitoring.md | 22 ++++++------ .../connection-monitoring-and-pooling.md | 34 ++++++++++--------- ...y-and-monitoring-logging-and-monitoring.md | 26 +++++++------- 3 files changed, 44 insertions(+), 38 deletions(-) diff --git a/source/command-logging-and-monitoring/command-logging-and-monitoring.md b/source/command-logging-and-monitoring/command-logging-and-monitoring.md index b9938166e1..5e01fc5f3f 100644 --- a/source/command-logging-and-monitoring/command-logging-and-monitoring.md +++ b/source/command-logging-and-monitoring/command-logging-and-monitoring.md @@ -397,11 +397,11 @@ placeholders as appropriate: In addition to the common fields, command succeeded messages MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | String | "Command succeeded" | -| 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. | -| 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. | +| Key | Suggested Type | Value | +| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| message | String | "Command succeeded" | +| 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. | +| 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. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -415,11 +415,11 @@ placeholders as appropriate: In addition to the common fields, command failed messages MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ---------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | String | "Command failed" | -| 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. | -| 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. | +| Key | Suggested Type | Value | +| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| message | String | "Command failed" | +| 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. | +| 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. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -444,6 +444,8 @@ penalties, particularly when event listeners are introduced. ## Changelog +- 2025-01-22: Clarify durationMS in logs may be Int32/Int64/Double. + - 2024-09-11: Migrated from reStructuredText to Markdown. - 2015-09-16: Removed `limit` from find test with options to support 3.2.\ diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md index ea97e844e3..0c56a2538f 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md @@ -1105,11 +1105,11 @@ placeholders as appropriate: In addition to the common fields defined above, this message MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ------------------ | -------------- | ----------------------------------------------------------------------------------- | -| message | String | "Connection ready" | -| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). | -| durationMS | Int64 | `ConnectionReadyEvent.duration` converted to milliseconds. | +| Key | Suggested Type | Value | +| ------------------ | ------------------ | ----------------------------------------------------------------------------------- | +| message | String | "Connection ready" | +| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). | +| durationMS | Int32/Int64/Double | `ConnectionReadyEvent.duration` converted to milliseconds. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -1151,12 +1151,12 @@ placeholders as appropriate: In addition to the common fields defined above, this message MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| message | String | "Connection checkout failed" | -| reason | String | A string describing the reason checkout. The following strings MUST be used for each possible reason as defined in [Events](#events) above:
- Timeout: "Wait queue timeout elapsed without a connection becoming available"
- ConnectionError: "An error occurred while trying to establish a new connection"
- Pool closed: "Connection pool was closed" | -| 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. | -| durationMS | Int64 | `ConnectionCheckOutFailedEvent.duration` converted to milliseconds. | +| Key | Suggested Type | Value | +| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| message | String | "Connection checkout failed" | +| reason | String | A string describing the reason checkout. The following strings MUST be used for each possible reason as defined in [Events](#events) above:
- Timeout: "Wait queue timeout elapsed without a connection becoming available"
- ConnectionError: "An error occurred while trying to establish a new connection"
- Pool closed: "Connection pool was closed" | +| 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. | +| durationMS | Int32/Int64/Double | `ConnectionCheckOutFailedEvent.duration` converted to milliseconds. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -1168,11 +1168,11 @@ placeholders as appropriate: In addition to the common fields defined above, this message MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ------------------ | -------------- | ----------------------------------------------------------------------------------- | -| message | String | "Connection checked out" | -| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). | -| durationMS | Int64 | `ConnectionCheckedOutEvent.duration` converted to milliseconds. | +| Key | Suggested Type | Value | +| ------------------ | ------------------ | ----------------------------------------------------------------------------------- | +| message | String | "Connection checked out" | +| driverConnectionId | Int64 | The driver-generated ID for the connection as defined in [Connection](#connection). | +| durationMS | Int32/Int64/Double | `ConnectionCheckedOutEvent.duration` converted to milliseconds. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -1375,6 +1375,8 @@ to close and remove from its pool a [Connection](#connection) which has unread e ## Changelog +- 2025-01-22: Clarify durationMS in logs may be Int32/Int64/Double. + - 2024-11-27: Relaxed the WaitQueue fairness requirement. - 2024-11-01: Fixed race condition in pool-checkout-returned-connection-maxConnecting.yml test. diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md index a7f9cdf145..c59d6fddb0 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md @@ -517,12 +517,12 @@ This message MUST be published under the same circumstances as a `ServerHeartbea In addition to the relevant common fields, these messages MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | String | "Server heartbeat succeeded" | -| awaited | Boolean | Whether this log message is for an awaitable hello or legacy "hello". | -| durationMS | Int | The execution time for the heartbeat in milliseconds. See `ServerHeartbeatSucceededEvent` in [Events API](#events-api) for details on calculating this value. | -| reply | String | Relaxed extended JSON representation of the reply to the heartbeat command. | +| Key | Suggested Type | Value | +| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| message | String | "Server heartbeat succeeded" | +| awaited | Boolean | Whether this log message is for an awaitable hello or legacy "hello". | +| durationMS | Int32/Int64/Double | The execution time for the heartbeat in milliseconds. See `ServerHeartbeatSucceededEvent` in [Events API](#events-api) for details on calculating this value. | +| reply | String | Relaxed extended JSON representation of the reply to the heartbeat command. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -538,12 +538,12 @@ This message MUST be published under the same circumstances as a `ServerHeartbea In addition to the relevant common fields, these messages MUST contain the following key-value pairs: -| Key | Suggested Type | Value | -| ---------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | String | "Server heartbeat failed" | -| awaited | Boolean | Whether this log message is for an awaitable hello or legacy "hello". | -| durationMS | Int | The execution time for the heartbeat in milliseconds. See `ServerHeartbeatFailedEvent` in [Events API](#events-api) for details on calculating this value. | -| 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. | +| Key | Suggested Type | Value | +| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| message | String | "Server heartbeat failed" | +| awaited | Boolean | Whether this log message is for an awaitable hello or legacy "hello". | +| durationMS | Int32/Int64/Double | The execution time for the heartbeat in milliseconds. See `ServerHeartbeatFailedEvent` in [Events API](#events-api) for details on calculating this value. | +| 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. | The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate: @@ -558,6 +558,8 @@ See the [README](tests/monitoring/README.md). ## Changelog +- 2025-01-22: Clarify durationMS in logs may be Int32/Int64/Double. + - 2024-05-02: Migrated from reStructuredText to Markdown. - 2024-03-29: Updated to clarify expected initial value of TopologyDescriptionChangedEvent's previousDescription field