Sean McGinnis f718919c45 Fix poor examples of exception logging

There were several examples showing passing an
exception in as the message text to a call to
LOG.exception. LOG.exception will automatically
log the exception details, so doing something
like this results in the exception information
being written out twice.

To prevent the possibility of someone seeing these
examples and assuming that is the correct way to
use LOG.exception, examples have been updated to
use LOG.error instead to illustrate the correct
way to pass in exceptions in the message string.

Change-Id: I582008609180a02eaff3d85bee5b5ca4381719ce

2015-08-28 08:50:26 -05:00

5.5 KiB

Raw Blame History

Usage

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.

In an Application

Applications should use oslo.log's configuration functions to register logging-related configuration options and configure the root and other default loggers.

Call ~oslo_log.log.register_options before parsing command line options.

Call ~oslo_log.log.set_defaults before configuring logging.

Call ~oslo_log.log.setup to configure logging for the application.

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.

Migrating to oslo.log

Applications using the incubated version of the logging code from Oslo may need to make some extra changes.

What do I import?

Our goal is to allow most libraries to import the Python standard library module, logging, and not require oslo.log directly. Applications may do the same, but if an application takes advantage of features like passing keywords through to the context for logging, it is likely to be less confusing to use oslo.log everywhere, rather than have different types of loggers in different modules of the application.

No more `audit()`

The audit() method of the old ContextAdapter class no longer exists. We agreed in the cross project spec to stop using audit level anyway, so those calls should be replaced with calls to info().

Deprecation tools moved to `versionutils`

The deprecated decorator and DeprecatedConfig have moved to oslo_log.versionutils. Replace LOG.deprecated() with oslo_log.versionutils.report_deprecated_feature, passing a local logger object as the first argument so the log message includes the location information.

No more implicit conversion to unicode/str

The old ContextAdapter used to convert anything given to it to a unicode object before passing it to lower layers of the logging code. The new logging configuration uses a formatter instead of an adapter, so this conversion is no longer possible. All message format strings therefore need to be passed as unicode objects --that's strictly unicode, not str. If a message has no interpolation for extra parameters, a byte string can be used.

The most common place to encounter this is where Logger.error is used by passing an exception object as the first argument.

# Old style
try:
    do_something()
except Exception as err:
    LOG.error(err)

Now, the error should be converted to unicode either by calling six.text_type or by using a unicode formatting string to provide context. It's even better to replace the redundant message produced by passing the exception with a useful message.

# New style, preferred approach
from myapp._i18n import _LE  # see oslo.i18n
try:
    do_something()
except Exception as err:
    LOG.exception(_LE(u"do_something couldn't do something"))

# New style, with exception
from myapp._i18n import _LE  # see oslo.i18n
try:
    do_something()
except Exception as err:
    LOG.error(_LE(u"do_something couldn't do something: %s"), err)

# New style, alternate without context
import six
try:
    do_something()
except Exception as err:
    LOG.error(six.text_type(err))

Failure to do this for exceptions or other objects containing translatable strings from oslo.i18n results in an exception when the _Message instance is combined in unsupported ways with the default formatting string inside the logging module in the standard library.

Changes to App Initialization

The logging options are no longer registered on the global configuration object defined in oslo.config, and need to be registered explicitly on the configuration object being used by the application. Do this by calling ~oslo_log.log.register_options before parsing command line options.

The same configuration option passed to ~oslo_log.log.register_options should also be passed as the first argument to ~oslo_log.log.setup.

See usage-app for more details about application setup.

Passing Context

Applications are expected to be using oslo_context.context.RequestContext as the base class for their application-specific context classes. The base class manages a thread-local storage for the "current" context object so that oslo.log can retrieve it without having the value passed in explicitly. This ensures that all log messages include the same context information, such as the request id and user identification. See the oslo.context documentation for details of using the class.

5.5 KiB Raw Blame History