DOCSP-47935-log-retention-duration (#384)

* DOCSP-47935-log-retention-duration

* add duration page to toc

* WIP

* edit

* edit

* wording

* edit

* edit

* edit

* wording

* retry build

* wording

Author: jeff-allen-mongo

snooty.toml

@@ -13,7 +13,8 @@ toc_landing_pages = ["/install",
                      "/configure-mongosh",
                      "/reference/configure-shell-settings",
                      "/reference/ejson",
-                     "/logs"
+                     "/logs",
+                     "/logs/retention"
                     ]
 
 [constants]

source/includes/list-table-shell-properties.rst

@@ -71,6 +71,15 @@
      - Directory where MongoDB Shell writes log files. Specify an
        absolute filepath. See :ref:`mongosh-log-location`.
 
+   * - ``logRetentionDays``
+     - integer or Infinity
+     - 30
+     - Number of days that |mdb-shell| log files are retained. If this
+       value is set to ``Infinity``, log files are not deleted based on
+       age. To prevent log storage from growing too large, always
+       specify at least one log retention criterion. See
+       :ref:`mongosh-logs-retention`.
+
    * - ``redactHistory``
      - string
      - ``remove``

source/includes/log-retention-multiple-criteria.rst

@@ -0,0 +1,4 @@
+You can specify multiple criteria for log retention. For example, you
+can specify a maximum duration for log files of 60 days and a maximum
+log storage size of 2GB. Logs are deleted when any retention criterion
+is met, starting with the oldest logs.

source/logs.txt

@@ -63,13 +63,15 @@ history:
 Log Retention
 -------------
 
-``mongosh`` retains up to 100 log files for 30 days. ``mongosh``
-automatically deletes log files older than 30 days.
+By default, ``mongosh`` retains up to 100 log files for 30 days.
+``mongosh`` automatically deletes log files older than 30 days. To
+customize log file retention, see :ref:`mongosh-logs-retention`.
 
 .. toctree::
    :titlesonly:
 
-   Disable Logging </logs/disable>
-   Specify Log Location <logs/location> 
-   Write Custom Log Entries <logs/custom-entries> 
+   Specify Log Location </logs/location> 
+   Write Custom Log Entries </logs/custom-entries>
+   Retention </logs/retention>
    Enable Log Compression </logs/compression>
+   Disable Logging </logs/disable>

source/logs/retention.txt

@@ -0,0 +1,32 @@
+.. _mongosh-logs-retention:
+
+=============
+Log Retention
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can customize how |mdb-shell| logs are retained. By default, the
+system retains 100 log files for 30 days. You can choose to retain logs
+based on a combination of time, storage size, and number of log files.
+
+Get Started
+-----------
+
+To customize log retention, see these pages:
+
+- :ref:`mongosh-log-file-duration`
+
+Details
+-------
+
+.. include:: /includes/log-retention-multiple-criteria.rst
+
+.. toctree::
+   :titlesonly:
+
+   Duration </logs/retention/duration>

source/logs/retention/duration.txt

@@ -0,0 +1,72 @@
+.. _mongosh-log-file-duration:
+
+=============================
+Modify Log Retention Duration
+=============================
+
+You can modify how long |mdb-shell| log files are retained. A log
+cleanup process automatically deletes log files older than the specified
+retention period. By default, log files are retained for 30 days.
+
+About this Task
+---------------
+
+.. include:: /includes/log-retention-multiple-criteria.rst
+
+Before you Begin
+----------------
+
+To check the current log retention duration, run the following command:
+
+.. code-block:: javascript
+
+   config.get("logRetentionDays")
+
+Steps
+-----
+
+To modify how long log files are retained, set the ``logRetentionDays``
+configuration option. You can set configuration options in the
+configuration API or a configuration file.
+
+Modify Log Duration with the Configuration API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following command uses the config API to set log retention to 60
+days:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: javascript
+
+      config.set("logRetentionDays", 60)
+
+   .. output::
+      :language: javascript
+
+      Setting "logRetentionDays" has been changed
+
+Modify Log Duration with a Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following configuration file sets log retention to 60
+days:
+
+.. code-block:: yaml
+
+   mongosh:
+     logRetentionDays: 60
+
+Disable Duration-Based Log Cleanup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To instruct |mdb-shell| to not delete logs based on file age, set
+``logRetentionDays`` to ``Infinity``. You can perform this action
+through the config API or configuration file.
+
+.. important::
+
+   To prevent log storage from growing too large, always specify at
+   least one log retention criterion.