Usage

Usage

In an Application

When using Python’s standard logging library the following minimal setup demonstrates basic logging.

 1import logging
 2
 3LOG = logging.getLogger(__name__)
 4
 5# Define a default handler at INFO logging level
 6logging.basicConfig(level=logging.INFO)
 7
 8LOG.info("Python Standard Logging")
 9LOG.warning("Python Standard Logging")
10LOG.error("Python Standard Logging")

Source: examples/python_logging.py

When using Oslo Logging the following setup demonstrates a comparative syntax with Python standard logging.

 1from oslo_config import cfg
 2from oslo_log import log as logging
 3
 4LOG = logging.getLogger(__name__)
 5CONF = cfg.CONF
 6DOMAIN = "demo"
 7
 8logging.register_options(CONF)
 9logging.setup(CONF, DOMAIN)
10
11# Oslo Logging uses INFO as default
12LOG.info("Oslo Logging")
13LOG.warning("Oslo Logging")
14LOG.error("Oslo Logging")

Source: examples/oslo_logging.py

Oslo 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 register_options() with an oslo.config CONF object before parsing any application command line options.

1CONF = cfg.CONF
2
3def prepare():
4
5    # Required step to register common, logging and generic configuration
6    # variables
7    logging.register_options(CONF)

Optionally call set_defaults() before setup to change default logging levels if necessary.

 1    # Optional step to set new defaults if necessary for
 2    # * logging_context_format_string
 3    # * default_log_levels
 4
 5    extra_log_level_defaults = [
 6        'dogpile=INFO',
 7        'routes=INFO'
 8        ]
 9
10    logging.set_defaults(
11        default_log_levels=logging.get_default_log_levels() +
12        extra_log_level_defaults)

Call 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.

1DOMAIN = 'demo'
2
3def prepare():
4
5    # Required setup based on configuration and domain
6    logging.setup(CONF, DOMAIN)

Source: examples/usage.py

Oslo Logging Functions

Use standard Python logging functions to produce log records at applicable log levels.

1    # NOTE: These examples do not demonstration Oslo i18n messages
2
3    LOG.info("Welcome to Oslo Logging")
4    LOG.debug("A debugging message")
5    LOG.warning("A warning occurred")
6    LOG.error("An error occurred")
7    try:

Example Logging Output:

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 occurred
2016-01-14 21:07:51.395 12945 ERROR __main__ [-] An error occurred
2016-01-14 21:07:51.396 12945 ERROR __main__ [-] An Exception occurred
2016-01-14 21:07:51.396 12945 ERROR __main__ None
2016-01-14 21:07:51.396 12945 ERROR __main__

Oslo Log Translation

As of the Pike release, logging within an application should no longer use Oslo International Utilities (i18n) marker functions to provide language translation capabilities.

Adding Context to Logging

With the use of Oslo Context, log records can also contain additional contextual information applicable for your application.

1    LOG.info("Welcome to Oslo Logging")
2    LOG.info("Without context")
3    context.RequestContext(user='6ce90b4d',
4                           tenant='d6134462',
5                           domain='a6b9360e')
6    LOG.info("With context")

Example Logging Output:

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 logging_default_format_string configuration variable. When specifying context the 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

examples/usage.py provides a documented example of Oslo Logging setup.

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.

examples/usage_context.py provides a documented example of Oslo Logging with Oslo Context.

In a Library

oslo.log is primarily used for configuring logging in an application, but it does include helpers that can be useful from libraries.

getLogger() wraps the function of the same name from Python’s standard library to add a KeywordArgumentAdapter, making it easier to pass data to the formatters provided by oslo.log and configured by an application.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.