DRIVERS-2789 Convert Logging Spec to Markdown

fix index generation
mongodb · Mar 21, 2024 · daf4e34 · daf4e34
1 parent dc3fc1c
commit daf4e34
Show file tree

Hide file tree

Showing 12 changed files with 974 additions and 547 deletions.
diff --git a/source/command-logging-and-monitoring/command-logging-and-monitoring.rst b/source/command-logging-and-monitoring/command-logging-and-monitoring.rst
@@ -60,7 +60,7 @@ Publishing & Subscribing
 
 The driver SHOULD publish events in a manner that is standard to the driver's language publish/subscribe patterns and is not strictly mandated in this specification.
 
-Similarly, as described in the `logging specification <../logging/logging.rst#implementation-requirements>`__ the driver SHOULD emit log messages in a manner that is standard for the language.
+Similarly, as described in the `logging specification <../logging/logging.md#implementation-requirements>`__ the driver SHOULD emit log messages in a manner that is standard for the language.
 
 
 Guarantees
@@ -363,7 +363,7 @@ See the `Load Balancer Specification <../load-balancers/load-balancers.md#events
 
 Log Messages
 ------------
-Please refer to the `logging specification <../logging/logging.rst>`__ for details on logging implementations in general, including log levels, log
+Please refer to the `logging specification <../logging/logging.md>`__ for details on logging implementations in general, including log levels, log
 components, and structured versus unstructured logging.
 
 Drivers MUST support logging of command information via the following types of log messages. These messages MUST be logged at ``Debug`` level and use
@@ -451,7 +451,7 @@ In addition to the common fields, command started messages MUST contain the foll
    * - command
      - String
      - Relaxed extJSON representation of the command. This document MUST be truncated appropriately according to rules defined in the 
-       `logging specification <../logging/logging.rst#configurable-max-document-length>`__, and MUST be replaced with an empty document
+       `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:
@@ -484,7 +484,7 @@ In addition to the common fields, command succeeded messages MUST contain the fo
    * - reply
      - String
      - Relaxed extJSON representation of the reply. This document MUST be truncated appropriately according to rules defined in the 
-       `logging specification <../logging/logging.rst#configurable-max-document-length>`__, and MUST be replaced with an empty document
+       `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:
@@ -516,7 +516,7 @@ In addition to the common fields, command failed messages MUST contain the follo
 
    * - failure
      - Flexible
-     - The error. The type and format of this value is flexible; see the `logging specification <../logging/logging.rst#representing-errors-in-log-messages>`__ 
+     - 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.
 

diff --git a/source/command-logging-and-monitoring/tests/README.rst b/source/command-logging-and-monitoring/tests/README.rst
@@ -17,7 +17,7 @@ Automated Tests
 There are tests in the `Unified Test Format <../../unified-test-format/unified-test-format.md>`__ for both logging and
 monitoring in `/logging <./logging>`_ and `/monitoring <./monitoring>`_, respectively. Drivers MUST run the logging
 tests with their max document length setting (as described in the 
-`logging specification <../../logging/logging.rst#configurable-max-document-length>`__) set to a large value e.g. 10,000;
+`logging specification <../../logging/logging.md#configurable-max-document-length>`__) set to a large value e.g. 10,000;
 this is necessary in order for the driver to emit the full server reply (and to allow matching against that reply) on
 certain MongoDB versions and topologies.
 
@@ -29,7 +29,7 @@ structured form as described in the
 
 Note: the following tests mention string "length"; this refers to length in terms of whatever unit the driver has chosen
 to support for specifying max document length as discussed in the 
-`logging specification <../../logging/logging.rst#configurable-max-document-length>`__.
+`logging specification <../../logging/logging.md#configurable-max-document-length>`__.
 
 *Test 1: Default truncation limit*
 

diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md
@@ -998,7 +998,7 @@ interface ConnectionCheckedInEvent {
 
 ### Connection Pool Logging
 
-Please refer to the [logging specification](../logging/logging.rst) for details on logging implementations in general,
+Please refer to the [logging specification](../logging/logging.md) for details on logging implementations in general,
 including log levels, log components, handling of null values in log messages, and structured versus unstructured
 logging.
 
@@ -1123,7 +1123,7 @@ In addition to the common fields defined above, this message MUST contain the fo
 | message            | String         | "Connection closed"                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | driverConnectionId | Int64          | The driver-generated ID for the connection as defined in a [Connection](#connection).                                                                                                                                                                                                                                                                                                                                                       |
 | reason             | String         | A string describing the reason the connection was closed. The following strings MUST be used for each possible reason as defined in [Events](#events) above:<br>- Stale: "Connection became stale because the pool was cleared<br>- Idle: "Connection has been available but unused for longer than the configured max idle time"<br>- Error: "An error occurred while using the connection"<br>- Pool closed: "Connection pool was closed" |
-| error              | Flexible       | If `reason` is `Error`, the associated error.<br>The type and format of this value is flexible; see the [logging specification](../logging/logging.rst#representing-errors-in-log-messages) for details on representing errors in log messages.                                                                                                                                                                                             |
+| error              | Flexible       | If `reason` is `Error`, the associated error.<br>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.                                                                                                                                                                                              |
 
 The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in
 placeholders as appropriate:
@@ -1152,7 +1152,7 @@ In addition to the common fields defined above, this message MUST contain the fo
 | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 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:<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" |
-| error      | Flexible       | If `reason` is `ConnectionError`, the associated error. The type and format of this value is flexible; see the [logging specification](../logging/logging.rst#representing-errors-in-log-messages) for details on representing errors in log messages.                                                                                                             |
+| 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.                                                                                                                                                                                                                                                                                                |
 
 The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in

diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.rst
@@ -1063,7 +1063,7 @@ See the `Load Balancer Specification <../load-balancers/load-balancers.md#events
 
 Connection Pool Logging
 ~~~~~~~~~~~~~~~~~~~~~~~
-Please refer to the `logging specification <../logging/logging.rst>`__ for details on logging implementations in general, including log levels, log
+Please refer to the `logging specification <../logging/logging.md>`__ for details on logging implementations in general, including log levels, log
 components, handling of null values in log messages, and structured versus unstructured logging.
 
 Drivers MUST support logging of connection pool information via the following types of log messages. These messages MUST be logged at ``Debug`` level
@@ -1299,7 +1299,7 @@ In addition to the common fields defined above, this message MUST contain the fo
    * - error
      - Flexible
      - If ``reason`` is ``Error``, the associated error. The type and format of this value is flexible; see the
-       `logging specification <../logging/logging.rst#representing-errors-in-log-messages>`__  for details on representing errors in log messages.
+       `logging specification <../logging/logging.md#representing-errors-in-log-messages>`__  for details on representing errors in log messages.
 
 The unstructured form SHOULD be as follows, using the values defined in the structured format above to fill in placeholders as appropriate:
 
@@ -1353,7 +1353,7 @@ In addition to the common fields defined above, this message MUST contain the fo
    * - error
      - Flexible
      - If ``reason`` is ``ConnectionError``, the associated error. The type and format of this value is flexible; see the
-       `logging specification <../logging/logging.rst#representing-errors-in-log-messages>`__  for details on representing errors in log messages.
+       `logging specification <../logging/logging.md#representing-errors-in-log-messages>`__  for details on representing errors in log messages.
 
    * - durationMS
      - Int64

diff --git a/source/index.md b/source/index.md
@@ -19,6 +19,7 @@
 - [Index Management](index-management/index-management.md)
 - [Initial DNS Seedlist Discovery](initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md)
 - [Load Balancer Support](load-balancers/load-balancers.md)
+- [Logging](logging/logging.md)
 - [MongoDB Driver Performance Benchmarking](benchmarking/benchmarking.md)
 - [Server Selection](server-selection/server-selection.md)
 - [Server Selection Test Plan](server-selection/server-selection-tests.md)