From 77d2c4def47c3c4283cde28f48b369ed8b696ed0 Mon Sep 17 00:00:00 2001 From: Ronald Bradford Date: Thu, 14 Jan 2016 22:50:07 +0000 Subject: [PATCH] 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 | 1 + doc/source/examples.rst | 60 +++++++++++++++ doc/source/examples/oslo_logging.py | 2 +- doc/source/examples/usage.py | 9 ++- doc/source/examples/usage_context.py | 85 +++++++++++++++++++++ doc/source/examples/usage_helper.py | 4 +- doc/source/examples/usage_i18n.py | 15 ++-- doc/source/index.rst | 1 + doc/source/usage.rst | 110 +++++++++++++++++++++++---- 9 files changed, 258 insertions(+), 29 deletions(-) create mode 100644 doc/source/examples.rst create mode 100644 doc/source/examples/usage_context.py diff --git a/doc/source/conf.py b/doc/source/conf.py index 454c6bc2..f64b726d 100755 --- a/doc/source/conf.py +++ b/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', diff --git a/doc/source/examples.rst b/doc/source/examples.rst new file mode 100644 index 00000000..78e7f2b3 --- /dev/null +++ b/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: diff --git a/doc/source/examples/oslo_logging.py b/doc/source/examples/oslo_logging.py index 886278a1..c002c8e6 100644 --- a/doc/source/examples/oslo_logging.py +++ b/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 diff --git a/doc/source/examples/usage.py b/doc/source/examples/usage.py index 8466050e..ffd73ef9 100644 --- a/doc/source/examples/usage.py +++ b/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") diff --git a/doc/source/examples/usage_context.py b/doc/source/examples/usage_context.py new file mode 100644 index 00000000..15a3c071 --- /dev/null +++ b/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") diff --git a/doc/source/examples/usage_helper.py b/doc/source/examples/usage_helper.py index 0b5baa47..84926c1a 100644 --- a/doc/source/examples/usage_helper.py +++ b/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__) diff --git a/doc/source/examples/usage_i18n.py b/doc/source/examples/usage_i18n.py index ef53f849..46a3ed42 100644 --- a/doc/source/examples/usage_i18n.py +++ b/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 + - extra_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) @@ -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")) diff --git a/doc/source/index.rst b/doc/source/index.rst index f19855b0..0cf0d6c6 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,6 +15,7 @@ logging (like resource id's etc). migration opts configfiles/index + examples contributing history diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 442a323f..2f08da60 100644 --- a/doc/source/usage.rst +++ b/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 ` 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 ` -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 -levels. Logging should also use Oslo i18n contextual functions to provide -translation. With the use of Oslo Context, log records can also contain -additional contextual information. +.. literalinclude:: examples/usage.py + :linenos: + :lines: 34,36-37,70-72 + :emphasize-lines: 6 + +Source: :ref:`examples/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 ` + +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 ` +configuration variable. When specifying context the +:ref:`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 ` provides a documented +example of Oslo Logging setup. -:download:`examples/usage.py` provides a documented example of -Oslo Logging setup. +:ref:`examples/usage_helper.py ` provides an +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 -debugging logging at each step details the configuration and logging -at each step of Oslo Logging setup. +:ref:`examples/usage_i18n.py ` provides a +documented example of Oslo Logging with Oslo i18n supported messages. -:download:`examples/usage_i18n.py` provides a documented example of -Oslo Logging with Oslo i18n supported messages. +:ref:`examples/usage_context.py ` provides +a documented example of Oslo Logging with Oslo Context. General Logging Guidelines