Improve Logging docs with inline examples and context example

Also cleaned up set_default example syntax, to help other projects
to implement consistently. Ensured example code passed flake8.
Created a dedicated examples page and applicable links to enable
viewing and download capability of examples.

Change-Id: Idd16321110df824dc89faf86a2cf9f47f38d1f4f
Depends-on: I6f92b525c6d0bdf71b01d3ac89d537b458d17e6f

doc/source/conf.py

@@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
     #'sphinx.ext.intersphinx',
     'oslosphinx',
     'oslo_config.sphinxext',

doc/source/examples.rst

@@ -0,0 +1,60 @@
+==========
+ Examples
+==========
+
+.. _examples:
+
+These files can be found in the docs/source/examples directory of
+the git source of this project.  They can also be found at the 
+`online git respository`_ of this project.
+
+.. _online git respository: http://git.openstack.org/cgit/openstack/oslo.log/tree/doc/source/examples
+
+
+python_logging.py
+-----------------
+
+.. _example_python_logging.py:
+
+.. highlight:: python
+.. literalinclude:: examples/python_logging.py
+   :linenos:
+
+oslo_logging.py
+---------------
+
+.. _example_olso_logging.py:
+
+.. literalinclude:: examples/oslo_logging.py
+
+usage.py
+--------
+
+.. _example_usage.py:
+
+.. literalinclude:: examples/usage.py
+   :linenos:
+
+usage_helper.py
+---------------
+
+.. _example_usage_helper.py:
+
+.. literalinclude:: examples/usage_helper.py
+   :linenos:
+
+usage_i18n.py
+-------------
+
+.. _example_usage_i18n.py:
+
+.. literalinclude:: examples/usage_i18n.py
+   :linenos:
+
+usage_context.py
+----------------
+
+.. _example_usage_context.py:
+
+.. literalinclude:: examples/usage_context.py
+   :linenos:

doc/source/examples/oslo_logging.py

@@ -14,8 +14,8 @@
 
 """A minimal syntax example of Oslo Logging"""
 
-from oslo_log import log as logging
 from oslo_config import cfg
+from oslo_log import log as logging
 
 LOG = logging.getLogger(__name__)
 CONF = cfg.CONF

doc/source/examples/usage.py

@@ -31,7 +31,7 @@ from oslo_log import log as logging
 
 LOG = logging.getLogger(__name__)
 CONF = cfg.CONF
-DOMAIN = "demo"
+DOMAIN = 'demo'
 
 
 def prepare():
@@ -59,12 +59,14 @@ def prepare():
     #  oslo_log._options.log_opts[0].default
     #
 
