docs: updated documentation structure

2019-05-21 16:33:01 +02:00 · 2019-05-21 16:33:01 +02:00 · eddc784e19
commit eddc784e19
parent 434efcd94f
47 changed files with 158 additions and 98 deletions
--- a/docs/admin/system_admin/enable-debug.rst
+++ b/docs/admin/system_admin/enable-debug.rst
@ -0,0 +1,148 @@
+.. _debug-mode:
+
+Enabling Debug Mode
+-------------------
+
+Debug Mode will enable debug logging, and request tracking middleware. Debug Mode
+enabled DEBUG log-level which allows tracking various information about authentication
+failures, LDAP connection, email etc.
+
+The request tracking will add a special
+unique ID: `| req_id:00000000-0000-0000-0000-000000000000` at the end of each log line.
+The req_id is the same for each individual requests, it means that if you want to
+track particular user logs only, and exclude other concurrent ones
+simply grep by `req_id` uuid which you'll have to find for the individual request.
+
+To enable debug mode on a |RCE| instance you need to set the debug property
+in the :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file. To
+do this, use the following steps
+
+1. Open the file and set the ``debug`` line to ``true``
+2. Restart you instance using the ``rccontrol restart`` command,
+   see the following example:
+
+.. code-block:: ini
+
+    [DEFAULT]
+    debug = true
+
+.. code-block:: bash
+
+    # Restart your instance
+    $ rccontrol restart enterprise-1
+    Instance "enterprise-1" successfully stopped.
+    Instance "enterprise-1" successfully started.
+
+
+Debug and Logging Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Further debugging and logging settings can also be set in the
+:file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file.
+
+In the logging section, the various packages that run with |RCE| can have
+different debug levels set. If you want to increase the logging level change
+``level = DEBUG`` line to one of the valid options.
+
+You also need to change the log level for handlers. See the example
+``##handler`` section below. The ``handler`` level takes the same options as
+the ``debug`` level.
+
+.. code-block:: ini
+
+    ################################
+    ### LOGGING CONFIGURATION   ####
+    ################################
+    [loggers]
+    keys = root, sqlalchemy, beaker, celery, rhodecode, ssh_wrapper
+
+    [handlers]
+    keys = console, console_sql, file, file_rotating
+
+    [formatters]
+    keys = generic, color_formatter, color_formatter_sql
+
+    #############
+    ## LOGGERS ##
+    #############
+    [logger_root]
+    level = NOTSET
+    handlers = console
+
+    [logger_sqlalchemy]
+    level = INFO
+    handlers = console_sql
+    qualname = sqlalchemy.engine
+    propagate = 0
+
+    [logger_beaker]
+    level = DEBUG
+    handlers =
+    qualname = beaker.container
+    propagate = 1
+
+    [logger_rhodecode]
+    level = DEBUG
+    handlers =
+    qualname = rhodecode
+    propagate = 1
+
+    [logger_ssh_wrapper]
+    level = DEBUG
+    handlers =
+    qualname = ssh_wrapper
+    propagate = 1
+
+    [logger_celery]
+    level = DEBUG
+    handlers =
+    qualname = celery
+
+    ##############
+    ## HANDLERS ##
+    ##############
+
+    [handler_console]
+    class = StreamHandler
+    args = (sys.stderr, )
+    level = DEBUG
+    formatter = generic
+
+    [handler_console_sql]
+    class = StreamHandler
+    args = (sys.stderr, )
+    level = INFO
+    formatter = generic
+
+    [handler_file]
+    class = FileHandler
+    args = ('rhodecode_debug.log', 'a',)
+    level = INFO
+    formatter = generic
+
+    [handler_file_rotating]
+    class = logging.handlers.TimedRotatingFileHandler
+    # 'D', 5 - rotate every 5days
+    # you can set 'h', 'midnight'
+    args = ('rhodecode_debug_rotated.log', 'D', 5, 10,)
+    level = INFO
+    formatter = generic
+
+    ################
+    ## FORMATTERS ##
+    ################
+
+    [formatter_generic]
+    class = rhodecode.lib.logging_formatter.ExceptionAwareFormatter
+    format = %(asctime)s.%(msecs)03d [%(process)d] %(levelname)-5.5s [%(name)s] %(message)s
+    datefmt = %Y-%m-%d %H:%M:%S
+
+    [formatter_color_formatter]
+    class = rhodecode.lib.logging_formatter.ColorFormatter
+    format = %(asctime)s.%(msecs)03d [%(process)d] %(levelname)-5.5s [%(name)s] %(message)s
+    datefmt = %Y-%m-%d %H:%M:%S
+
+    [formatter_color_formatter_sql]
+    class = rhodecode.lib.logging_formatter.ColorFormatterSql
+    format = %(asctime)s.%(msecs)03d [%(process)d] %(levelname)-5.5s [%(name)s] %(message)s
+    datefmt = %Y-%m-%d %H:%M:%S