DOCSP-43518: query logging

Author: rustagir

docs/fundamentals/read-operations.txt

@@ -17,7 +17,8 @@ Read Operations
    Retrieve Data </fundamentals/read-operations/retrieve>
    Search Text </fundamentals/read-operations/search-text>
    Modify Query Results </fundamentals/read-operations/modify-results>
-   Set Read Preference </fundamentals/read-operations/read-pref>
+   Read Preference </fundamentals/read-operations/read-pref>
+   Query Logging </fundamentals/read-operations/query-logging>
 
 .. contents:: On this page
    :local:

docs/fundamentals/read-operations/query-logging.txt

@@ -0,0 +1,115 @@
+.. _laravel-query-logging:
+
+====================
+Enable Query Logging
+====================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: monitoring, CRUD, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to enable query logging in
+{+odm-long+}. Query logging can help you debug your queries and monitor
+database interactions.
+
+.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst
+
+Enable Logs On a Connection
+---------------------------
+
+To enable logs on a connection, you can use the ``enableQueryLog()``
+method on the ``DB`` facade. This method enables MongoDB command logging
+on any queries that you perform on the database connection.
+
+After you enable query logging, any queries you perform are stored in
+memory. To retrieve the logs, use one of the following methods:
+
+- ``getQueryLog()``: Returns a log of MongoDB queries
+- ``getRawQueryLog()``: Returns a log of raw MongoDB queries
+
+The following example enables query logging, performs some queries, then
+prints the query log:
+
+.. tabs::
+
+   .. tab:: Query Syntax
+      :tabid: query-syntax
+
+      Use the following syntax to specify the query:
+
+      .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php
+         :language: php
+         :dedent:
+         :start-after: start-query-log
+         :end-before: end-query-log
+         :emphasize-lines: 1, 7
+
+   .. tab:: Controller Method
+      :tabid: controller
+
+      To see the logs in the ``browse_movies`` view, edit the ``show()`` function
+      in the ``MovieController.php`` file to resemble the following code:
+
+      .. io-code-block::
+         :copyable: true
+
+         .. input::
+            :language: php
+
+            class MovieController
+            {
+                public function show()
+                {
+                    DB::connection('mongodb')->enableQueryLog();
+            
+                    Movie::where('title', 'Carrie')->get();
+                    Movie::where('year', '<', 2005)->get();
+                    Movie::where('imdb.rating', '>', 8.5)->get();
+            
+                    $logs = DB::connection('mongodb')->getQueryLog();
+                    foreach ($logs as $log) {
+                        echo json_encode($log, JSON_PRETTY_PRINT);
+                    }
+                }
+            }
+
+         .. output::
+            :language: none
+            :visible: false
+            
+            {
+              "query": "{ \"find\" : \"movies\", \"filter\" : { \"title\" : \"Carrie\" } }",
+              "bindings": [],
+              "time": 29476
+            }
+            {
+              "query": "{ \"find\" : \"movies\", \"filter\" : { \"year\" : { \"$lt\" : { \"$numberInt\" : \"2005\" } } } }",
+              "bindings": [],
+              "time": 29861
+            }
+            {
+              "query": "{ \"find\" : \"movies\", \"filter\" : { \"imdb.rating\" : { \"$gt\" : { \"$numberDouble\" : \"8.5\" } } } }",
+              "bindings": [],
+              "time": 27251
+            }
+
+Additional Information
+----------------------
+
+To learn more about connecting to MongoDB, see the
+:ref:`laravel-connect-to-mongodb`.
+
+To learn how to retrieve data based on filter criteria, see the
+:ref:`laravel-fundamentals-read-retrieve` guide.

docs/includes/fundamentals/read-operations/ReadOperationsTest.php

@@ -183,4 +183,26 @@ public function testReadPreference(): void
         $this->assertNotNull($movies);
         $this->assertCount(2, $movies);
     }
+
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testQueryLog(): void
+    {
+        // start-query-log
+        DB::connection('mongodb')->enableQueryLog();
+
+        Movie::where('title', 'Carrie')->get();
+        Movie::where('year', '<', 2005)->get();
+        Movie::where('imdb.rating', '>', 8.5)->get();
+
+        $logs = DB::connection('mongodb')->getQueryLog();
+        foreach ($logs as $log) {
+            echo json_encode($log, JSON_PRETTY_PRINT);
+        }
+        // end-query-log
+
+        $this->assertNotNull($logs);
+    }
 }