185c10a36b
Added examples to explain how to implement Oslo Logging and to show how it interacts with Oslo Config and i18n. Revised configuration option help (and order) to provide a better documented Configuration Options page Change-Id: Idf4a8788f887ba07fe1b3604e06b165366b2c808
2.7 KiB
Usage
In an Application
When using Python's standard logging library the following minimal setup demostrates basic logging.
examples/python_logging.py
Source: examples/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
Olso Logging 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 the application command line options.
Optionally call ~oslo_log.log.set_defaults before setup to change
default logging levels if necessary.
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.
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.
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.
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.