From 64b2a886e83ea8d78d15c55c2c930cc1517869ab Mon Sep 17 00:00:00 2001
From: Sean Madsen <sean@seanmadsen.com>
Date: Wed, 5 Jul 2017 11:51:56 -0600
Subject: [PATCH] Improve instructions for MySQL query logging

- Add details about how to do query logging to a table instead of a
  file.
- Put instructions into steps in chronological order.
---
 docs/tools/debugging.md | 79 ++++++++++++++++++++++++++++++-----------
 1 file changed, 58 insertions(+), 21 deletions(-)

diff --git a/docs/tools/debugging.md b/docs/tools/debugging.md
index 19511492..43d4fe63 100644
--- a/docs/tools/debugging.md
+++ b/docs/tools/debugging.md
@@ -83,31 +83,68 @@ The following values can be added to your site's settings file `civicrm.settings
 
 ## Viewing a query log from MySQL
 
-Outside of CiviCRM, the MySQL general query log allows MySQL to log all queries. This is a performance killer, so avoid using it in production!
+Outside of CiviCRM, the [MySQL General Query Log](https://dev.mysql.com/doc/refman/en/query-log.html) log allows MySQL to log all queries. This is a performance killer, so avoid using it in production!
+
+1. Inspect your current settings
+
+    ```sql
+    SHOW VARIABLES
+    WHERE variable_name IN (
+      'general_log',
+      'general_log_file',
+      'log_output'
+      );
+    ```
+
+    ```text
+    +------------------+------------------------------+
+    | Variable_name    | Value                        |
+    +------------------+------------------------------+
+    | general_log      | OFF                          |
+    | general_log_file | /var/lib/mysql/localhost.log |
+    | log_output       | FILE                         |
+    +------------------+------------------------------+
+    ```
+
+    You should see `general_log` set to `OFF` by default.
+
+1. Turn on logging.
+
+    ```sql
+    SET GLOBAL general_log = 'ON';
+    ```
 
-* [MySQL reference: General Query Log](https://dev.mysql.com/doc/refman/en/query-log.html)
+    * To **log to a file**, leave `log_output` = `FILE`, as it is probably already set.
 
-The relevant settings are:
+    * To **log to a table** (which can sometimes be easier to sift through), execute the following. Note that you need to leave `'TABLE'` as a string literal here
 
-    # Location of the query log
-    general_log_file=/tmp/mysql.log
-    # Enable/disable the query log
-    general_log=1
+        ```sql
+        SET GLOBAL log_output = 'TABLE';
+        ```
 
-You can enable the query log at runtime via SQL, provided the path to the logfile is configured.
+1. Do something with CiviCRM that produces MySQL queries.
 
-    SET GLOBAL general_log = 'ON';
-    SET GLOBAL general_log = 'OFF';
+1. View the log.
+
+    * If logging to a file, then find (or change) the location of the log file with the `general_log_file` variable.
+
+    * If logging to a table run:
 
-And you can inspect the query log settings also:
+        ```sql
+        SELECT * FROM mysql.general_log
+        ```
 
-    mysql> show variables like '%general%';
-    +------------------+---------------------------------+
-    | Variable_name    | Value                           |
-    +------------------+---------------------------------+
-    | general_log      | OFF                             |
-    | general_log_file | /usr/local/var/mysql/strike.log |
-    +------------------+---------------------------------+
+1. (If logging to a table) clear the log. (It can be helpful to do this before performing an action that you'd like to inspect).
+
+    ```sql
+    TRUNCATE TABLE mysql.general_log;
+    ```
+
+1. When you're finished, turn *off* logging.
+
+    ```sql
+    SET GLOBAL general_log = 'OFF';
+    ```
 
 ## Changing source code
 
@@ -280,7 +317,7 @@ for more information.
 
 ## Error 500, white screen (WSoD),  "Internal Server Error" errors
 
-If CiviCRM shows a blank white page or page with "Error 500" with no other messages on screen, follow the steps in this section to diagnose and fix. A white screen (WSoD or "white screen of death") indicates that PHP is configured not to display errors, and has hit an error which it can't recover from. The result is an empty page. 
+If CiviCRM shows a blank white page or page with "Error 500" with no other messages on screen, follow the steps in this section to diagnose and fix. A white screen (WSoD or "white screen of death") indicates that PHP is configured not to display errors, and has hit an error which it can't recover from. The result is an empty page.
 
 Your next step is not to fix the error, but to first give yourself enough information to identify the source of the error. (Diagnose, then treat.)
 
@@ -311,7 +348,7 @@ You may prefer to display errors to screen. This is probably disabled on your si
 
 To enable error display, either:
 
-**Configure your PHP to display errors for your site** via `php.ini` / `.htaccess` (see [How can I get PHP errors to display](http://stackoverflow.com/questions/1053424/how-do-i-get-php-errors-to-display)), OR 
+**Configure your PHP to display errors for your site** via `php.ini` / `.htaccess` (see [How can I get PHP errors to display](http://stackoverflow.com/questions/1053424/how-do-i-get-php-errors-to-display)), OR
 
 **Add PHP code to enable error display** (you can add it in `civicrm.settings.php` or the top of the `index.php` of your host CMS).
 
@@ -344,7 +381,7 @@ If you're not familiar with UNIX, this may seem like a lot of effort. It's a lot
 ## Credits
 
 Some content from this page was migrated from other sources
-and contributed by the following authors: 
+and contributed by the following authors:
 
 * Chris Burgess
 * Sean Madsen
-- 
GitLab