DOCSP-46885-custom-log-entries (#378)

* init

* initial page

* make logs a landing page

* first draft

* wording

* add find command to results

* review feedback

* add programmatic example

* change highlighting

* change highlighting

Author: jeff-allen-mongo

snooty.toml

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

source/logs.txt

@@ -60,3 +60,8 @@ Log Retention
 
 ``mongosh`` retains up to 100 log files for 30 days. ``mongosh``
 automatically deletes log files older than 30 days.
+
+.. toctree::
+   :titlesonly:
+
+   Write Custom Log Entries <logs/custom-entries> 

source/logs/custom-entries.txt

@@ -0,0 +1,133 @@
+.. _mongosh-custom-log-entries:
+
+========================
+Write Custom Log Entries
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can write custom :ref:`log entries <mdb-shell-logs>` from your
+:ref:`MongoDB Shell scripts <mdb-shell-write-scripts>`. Custom log
+entries help with debugging, error handling, and alert you when the
+script performs specific functions.
+
+About this Task
+---------------
+
+MongoDB Shell supports the following methods for custom log entries:
+
+- ``log.debug()``
+- ``log.error()``
+- ``log.fatal()``
+- ``log.info()``
+- ``log.warn()``
+
+Steps
+-----
+
+.. procedure::
+
+   .. step:: Create a script that writes a custom log entry
+
+      The following script inserts documents into the ``movies``
+      collection and writes a custom ``info`` log entry. If the script
+      errors, it writes a custom ``error`` log entry instead.
+
+      .. code-block:: javascript
+         :emphasize-lines: 22,24
+         
+         // connect-and-insert-with-log-entry.js
+                  
+         try {
+            db = connect( 'mongodb://localhost/myDatabase' );
+
+            db.movies.insertMany( [
+               {
+                  title: 'Titanic',
+                  year: 1997,
+                  genres: [ 'Drama', 'Romance' ]
+               },
+               {
+                  title: 'Spirited Away', 
+                  year: 2001,
+                  genres: [ 'Animation', 'Adventure', 'Family' ]
+               },
+               {
+                  title: 'Casablanca',
+                  genres: [ 'Drama', 'Romance', 'War' ]
+               }
+            ] )
+            log.info('InsertData: Inserted 3 movies');
+         } catch (error) {
+            log.error('Insert failed', { error: error.message });
+         }
+
+      Save the script as ``connect-and-insert-with-log-entry.js``.
+
+   .. step:: Run the script
+
+      To run the ``connect-and-insert-with-log-entry.js`` script, use
+      ``mongosh`` to connect to your deployment and run the following
+      command within MongoDB Shell:
+
+      .. code-block:: javascript
+
+         load("connect-and-insert-with-log-entry.js")
+
+      Alternatively, you can run the script programmatically by using
+      the :option:`--file <mongosh --file>` option when you start
+      ``mongosh``:
+      
+      .. code-block:: sh
+
+         mongosh --file connect-and-insert-with-log-entry.js
+
+Results
+-------
+
+The custom log entry appears in the logs for your session:
+
+.. code-block:: javascript
+   :copyable: false
+
+   {"t":{"$date":"2025-02-25T18:04:01.690Z"},"s":"I","c":"MONGOSH-SCRIPTS","id":1000000054,"ctx":"custom-log","msg":"InsertData: Inserted 3 movies"}
+   
+For more information about log sessions and how to retrieve log
+messages, see :ref:`mdb-shell-view-logs`.
+
+To verify that the script inserted the documents, query the ``movies``
+collection:
+
+.. code-block:: javascript
+
+   use myDatabase
+   db.movies.find()
+
+Output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+      {
+         _id: ObjectId('67bde8c2a527c6b1341979f2'),
+         title: 'Titanic',
+         year: 1997,
+         genres: [ 'Drama', 'Romance' ]
+      },
+      {
+         _id: ObjectId('67bde8c2a527c6b1341979f3'),
+         title: 'Spirited Away',
+         year: 2001,
+         genres: [ 'Animation', 'Adventure', 'Family' ]
+      },
+      {
+         _id: ObjectId('67bde8c2a527c6b1341979f4'),
+         title: 'Casablanca',
+         genres: [ 'Drama', 'Romance', 'War' ]
+      }
+   ]