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__

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.

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 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 <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_context.py <example_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.

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