DOCS-415 diaglogging: add warning that log is kept open by mongod

source/administration/configuration.txt

@@ -342,7 +342,7 @@ needed:
   Each additional level ``v`` adds additional verbosity to the
   logging. The ``verbose`` option  is equal to ``v = true``.
 
-- :setting:`diaglog` enables diagnostic logging. Level ``3``
+- :setting:`diaglog` enables :term:`diagnostic logging <diagnostic log>`. Level ``3``
   logs all read and write options.
 
 - :setting:`objcheck` forces :program:`mongod` to validate all
@@ -352,7 +352,7 @@ needed:
   performance.
 
 - :setting:`cpu` forces :program:`mongod` to report the percentage of
-   the last interval spent in :term:`write-lock`. The interval is
-   typically 4 seconds, and each output line in the log includes both
-   the actual interval since the last report and the percentage of
-   time spent in write lock.
+  the last interval spent in :term:`write-lock`. The interval is
+  typically 4 seconds, and each output line in the log includes both
+  the actual interval since the last report and the percentage of
+  time spent in write lock.

source/includes/warning-diaglogging-off.rst

@@ -0,0 +1,8 @@
+
+.. warning::
+
+   Setting the diagnostic level to ``0`` will cause :program:`mongod`
+   to stop writing data to the :term:`diagnostic log` file, however the
+   :program:`mongod` instance will continue to keep the file open.
+   If you want to rename, move, or delete the diagnostic log you must
+   cleanly shut down the :program:`mongod` instance before doing so.

source/reference/configuration-options.txt

@@ -269,10 +269,11 @@ Settings
 
    *Default:* 0
 
-   Creates a very verbose, diagnostic log for troubleshooting and
+   Creates a very verbose, :term:`diagnostic log` for troubleshooting and
    recording various errors. MongoDB writes these log files in the
-   :setting:`dbpath` in a series of files that begin with the string
-   ``diaglog``.
+   :setting:`dbpath` directory in a series of files that begin with the string
+   ``diaglog`` with the time logging was initiated appended as a hex
+   string.
 
    The value of this setting configures the level of
    verbosity. Possible values, and their impact are as follows.
@@ -298,6 +299,8 @@ Settings
 
    :setting:`diaglog` is for internal use and not intended for most
    users.
+
+   .. include:: /includes/warning-diaglogging-off.rst
 
 .. setting:: directoryperdb
 

source/reference/glossary.txt

@@ -866,3 +866,16 @@ Glossary
       results. The optimizer then uses the query plan each time the
       query is run. If a collection changes significantly, the optimizer
       creates a new query plan.
+
+   diagnostic log
+      :program:`mongod` can create a verbose log of operations with
+      the :option:`mongod --diaglog` option or through the
+      :dbcommand:`diagLogging` command.  This log will be created in
+      the directory specified with the :option:`mongod --dbpath` option
+      or the default :file:`/data/db` directory.  The log file will
+      be named :file:`diaglog.{time in hex}`, with the time when
+      logging was initiated appended as a hexadecimal string.
+
+      .. include:: /includes/warning-diaglogging-off.rst
+
+      .. seealso:: :option:`mongod --diaglog`

source/reference/mongod.txt

@@ -189,10 +189,11 @@ Options
 
 .. option:: --diaglog <value>
 
-   Creates a very verbose, diagnostic log for troubleshooting and
+   Creates a very verbose, :term:`diagnostic log` for troubleshooting and
    recording various errors. MongoDB writes these log files in the
-   :setting:`dbpath` in a series of files that begin with the string
-   ``diaglog``.
+   :setting:`dbpath` directory in a series of files that begin with the string
+   ``diaglog`` with the time logging was initiated appended as a hex
+   string.
 
    The specified value configures the level of verbosity. Possible
    values, and their impact are as follows.
@@ -219,6 +220,8 @@ Options
    :option:`--diaglog` is for internal use and not intended for most
    users.
 
+   .. include:: /includes/warning-diaglogging-off.rst
+
 .. option:: --directoryperdb
 
    Alters the storage pattern of the data directory to store each