Add logging documentation

Document how logging is implemented and how it can be used and configured

Change-Id: I1ce123abb0b363aefccba109f934eaf5ce6e755a
Implements: blueprint websocket-logging

docs/index.rst

@@ -14,6 +14,7 @@ Welcome to Tripleo UI's developer documentation!
    overview
    testing
    translation
+   logging
    packaging
    contributing
 

docs/logging.rst

@@ -0,0 +1,63 @@
+Logging
+=======
+
+This document describes how logging works in tripleo-ui.
+
+Collection
+----------
+
+Logs are collected by using the logging service.  The logging service has an API
+similar to the ``console`` API in modern browsers.  This means that we can use
+the standard "info", "warn", "error" semantics.
+
+Import the logging service like this:
+
+.. code-block:: js
+
+   import logger from './src/js/services/logging/LoggingService';
+
+And then use the logger object directly:
+
+.. code-block:: js
+
+   logger.error('Something bad happened.')
+
+Logs are collected to two different places: the browser console and a Zaqar
+queue on the undercloud.  This is done via logging adapters in
+``src/js/services/logging/adapters``.  Adapters share a common API and allow us
+to send logging data to multiple destinations, and to enable and disable them
+based on our needs.
+
+We collect standard logging data via logging statements introduced to our code
+by application developers.  In addition to that, we collect data via the
+redux-logger mechanism.  This records application state changes, and the
+application state itself.
+
+Configuration
+-------------
+
+Logging can be configured in the ``tripleo_ui_config.js`` file.  You can enable
+or disable certain loggers in the ``loggers`` array, and you can change the name
+of the Zaqar queue where your messages will be sent.  By default, the name of
+the queue is different from the normal TripleO queue to avoid any conflicts.
+
+Storage
+-------
+
+Once messages arrive in the configured Zaqar queue, they wait to be persisted in
+Swift.  Once an hour, a cron-triggered Mistral workflow drains the queue,
+formats the messages into log lines, and persists them in a Swift object.  This
+object lives in a container called ``tripleo-ui-logs``.
+
+The Mistral workflow also checks if the log file has reached or exceeded 10MB in
+size, and if so, it will rotate the log.
+
+Retrieval
+---------
+
+Logs can be retrieved from Swift by using the Debug part of the interface.  It
+can be accessed from the navbar in the upper right corner.  You request the
+logs, and Mistral will gather them for you, put them in a tar archive, and make
+them available at a temporary Swift url for you to download.
+
+Logs are also included in sosreports.