oslo.log/doc/source/user/usage.rst

Usage

In an Application

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

examples/python_logging.py

Source: examples/python_logging.py <example_python_logging.py>

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

examples/oslo_logging.py

Source: examples/oslo_logging.py <example_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 ~oslo_log.log.register_options with an oslo.config CONF object before parsing any application command line options.

examples/usage.py

Optionally call ~oslo_log.log.set_defaults before setup to change default logging levels if necessary.

examples/usage.py

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

examples/usage.py

Source: examples/usage.py <example_usage.py>

Oslo Logging Functions

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

examples/usage.py

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.

examples/usage_i18n.py

Source: 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.

examples/usage_context.py

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 :oslo.configlogging_default_format_string configuration variable. When specifying context the :oslo.configlogging_context_format_string configuration variable is used.

The Oslo RequestContext object contains a number of attributes that can be specified in :oslo.configlogging_context_format_string. An application can extend this object to provide additional attributes that can be specified in log records.

Examples

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

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.

examples/usage_i18n.py <example_usage_i18n.py> provides a documented example of Oslo Logging with Oslo i18n supported messages.

examples/usage_context.py <example_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.

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