-    custom_log_level_defaults = logging.get_default_log_levels() + [
+    extra_log_level_defaults = [
         'dogpile=INFO',
         'routes=INFO'
         ]
 
-    logging.set_defaults(default_log_levels=custom_log_level_defaults)
+    logging.set_defaults(
+        default_log_levels=logging.get_default_log_levels() +
+        extra_log_level_defaults)
 
     # Required setup based on configuration and domain
     logging.setup(CONF, DOMAIN)
@@ -73,6 +75,7 @@ def prepare():
 if __name__ == '__main__':
     prepare()
     # NOTE: These examples do not demonstration Oslo i18n messages
+
     LOG.info("Welcome to Oslo Logging")
     LOG.debug("A debugging message")
     LOG.warning("A warning occured")

doc/source/examples/usage_context.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2016 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A usage example of Oslo Logging with context
+
+This example requires the following package to be installed.
+
+$ pip install oslo.log
+
+Additional Oslo packages installed include oslo.config, oslo.context,
+oslo.i18n, osli.serialization and oslo.utils.
+
+More information about Oslo Logging can be found at:
+
+  http://docs.openstack.org/developer/oslo.log/usage.html
+  http://docs.openstack.org/developer/oslo.context/usage.html
+"""
+
+from oslo_config import cfg
+from oslo_context import context
+from oslo_log import log as logging
+
+LOG = logging.getLogger(__name__)
+CONF = cfg.CONF
+DOMAIN = 'demo'
+
+
+def prepare():
+    """Prepare Oslo Logging (2 or 3 steps)
+
+    Use of Oslo Logging involves the following:
+
+    * logging.register_options
+    * logging.set_defaults (optional)
+    * logging.setup
+    """
+
+    # Required step to register common, logging and generic configuration
+    # variables
+    logging.register_options(CONF)
+
+    # Optional step to set new defaults if necessary for
+    # * logging_context_format_string
+    # * default_log_levels
+    #
+    # These variables default to respectively:
+    #
+    #  import oslo_log
+    #  oslo_log._options.DEFAULT_LOG_LEVELS
+    #  oslo_log._options.log_opts[0].default
+    #
+
+    extra_log_level_defaults = [
+        'dogpile=INFO',
+        'routes=INFO'
+        ]
+
+    logging.set_defaults(
+        default_log_levels=logging.get_default_log_levels() +
+        extra_log_level_defaults)
+
+    # Required setup based on configuration and domain
+    logging.setup(CONF, DOMAIN)
+
+
+if __name__ == '__main__':
+    prepare()
+
+    LOG.info("Welcome to Oslo Logging")
+    LOG.info("Without context")
+    context.RequestContext(user='6ce90b4d',
+                           tenant='d6134462',
+                           domain='a6b9360e')
+    LOG.info("With context")

doc/source/examples/usage_helper.py

@@ -26,10 +26,10 @@ More information about Oslo Logging can be found at:
   http://docs.openstack.org/developer/oslo.log/usage.html
 """
 
-from oslo_config import cfg
-from oslo_log import log as logging
 # Use default Python logging to display running output
 import logging as py_logging
+from oslo_config import cfg
+from oslo_log import log as logging
 
 
 LOG = py_logging.getLogger(__name__)

doc/source/examples/usage_i18n.py

@@ -15,7 +15,6 @@
 """A usage example of Oslo Logging with Oslo i18n
 
 This example requires the following package to be installed.
-
 $ pip install oslo.log
 
 Additional Oslo packages installed include oslo.config, oslo.context,
@@ -29,11 +28,11 @@ More information about Oslo Logging can be found at:
 
 from oslo_config import cfg
 from oslo_log import log as logging
-from _i18n import _, _LI, _LW, _LE
+from _i18n import _, _LI, _LW, _LE  # noqa
 
 LOG = logging.getLogger(__name__)
 CONF = cfg.CONF
-DOMAIN = "demo"
+DOMAIN = 'demo'
 
 
 def prepare():
@@ -64,10 +63,11 @@ def prepare():
     extra_log_level_defaults = [
         'dogpile=INFO',
         'routes=INFO'
-    ]
+        ]
 
-    logging.set_defaults(default_log_levels=CONF.default_log_levels +
+    logging.set_defaults(
-                         extra_log_level_defaults)
+        default_log_levels=logging.get_default_log_levels() +
+        extra_log_level_defaults)
 
     # Required setup based on configuration and domain
     logging.setup(CONF, DOMAIN)
@@ -75,7 +75,8 @@ def prepare():
 
 if __name__ == '__main__':
     prepare()
-    # NOTE: These examples use Oslo i18n messages
+    # NOTE: These examples use Oslo i18n marker functions
+
     LOG.info(_LI("Welcome to Oslo Logging"))
     LOG.debug("A debugging message")  # Debug messages are not translated
     LOG.warning(_LW("A warning occured"))

doc/source/index.rst

@@ -15,6 +15,7 @@ logging (like resource id's etc).
    migration
    opts
    configfiles/index
+   examples
    contributing
    history
 

doc/source/usage.rst

@@ -12,11 +12,12 @@ demostrates basic logging.
 
 .. _Python's standard logging library: https://docs.python.org/2/library/logging.html
 
+.. highlight:: python
 .. literalinclude:: examples/python_logging.py
    :linenos:
    :lines: 17-26
 
-Source: :download:`examples/python_logging.py`
+Source: :ref:`examples/python_logging.py <example_python_logging.py>`
 
 When using ``Oslo Logging`` the following setup demonstrates a comparative
 syntax with Python standard logging.
@@ -27,43 +28,120 @@ syntax with Python standard logging.
    :lines: 17-30
    :emphasize-lines: 8,9
 
-Source: :download:`examples/oslo_logging.py`
+Source: :ref:`examples/oslo_logging.py <example_olso_logging.py>`
 
-Olso Logging Methods
+Olso Logging Setup Methods
---------------------
+--------------------------
 
 Applications need to use the oslo.log configuration functions to register
 logging-related configuration options and configure the root and other
 default loggers before using standard logging functions.
 
 Call :func:`~oslo_log.log.register_options` with an oslo.config CONF object
-before parsing the application command line options.
+before parsing any application command line options.
+
+.. literalinclude:: examples/usage.py
+   :linenos:
+   :lines: 33,36-37,46-49
+   :emphasize-lines: 7
 
 Optionally call :func:`~oslo_log.log.set_defaults` before setup to
 change default logging levels if necessary.
 
+.. literalinclude:: examples/usage.py
+   :linenos:
+   :lines: 51-53,61-69
+   :emphasize-lines: 10
+
 Call :func:`~oslo_log.log.setup` with the oslo.config CONF object used
 when registering objects, along with the domain and optionally a version
 to configure logging for the application.
 
-Use standard logging functions to produce log records at applicable log
+.. literalinclude:: examples/usage.py
-levels.  Logging should also use Oslo i18n contextual functions to provide
+   :linenos:
-translation.  With the use of Oslo Context, log records can also contain
+   :lines: 34,36-37,70-72
-additional contextual information.
+   :emphasize-lines: 6
+
+Source: :ref:`examples/usage.py <example_usage.py>`
+
+Olso Logging Functions
+----------------------
+
+Use standard Python logging functions to produce log records at applicable
+log levels.
+
+.. literalinclude:: examples/usage.py
+   :linenos:
+   :lines: 77-83
+
+**Example Logging Output:**
+
+.. testoutput::
+
+    2016-01-14 21:07:51.394 12945 INFO __main__ [-] Welcome to Oslo Logging
+    2016-01-14 21:07:51.395 12945 WARNING __main__ [-] A warning occured
+    2016-01-14 21:07:51.395 12945 ERROR __main__ [-] An error occured
+    2016-01-14 21:07:51.396 12945 ERROR __main__ [-] An Exception occured
+    2016-01-14 21:07:51.396 12945 ERROR __main__ None
+    2016-01-14 21:07:51.396 12945 ERROR __main__
+
+Logging within an application should use `Oslo International Utilities (i18n)`_ marker
+functions to provide language translation capabilities.
+
+.. _Oslo International Utilities (i18n): http://docs.openstack.org/developer/oslo.i18n/
+
+.. literalinclude:: examples/usage_i18n.py
+   :linenos:
+   :lines: 31-32,76,79-85
+   :emphasize-lines: 1
+
+Source: :ref:`examples/usage_i18n.py <example_usage_i18n.py>`
+
+With the use of `Oslo Context`_, log records can also contain
+additional contextual information applicable for your application.
+
+.. _Oslo Context: http://docs.openstack.org/developer/oslo.context/
+
+.. literalinclude:: examples/usage_context.py
+   :linenos:
+   :lines: 80-85
+   :emphasize-lines: 3-5
+
+**Example Logging Output:**
+
+.. testoutput::
+
+    2016-01-14 20:04:34.562 11266 INFO __main__ [-] Welcome to Oslo Logging
+    2016-01-14 20:04:34.563 11266 INFO __main__ [-] Without context
+    2016-01-14 20:04:34.563 11266 INFO __main__ [req-bbc837a6-be80-4eb2-8ca3-53043a93b78d 6ce90b4d d6134462 a6b9360e - -] With context
+
+The log record output format without context is defined with
+:ref:`logging_default_format_string <opt-default-logging_default_format_string>`
+configuration variable.  When specifying context the
+:ref:`logging_context_format_string <opt-default-logging_context_format_string>`
+configuration variable is used.
+
+The Oslo RequestContext object contains a number of attributes that can be
+specified in ``logging_context_format_string``. An application can extend this
+object to provide additional attributes that can be specified in log records.
+
+
 
 Examples
 --------
 
+:ref:`examples/usage.py <example_usage.py>` provides a documented
+example of Oslo Logging setup.
 
-:download:`examples/usage.py` provides a documented example of
+:ref:`examples/usage_helper.py <example_usage_helper.py>` provides an
-Oslo Logging setup.
+example showing debugging logging at each step details the configuration
+and logging at each step of Oslo Logging setup.
 
-:download:`examples/usage_helper.py` provides an example showing
+:ref:`examples/usage_i18n.py <example_usage_i18n.py>` provides a
-debugging logging at each step details the configuration and logging
+documented example of Oslo Logging with Oslo i18n supported messages.
-at each step of Oslo Logging setup.
 
-:download:`examples/usage_i18n.py` provides a documented example of
+:ref:`examples/usage_context.py <example_usage_context.py>` provides
-Oslo Logging with Oslo i18n supported messages.
+a documented example of Oslo Logging with Oslo Context.
 
 
 General Logging Guidelines