openstack/oslo.log
Code Issues Proposed changes

Improve Logging docs with inline examples and context example

Browse Source 
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
This commit is contained in:
Ronald Bradford 2016-01-14 22:50:07 +00:00
parent 185c10a36b
commit 77d2c4def4
9 changed files with 258 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/conf.py
View File

@ -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',

60
doc/source/examples.rst Normal file
View File

@ -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:

2
doc/source/examples/oslo_logging.py
View File

@ -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

9
doc/source/examples/usage.py
View File

@ -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")

85
doc/source/examples/usage_context.py Normal file
View File

@ -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")

4
doc/source/examples/usage_helper.py
View File

@ -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__)

11
doc/source/examples/usage_i18n.py
View File

@ -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():
@ -66,7 +65,8 @@ def prepare():
'routes=INFO'
]
logging.set_defaults(default_log_levels=CONF.default_log_levels +
logging.set_defaults(
default_log_levels=logging.get_default_log_levels() +
extra_log_level_defaults)
# Required setup based on configuration and 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"))

1
doc/source/index.rst
View File

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

110
doc/source/usage.rst
View File

@ -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
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 <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
Oslo Logging setup.
:ref:`examples/usage_helper.py <example_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 <example_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 <example_usage_context.py>` provides
a documented example of Oslo Logging with Oslo Context.
General Logging Guidelines