Usage

updated: None

Usage

Usage¶

In an Application¶

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

import logging

LOG = logging.getLogger(__name__)

# Define a default handler at INFO logging level
logging.basicConfig(level=logging.INFO)

LOG.info("Python Standard Logging")
LOG.warning("Python Standard Logging")
LOG.error("Python Standard Logging")

Source: examples/python_logging.py

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

from oslo_config import cfg
from oslo_log import log as logging

LOG = logging.getLogger(__name__)
CONF = cfg.CONF
DOMAIN = "demo"

logging.register_options(CONF)
logging.setup(CONF, DOMAIN)

# Oslo Logging uses INFO as default
LOG.info("Oslo Logging")
LOG.warning("Oslo Logging")
LOG.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.

CONF = cfg.CONF

def prepare():

    # Required step to register common, logging and generic configuration
    # variables
    logging.register_options(CONF)

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

    # Optional step to set new defaults if necessary for
    # * logging_context_format_string
    # * default_log_levels

    extra_log_level_defaults = [
        'dogpile=INFO',
        'routes=INFO'
        ]

    logging.set_defaults(
        default_log_levels=logging.get_default_log_levels() +
        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.

DOMAIN = 'demo'

def prepare():

    # Required setup based on configuration and domain
    logging.setup(CONF, DOMAIN)

Source: examples/usage.py

Oslo Logging Functions¶

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

    # NOTE: These examples do not demonstration Oslo i18n messages

    LOG.info("Welcome to Oslo Logging")
    LOG.debug("A debugging message")
    LOG.warning("A warning occurred")
    LOG.error("An error occurred")
    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__

Logging within an application should use Oslo International Utilities (i18n) marker functions to provide language translation capabilities.

from _i18n import _, _LI, _LW, _LE  # noqa

if __name__ == '__main__':

    LOG.info(_LI("Welcome to Oslo Logging"))
    LOG.debug("A debugging message")  # Debug messages are not translated
    LOG.warning(_LW("A warning occurred"))
    LOG.error(_LE("An error occurred"))
    try:
        raise Exception(_("This is exceptional"))

Source: examples/usage_i18n.py

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

    LOG.info("Welcome to Oslo Logging")
    LOG.info("Without context")
    context.RequestContext(user='6ce90b4d',
                           tenant='d6134462',
                           domain='a6b9360e')
    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_i18n.py provides a documented example of Oslo Logging with Oslo i18n supported messages.

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

General Logging Guidelines¶

The OpenStack Logging Guidelines in openstack-specs repository explain how to use different logging levels, and the desired logging patterns to be used in OpenStack applications.

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.