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
120 lines
4.4 KiB
ReStructuredText
120 lines
4.4 KiB
ReStructuredText
Migrating from Oslo Incubator 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()``.
|
|
|
|
.. _cross project spec: http://git.openstack.org/cgit/openstack/openstack-specs/tree/specs/log-guidelines.rst
|
|
|
|
Deprecation tools moved to ``versionutils``
|
|
-------------------------------------------
|
|
|
|
The :meth:`deprecated` decorator and :class:`DeprecatedConfig` have
|
|
moved to :mod:`oslo_log.versionutils`. Replace ``LOG.deprecated()``
|
|
with :mod:`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 :class:`ContextAdapter` used to convert anything given to it
|
|
to a :class:`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 :class:`unicode`, not :class:`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 :meth:`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
|
|
:func:`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 :class:`_Message` instance is combined in unsupported ways with
|
|
the default formatting string inside the :mod:`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 :func:`~oslo_log.log.register_options`
|
|
before parsing command line options.
|
|
|
|
The same configuration option passed to
|
|
:func:`~oslo_log.log.register_options` should also be passed as the
|
|
first argument to :func:`~oslo_log.log.setup`.
|
|
|
|
See :ref:`usage-app` for more details about application setup.
|
|
|
|
Passing Context
|
|
---------------
|
|
|
|
Applications are expected to be using
|
|
:class:`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.
|