oslolog(1)

OSLOLOG(1)

oslo.log

OSLOLOG(1)

NAME

oslolog - oslo.log 7.1.0

The oslo.log (logging) configuration library provides standardized configuration for all openstack projects. It also provides custom formatters, handlers and support for context specific logging (like resource id's etc).

Installation

At the command line:

$ pip install oslo.log

To use oslo_log.fixture, some additional dependencies are needed. They can be installed using the fixtures extra:

$ pip install 'oslo.log[fixtures]'

Using oslo.log

Usage

In an Application

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

import logging
LOG = logging.getLogger(__name__)
# Define a default handler at INFO logging level
logging.basicConfig(level=logging.INFO)
LOG.info("Python Standard Logging")
LOG.warning("Python Standard Logging")
LOG.error("Python Standard Logging")

Source: examples/python_logging.py

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

from oslo_config import cfg
from oslo_log import log as logging
LOG = logging.getLogger(__name__)
CONF = cfg.CONF
DOMAIN = "demo"
logging.register_options(CONF)
logging.setup(CONF, DOMAIN)
# Oslo Logging uses INFO as default
LOG.info("Oslo Logging")
LOG.warning("Oslo Logging")
LOG.error("Oslo Logging")

Source: examples/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 register_options() with an oslo.config CONF object before parsing any application command line options.

CONF = cfg.CONF
def prepare():


    # Required step to register common, logging and generic configuration


    # variables


    logging.register_options(CONF)

Optionally call set_defaults() before setup to change default logging levels if necessary.



    # Optional step to set new defaults if necessary for


    # * logging_context_format_string


    # * default_log_levels


    extra_log_level_defaults = [


        'dogpile=INFO',


        'routes=INFO'


        ]


    logging.set_defaults(


        default_log_levels=logging.get_default_log_levels() +


        extra_log_level_defaults)

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

DOMAIN = 'demo'
def prepare():


    # Required setup based on configuration and domain


    logging.setup(CONF, DOMAIN)

Source: examples/usage.py

Oslo Logging Functions

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



    # NOTE: These examples do not demonstration Oslo i18n messages


    LOG.info("Welcome to Oslo Logging")


    LOG.debug("A debugging message")


    LOG.warning("A warning occurred")


    LOG.error("An error occurred")


    try:

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.



    LOG.info("Welcome to Oslo Logging")


    LOG.info("Without context")


    context.RequestContext(user='6ce90b4d',


                           tenant='d6134462',


                           domain='a6b9360e')


    LOG.info("With context")

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

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

Examples

These files can be found in the docs/source/examples directory of the git source of this project. They can also be found in the online git repository of this project.

python_logging.py

# Copyright (c) 2016 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""A syntax example of Python Logging"""
import logging
LOG = logging.getLogger(__name__)
# Define a default handler at INFO logging level
logging.basicConfig(level=logging.INFO)
LOG.info("Python Standard Logging")
LOG.warning("Python Standard Logging")
LOG.error("Python Standard Logging")

oslo_logging.py

# Copyright (c) 2016 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""A minimal syntax example of Oslo Logging"""
from oslo_config import cfg
from oslo_log import log as logging
LOG = logging.getLogger(__name__)
CONF = cfg.CONF
DOMAIN = "demo"
logging.register_options(CONF)
logging.setup(CONF, DOMAIN)
# Oslo Logging uses INFO as default
LOG.info("Oslo Logging")
LOG.warning("Oslo Logging")
LOG.error("Oslo Logging")

usage.py

# Copyright (c) 2016 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""A usage example of Oslo Logging
This example requires the following package to be installed.
$ pip install oslo.log
Additional Oslo packages installed include oslo.config, oslo.context,
oslo.i18n, oslo.serialization and oslo.utils.
More information about Oslo Logging can be found at:


  https://docs.openstack.org/oslo.log/latest/user/index.html
"""
from oslo_config import cfg
from oslo_log import log as logging
LOG = logging.getLogger(__name__)
CONF = cfg.CONF
DOMAIN = 'demo'
def prepare():


    """Prepare Oslo Logging (2 or 3 steps)


    Use of Oslo Logging involves the following:


    * logging.register_options


    * logging.set_defaults (optional)


    * logging.setup


    """


    # Required step to register common, logging and generic configuration


    # variables


    logging.register_options(CONF)


    # Optional step to set new defaults if necessary for


    # * logging_context_format_string


    # * default_log_levels


    #


    # These variables default to respectively:


    #


    #  import oslo_log


    #  oslo_log._options.DEFAULT_LOG_LEVELS


    #  oslo_log._options.log_opts[0].default


    #


    extra_log_level_defaults = [


        'dogpile=INFO',


        'routes=INFO'


        ]


    logging.set_defaults(


        default_log_levels=logging.get_default_log_levels() +


        extra_log_level_defaults)


    # Required setup based on configuration and domain


    logging.setup(CONF, DOMAIN)
if __name__ == '__main__':


    prepare()


    # NOTE: These examples do not demonstration Oslo i18n messages


    LOG.info("Welcome to Oslo Logging")


    LOG.debug("A debugging message")


    LOG.warning("A warning occurred")


    LOG.error("An error occurred")


    try:


        raise Exception("This is exceptional")


    except Exception:


        LOG.exception("An Exception occurred")

usage_helper.py

# Copyright (c) 2016 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""A usage example with helper debugging of minimum Oslo Logging
This example requires the following package to be installed.
$ pip install oslo.log
Additional Oslo packages installed include oslo.config, oslo.context,
oslo.i18n, oslo.serialization and oslo.utils.
More information about Oslo Logging can be found at:


  https://docs.openstack.org/oslo.log/latest/user/index.html
"""
# Use default Python logging to display running output
import logging as py_logging
from oslo_config import cfg
from oslo_log import log as logging
LOG = py_logging.getLogger(__name__)
CONF = cfg.CONF
DOMAIN = "demo"
def prepare():


    """Prepare Oslo Logging (2 or 3 steps)


    Use of Oslo Logging involves the following:


    * logging.register_options


    * logging.set_defaults (optional)


    * logging.setup


    """


    LOG.debug("Prepare Oslo Logging")


    LOG.info("Size of configuration options before %d", len(CONF))


    # Required step to register common, logging and generic configuration


    # variables


    logging.register_options(CONF)


    LOG.info("Size of configuration options after %d", len(CONF))


    # Optional step to set new defaults if necessary for


    # * logging_context_format_string


    # * default_log_levels


    #


    # These variables default to respectively:


    #


    #  import oslo_log


    #  oslo_log._options.DEFAULT_LOG_LEVELS


    #  oslo_log._options.log_opts[0].default


    #


    custom_log_level_defaults = logging.get_default_log_levels() + [


        'dogpile=INFO',


        'routes=INFO'


        ]


    logging.set_defaults(default_log_levels=custom_log_level_defaults)


    # NOTE: We cannot show the contents of the CONF object


    # after register_options() because accessing this caches


    # the default_log_levels subsequently modified with set_defaults()


    LOG.info("List of Oslo Logging configuration options and current values")


    LOG.info("=" * 80)


    for c in CONF:


        LOG.info("{} = {}".format(c, CONF[c]))


    LOG.info("=" * 80)


    # Required setup based on configuration and domain


    logging.setup(CONF, DOMAIN)
if __name__ == '__main__':


    py_logging.basicConfig(level=py_logging.DEBUG)


    prepare()


    # NOTE: These examples do not demonstration Oslo i18n messages


    LOG.info("Welcome to Oslo Logging")


    LOG.debug("A debugging message")


    LOG.warning("A warning occurred")


    LOG.error("An error occurred")


    try:


        raise Exception("This is exceptional")


    except Exception:


        LOG.exception("An Exception occurred")

usage_context.py

# Copyright (c) 2016 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""A usage example of Oslo Logging with context
This example requires the following package to be installed.
$ pip install oslo.log
Additional Oslo packages installed include oslo.config, oslo.context,
oslo.i18n, oslo.serialization and oslo.utils.
More information about Oslo Logging can be found at:


  https://docs.openstack.org/oslo.log/latest/user/index.html


  https://docs.openstack.org/oslo.context/latest/user/index.html
"""
from oslo_config import cfg
from oslo_context import context
from oslo_log import log as logging
LOG = logging.getLogger(__name__)
CONF = cfg.CONF
DOMAIN = 'demo'
def prepare():


    """Prepare Oslo Logging (2 or 3 steps)


    Use of Oslo Logging involves the following:


    * logging.register_options


    * logging.set_defaults (optional)


    * logging.setup


    """


    # Required step to register common, logging and generic configuration


    # variables


    logging.register_options(CONF)


    # Optional step to set new defaults if necessary for


    # * logging_context_format_string


    # * default_log_levels


    #


    # These variables default to respectively:


    #


    #  import oslo_log


    #  oslo_log._options.DEFAULT_LOG_LEVELS


    #  oslo_log._options.log_opts[0].default


    #


    extra_log_level_defaults = [


        'dogpile=INFO',


        'routes=INFO'


        ]


    logging.set_defaults(


        default_log_levels=logging.get_default_log_levels() +


        extra_log_level_defaults)


    # Required setup based on configuration and domain


    logging.setup(CONF, DOMAIN)
if __name__ == '__main__':


    prepare()


    LOG.info("Welcome to Oslo Logging")


    LOG.info("Without context")


    context.RequestContext(user='6ce90b4d',


                           tenant='d6134462',


                           domain='a6b9360e')


    LOG.info("With context")

Logging Guidelines

NOTE:

Many of these guidelines were originally authored as a cross-project spec.

Motivation

A consistent, unified logging format will better enable cloud administrators to monitor and maintain their environments. Therefore this document provides guidelines for best practices regarding how developers should use logging within their code.

Adding Variables to Log Messages

String interpolation should be delayed to be handled by the logging code, rather than being done at the point of the logging call. For example, do not do this:

# WRONG
LOG.info('some message: variable=%s' % variable)

Instead, use this style:

# RIGHT
LOG.info('some message: variable=%s', variable)

This allows the logging package to skip creating the formatted log message if the message is not going to be emitted because of the current log level.

Definition of Log Levels

NOTE:

The following definitions were originally taken from a popular answer on StackOverflow.

DEBUG: Shows everything and is likely not suitable for normal production operation due to the sheer size of logs generated.
INFO: Usually indicates successful service start/stop, versions and such non-error related data. This should include largely positive units of work that are accomplished (such as starting a compute service, creating a user, deleting a volume, etc.).
AUDIT: This should not be used. All previous messages at AUDIT level should be changed to INFO, or sent as notifications to a notification queue. (The origin of AUDIT was a NASA-specific requirement which led to confusion/misuse and is no longer relevant to the current code.)
WARNING: Indicates that there might be a systemic issue; potential predictive failure notice.
ERROR: An error has occurred and an administrator should research the event.
CRITICAL: An error has occurred and the system might be unstable; administrator attention is required immediately.

Log levels from an operator perspective

We can think of this from an operator perspective the following ways (Note: we are not specifying operator policy here, just trying to set tone for developers that aren't familiar with how these messages will be interpreted):

CRITICAL: ZOMG! Cluster on FIRE! Call all pagers, wake up everyone. This is an unrecoverable error with a service that has or probably will lead to service death or massive degradation.
ERROR: Serious issue with cloud: administrator should be notified immediately via email/pager. On call people expected to respond.
WARNING: Something is not right; should get looked into during the next work week. Administrators should be working through eliminating warnings as part of normal work.
INFO: Normal status messages showing measurable units of positive work passing through under normal functioning of the system. Should not be so verbose as to overwhelm real signal with noise. Should not be continuous "I'm alive!" messages. See Log messages at INFO and above should represent a "unit of work" for more details.
DEBUG: Developer logging level. Only enable if you are interested in reading through a ton of additional information about what is going on. See Debugging start / end messages for more details.
TRACE: In functions which support this level, details every parameter and operation to help diagnose subtle bugs. This should only be enabled for specific areas of interest or the log volume will be overwhelming. Some system performance degradation should be expected.

Overall logging principles

The following principles should apply to all messages.

Debugging start / end messages

At the DEBUG log level it is often extremely important to flag the beginning and ending of actions to track the progression of flows (which might error out before the unit of work is completed).

This should be made clear by there being a "starting" message with some indication of completion for that starting point.

In a real OpenStack environment lots of things are happening in parallel. There are multiple workers per services, multiple instances of services in the cloud.

Log messages at INFO and above should represent a "unit of work"

The INFO log level is defined as: "normal status messages showing measurable units of positive work passing through under normal functioning of the system."

A measurable unit of work should be describable by a short sentence fragment, in the past tense with a noun and a verb of something significant.

Examples:

Instance spawned
Instance destroyed
Volume attached
Image failed to copy

Words like "started", "finished", or any verb ending in "ing" are flags for non unit of work messages.

Examples of good and bad uses of INFO

Below are some examples of good and bad uses of INFO. In the good examples we can see the 'noun / verb' fragment for a unit of work. "Successfully" is probably superfluous and could be removed.

Good

2014-01-26 15:36:10.597 28297 INFO nova.virt.libvirt.driver [-]
[instance: b1b8e5c7-12f0-4092-84f6-297fe7642070] Instance spawned
successfully.
2014-01-26 15:36:14.307 28297 INFO nova.virt.libvirt.driver [-]
[instance: b1b8e5c7-12f0-4092-84f6-297fe7642070] Instance destroyed
successfully.

In the bad examples we see trace-level thinking put into messages at INFO level and above:

Bad

2014-01-26 15:36:11.198 INFO nova.virt.libvirt.driver
[req-ded67509-1e5d-4fb2-a0e2-92932bba9271
FixedIPsNegativeTestXml-1426989627 FixedIPsNegativeTestXml-38506689]
[instance: fd027464-6e15-4f5d-8b1f-c389bdb8772a] Creating image
2014-01-26 15:36:11.525 INFO nova.virt.libvirt.driver
[req-ded67509-1e5d-4fb2-a0e2-92932bba9271
FixedIPsNegativeTestXml-1426989627 FixedIPsNegativeTestXml-38506689]
[instance: fd027464-6e15-4f5d-8b1f-c389bdb8772a] Using config drive
2014-01-26 15:36:12.326 AUDIT nova.compute.manager
[req-714315e2-6318-4005-8f8f-05d7796ff45d FixedIPsTestXml-911165017
FixedIPsTestXml-1315774890] [instance:
b1b8e5c7-12f0-4092-84f6-297fe7642070] Terminating instance
2014-01-26 15:36:12.570 INFO nova.virt.libvirt.driver
[req-ded67509-1e5d-4fb2-a0e2-92932bba9271
FixedIPsNegativeTestXml-1426989627 FixedIPsNegativeTestXml-38506689]
[instance: fd027464-6e15-4f5d-8b1f-c389bdb8772a] Creating config
drive at
/opt/stack/data/nova/instances/fd027464-6e15-4f5d-8b1f
-c389bdb8772a/disk.config

This is mostly an overshare issue. At INFO, these are stages that don't really need to be fully communicated.

Messages shouldn't need a secret decoder ring

Bad

2014-01-26 15:36:14.256 28297 INFO nova.compute.manager [-]
Lifecycle event 1 on VM b1b8e5c7-12f0-4092-84f6-297fe7642070

As a general rule, when using constants or enums, ensure they are translated back to user strings prior to being sent to the user.

Specific event types

In addition to the above guidelines very specific additional recommendations exist. These are guidelines rather than hard rules to be adhered to, so common sense should always be exercised.

WSGI requests

Should be logged at INFO level.
Should be logged exactly once per request.
Should include enough information to know what the request was (but not so much as to overwhelm the logs).

The last point is notable, because some POST API requests don't include enough information in the URL alone to determine what the API did. For instance, Nova server actions (where POST includes a method name), although including POST request payloads could be excessive, so common sense should be exercised.

Rationale: Operators should be able to easily see what API requests their users are making in their cloud to understand the usage patterns of their users with their cloud.

Operator deprecation warnings

Should be logged at WARN level.
Where possible, should be logged exactly once per service start (not on every request through code). However it may be tricky to keep track of whether a warning was already issued, so common sense should dictate the best approach.
Should include directions on what to do to migrate from the deprecated state.

Rationale: Operators need to know that some aspect of their cloud configuration is now deprecated, and will require changes in the future. And they need enough of a bread crumb trail to figure out how to do that.

REST API deprecation warnings

Should not be logged any higher than DEBUG, since these are not operator-facing messages.
Should be logged no more than once per REST API usage / tenant, definitely not on every REST API call.

Rationale: The users of the REST API don't have access to the system logs. Therefore logging at a WARNING level is telling the wrong people about the fact that they are using a deprecated API.

Deprecation of user-facing APIs should be communicated via user-facing mechanisms, e.g. API change notes associated with new API versions.

Stacktraces in logs

Should be exceptional events, for unforeseeable circumstances that are not yet recoverable by the system.
Should be logged at ERROR level.
Should be considered high priority bugs to be addressed by the development team.

Rationale: The current behavior of OpenStack is extremely stack trace happy. Many existing stack traces in the logs are considered normal. This dramatically increases the time to find the root cause of real issues in OpenStack.

Logging by non-OpenStack components

OpenStack uses a ton of libraries, which have their own definitions of logging. This causes a lot of extraneous information in normal logs by wildly different definitions of those libraries.

As such, all 3rd party libraries should have their logging levels adjusted so only real errors are logged.

Currently proposed settings for 3rd party libraries:

amqp=WARN
boto=WARN
qpid=WARN
sqlalchemy=WARN
suds=INFO
iso8601=WARN
requests.packages.urllib3.connectionpool=WARN
urllib3.connectionpool=WARN

Testing

See tests provided by https://blueprints.launchpad.net/nova/+spec/clean-logs

References

Security Log Guidelines - https://wiki.openstack.org/wiki/Security/Guidelines/logging_guidelines
Wiki page for basic logging standards proposal developed early in Icehouse - https://wiki.openstack.org/wiki/LoggingStandards
Apache Log4j levels (which many tools work with) - https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html

CHANGES

7.1.0

Skip installation to speed up pep8
deprecate eventlet monkey patch within oslo.log
Fix outdated envlist

7.0.0

Skip grenade job for doc update
Support running tests w/eventlet monkey patching
reno: Update master for unmaintained/2023.1
Add missing contextmanager interfaces to PipeMutex

6.2.0

Add note about requirements lower bounds
Skip functional tests on pre-commit config update
Remove Python 3.8 support
Run pyupgrade to clean up Python 2 syntaxes
Remove windows support
Fix outdated tox minversion
Declare Python 3.12 support
Remove usage of deprecated RequestContext attributes
Update master for stable/2024.2

6.1.2

•: Mock time.time_ns in test_rfc5424_isotime_format_no_microseconds for py3.13

6.1.1

•: Revert "Remove the usage of the Eventlet debug feature from oslo.log."

6.1.0

Replace deprecated logging.warn() calls with logging.warning()
add a missing link to the release note
Remove the usage of the Eventlet debug feature from oslo.log

6.0.0

Remove unused pyinotify
Remove old excludes
Remove implementation for watch_log_file
Apply eventlet workaround only once
Deprecate watch_log_file
Remove fallback for old oslo.context
Add option to disable color
Fix broken reference to rate_limit_except_level
Validate rate_limit_except_level by choices
Imported Translations from Zanata
Fix eventlet detection
Update master for stable/2024.1
reno: Update master for unmaintained/victoria

5.5.0

pre-commit: Integrate bandit
pre-commit: Bump versions
Bump hacking
Update python classifier in setup.cfg

5.4.0

Deprecate Windows support
Update master for stable/2023.2

5.3.0

Catch RuntimeError when loading log config file
Bump bandit
Imported Translations from Zanata
Revert "Moves supported python runtimes from version 3.8 to 3.10"
Moves supported python runtimes from version 3.8 to 3.10
Update master for stable/2023.1
Imported Translations from Zanata

5.1.0

tox - fix allowlist_external issues
Cleanup py27 support

5.0.2

•: Make the eventlet logging fix execution conditional

5.0.1

•: Fix logging in eventlet native threads

5.0.0

[Fix] init global_request_id if not in context
Drop python3.6/3.7 support in testing runtime

4.8.0

Log Global Request IDs by default
Add system scope information to default user identity string
Update CI to use unversioned jobs template
Add Zed in versionutils
Add Python3 yoga unit tests
Fix formatting of release list

4.7.0

Add Yoga to versionutils
Use project when logging the user identity
Update python testing classifier

4.6.1

•: Replace deprecated arguments of RequestContext

4.6.0

Ussuri+ is python3 only
setup.cfg: Replace dashes with underscores
Remove references to 'sys.version_info'

4.5.0

Drop lower-constraints
Fix log_rotate_interval help text formatting
Move flake8 as a pre-commit local target
Add Xena to versionutils
remove unicode from code
Dropping lower constraints testing
Use TOX_CONSTRAINTS_FILE
Use py3 as the default runtime for tox
Imported Translations from Zanata
Add Python3 wallaby unit tests
Update master for stable/victoria
Adding pre-commit

4.4.0

zuul: port the legacy grenade job
Bump bandit version
Added uwsgi_name information into fluentFormatter event message

4.3.0

•: Add Victoria and Wallaby in versionutils.deprecated

4.2.1

Stop to use the __future__ module
Default facility to None in OSJournalHandler class

4.2.0

Switch to newer openstackdocstheme and reno versions
Remove the unused coding style modules
Remove translation sections from setup.cfg
Add missing SYSLOG_FACILITY to JournalHandler
Remove monotonic usage
Align contributing doc with oslo's policy
Bump default tox env from py37 to py38
Add py38 package metadata
Add release notes links to doc index
Imported Translations from Zanata
Add Python3 victoria unit tests
Update master for stable/ussuri

4.1.1

Use unittest.mock instead of third party mock
drop use of six

4.1.0

•: Add Victoria and Wallaby releases to versionutils

4.0.1

remove outdated header
Switch to hacking 2.x
Stop to build universal wheel
Ignore releasenote artifacts files

4.0.0

Drop python 2.7 support and testing
Drop use of unittest2
tox: Trivial cleanup

3.45.2

•: Always use jsonutils.to_primitive 'fallback' parameter

3.45.1

Serialize complex objects in FluentFormatter
Migrate grenade jobs to py3

3.45.0

tox: Keeping going with docs
Switch to official Ussuri jobs
Update master for stable/train
Add Ussuri release to versionutils

3.44.1

Add Python 3 Train unit tests
Use setLevel instead of setting logger.level directly
Bump the openstackdocstheme extension to 1.20
Blacklist sphinx 2.1.0 (autodoc bug)
Remove incubator migration docs
Modify the constraints url in tox
Add logging guidelines based on previous spec
Fix guidelines w.r.t. translation of log messages
Schedule a periodical check of requirements to catch py2.7 issues quickly

3.44.0

Avoid tox_install.sh for constraints support
Cap bandit below 1.6.0 version and update sphinx and limit monotonic
Replace git.openstack.org URLs with opendev.org URLs

3.43.0

OpenDev Migration Patch
Dropping the py35 testing
Add TRAIN to deprecated releases
Use raw string for regex
Added cmdline information into fluentFormatter event message
Replace openstack.org git:// URLs with https://
Update master for stable/stein

3.42.3

Clarify some config options
Add 'levelkey' + 'tbkey' params

3.42.2

•: Use template for lower-constraints

3.42.1

Default oslo.policy logging to INFO
Update mailinglist from dev to discuss
Fix handling of exc_info in OSJournalHandler
Fix up nits in log rotation change

3.42.0

Add config options for log rotation
Advancing the protocal of the website to HTTPS in usage.rst

3.41.0

Add Windows Event Log handler
Clean up .gitignore references to personal tools
Always build universal wheels
Add devstack job with JSONFormatter configured

3.40.1

Filter args dict in JSONFormatter
add lib-forward-testing-python3 test job
add python 3.6 unit test job
rewrite tests to not rely on implementation details of logging module
import zuul job settings from project-config
Follow the new PTI for document build
Migrate to stestr
Fix lower-constraints job
Imported Translations from Zanata
Update reno for stable/rocky

3.39.0

Add release notes link to README
Automatically append reset_color to log lines
fix tox python3 overrides
Provide reset_color key on log record
tox: Group targets and tool configuration together
tox: Don't set basepython in testenv

3.38.1

Fix Formatter subclasses for Python 3.2+
Fix file permissions
Remove stale pip-missing-reqs tox test
Trivial: Update pypi url to new url
Fix sphinx-docs job
set default python to python3

3.38.0

Add Stein release to versionutils
Add ROCKY to deprecated releases
add lower-constraints job
Increase sleep time in testsuite to make it more robust
Updated from global requirements

3.37.0

Add Rocky release to versionutils._RELEASES
Updated from global requirements
Update links in README
Imported Translations from Zanata
Zuul: Remove project name
Imported Translations from Zanata
Zuul: Remove project name
Update reno for stable/queens
Updated from global requirements
Imported Translations from Zanata
update structured logging tests to prove context id is included
Updated from global requirements
Updated from global requirements
Updated from global requirements

3.36.0

Truncate error_summary if exc_info not explicitly passed
Cleanup test-requirements
Updated from global requirements
Imported Translations from Zanata

3.35.0

•: Updated from global requirements

3.34.0

Remove setting of version/release from releasenotes
Updated from global requirements
Capture context in its own key for JSON-based formatters

3.33.0

Updated from global requirements
Remove checks for auth_token in JSON-based formatter tests
Add release note for use_json option
Add option to use JSON formatter
Updated from global requirements
Zuul: add file extension to playbook path
JSONFormatter convert unserializable with repr()

3.32.0

Allow logging of unhashable exceptions in Python 3
Updated from global requirements
Migrate to Zuul v3
Imported Translations from Zanata
Updated from global requirements

3.31.0

Updated from global requirements
Update the documentation link for doc migration
Update the documentation link
Updated from global requirements
Update reno for stable/pike
Updated from global requirements

3.30.0

Updated from global requirements
Update URLs according to document migration
Add missing variable html_last_updated_fmt

3.29.0

Updated from global requirements
switch from oslosphinx to openstackdocstheme
rearrange content to fit the new standard layout
only show error_summary for warning and error messages
Updated from global requirements
Add log.get_loggers method
Updated from global requirements

3.28.1

•: do not add error_summary for debug log messages

3.28.0

Updated from global requirements
formatter: skip ImportError when adding error_summary
Updated from global requirements

3.27.0

Updated from global requirements
Fix bug in log_method_call decorator
clarify release note for error summary handling
fix test description comment
Updated from global requirements
Oslo i18n 3.15.2 has broken deps
Remove deprecated module loggers
Updated from global requirements
add line number information to fluentd formatter
add error_summary support for fluentd formatter
add error_summary support to JSONFormatter
refactor error summary logic so it can be reused
improve the documentation for log format strings
skip built-in exceptions when adding error_summary
make handling of error_summary more flexible
add exception summaries to the main log line
Updated from global requirements

3.26.1

•: Use dict arg values for unicode checks in ContextFormatter

3.26.0

Add oslo_messaging to the list of log levels
Add additional info like python-systemd does

3.25.0

Fix syslog module usage breaking Windows compatibility
Updated from global requirements

3.24.0

add an extras dependency for systemd
Optimize the link address
Always create OSSysLogHandler
protect systemd class initialization when syslog is not available
Documentation for journal usage
Systemd native journal support
When record.args is None, it should not give an exception

3.23.0

Trivial: Remove testscenarios from test-requirements.txt
Check reStructuredText documents for common style issues
Use Sphinx 1.5 warning-is-error
Fix some reST field lists in docstrings
Remove log translations

3.22.0

Updated from global requirements
Remove 'verbose' option (again)

3.21.0

Added is_debug_enabled helper
Updated from global requirements
[Fix gate]Update test requirement
Revert "Remove 'verbose' option (again)"
Updated from global requirements
Remove support for py34
pbr.version.VersionInfo needs package name (oslo.xyz and not oslo_xyz)
tail support, log filtering, executable, and splitlines bug fix
Must not go underneath the context object and access __dict__
Fix devstack colors
Update reno for stable/ocata
Remove 'verbose' option (again)
Remove references to Python 3.4

3.20.0

Replace method attr in vars() to hasattr
Add Constraints support

3.19.0

Avoid converting to unicode if not needed
Show team and repo badges on README

3.18.0

Updated from global requirements
Updated from global requirements
Updated from global requirements
Imported Translations from Zanata

3.17.0

Modify use of assertTrue(A in B)
Change assertTrue(isinstance()) by optimal assert
Add a json reformatter command
Enable release notes translation
Add support for P and Q release names
Updated from global requirements
Updated from global requirements
modify the home-page info with the developer documentation
Add a filter to rate limit logs
Implement FluentFormatter
Fix races in unit tests
standardize release note page ordering
Use six.wraps instead of functools
Update reno for stable/newton
Updated from global requirements
Fix typos

3.16.0

Updated from global requirements
Default use_stderr to False

3.15.0

3.14.0

Updated from global requirements
Updated from global requirements
Fixes unit tests on Windows

3.13.0

Updated from global requirements
Fix parameters of assertEqual are misplaced
Updated from global requirements
Remove discover from test-requirements
Add Python 3.5 classifier and venv

3.12.0

Replace "LOG.exception(_" with "LOG.exception(_LE"
Updated from global requirements
Reload log_config_append config on SIGHUP
Imported Translations from Zanata
Updated from global requirements
log: Introduce _iter_loggers
Imported Translations from Zanata
Updated from global requirements
Updated from global requirements

3.11.0

3.10.0

Updated from global requirements
Provide a normal method for deprecation warnings

3.9.0

Updated from global requirements
Make available to log encoded strings as arguments
Updated from global requirements
Fix typo: 'Olso' to 'Oslo'
Updated from global requirements
Convert unicode data to utf-8 before calling syslog.syslog()
log: don't create foo.log
Updated from global requirements
Use new logging specific method for context info
Reduce READ_FREQ and TIMEOUT for watch-file

3.8.0

Revert "Remove 'verbose' option"
Fix regression causing the default log level to become WARNING
Remove 'verbose' option

3.7.0

Fix example issue
Updated from global requirements
Allow reload of 'debug' option

3.6.0

•: Imported Translations from Zanata

3.5.0

•: Remove direct dependency on babel

3.4.0

Updated from global requirements
Updated from global requirements
Updated from global requirements
Remove outdated comment in ContextFormatter
Enable log_method_call to work on static method
Explicitly exclude tests from bandit scan
Improve olso.log test coverage for edge cases
Improve test code coverage of _options
Update reno for stable/mitaka
Unit test cleanup and validation improvements
Added +2 release names for versionutils
Fix broken links in docs usage page
Enable bandit in gate
Updated from global requirements

3.2.0

use log.warning instead of log.warn
Imported Translations from Zanata
Updated from global requirements
Remove deprecated use-syslog-rfc-format option

3.1.0

Add release note for removed log_format option
Updated from global requirements
add page for release notes for unreleased versions
add a release note about using reno

3.0.0

Add reno for release notes management
remove pypy from default tox environment list
stop making a copy of options discovered by config generator
always run coverage report
Remove bandit.yaml in favor of defaults

2.4.0

Updated from global requirements
Fix spell typos
set oslo.cache and dogpile to INFO
Update translation setup
Updated from global requirements
Updated from global requirements
Updated from global requirements
Imported Translations from Zanata
Updated from global requirements
Improve Logging docs with inline examples and context example
Revert "Pass environment variables of proxy to tox"
Clean up removed hacking rule from [flake8] ignore lists
Provide a deprecated_reason for use_syslog_rfc_format
Remove deprecated log-format option

2.3.0

Improve documentataion of Oslo Log Usage
Added public method to getting default log levels
Updated from global requirements
enable isotime for exceptions
assertIsNone(val) instead of assertEqual(None,val)

2.2.0

Set keystoneauth default log level to WARN
Add ISO8601/RFC3339 timestamp to ContextFormatter
Format record before passing it to syslog
Updated from global requirements
Pass environment variables of proxy to tox
Updated from global requirements
Trival: Remove 'MANIFEST.in'

2.1.0

Remove iso8601 dependency
Remove duplicated profiles section from bandit.yaml
test_logging_error: build a logger at the test level
Cleanup all handlers in _setup_logging_from_conf
Drop python 2.6 support
Add a 'bandit' target to tox.ini

2.0.0

Updated from global requirements
Log to sys.stderr to avoid "No handlers could be found..."
Remove python 2.6 classifier
Remove python 2.6 and cleanup tox.ini
Refactor Python 2.6 check to use constant

1.14.0

The user_identity format flexibility
Updated from global requirements
Imported Translations from Zanata
Updated from global requirements

1.13.0

Updated from global requirements
Updated from global requirements

1.12.1

•: Allow oslo.log to work on non-linux platforms

1.12.0

Fix coverage configuration and execution
No need for Oslo Incubator Sync
Add hostname field to JSONFormatter
Imported Translations from Zanata
Fix unintended assignment of "syslog"
Make doc title consistent with readme
add documentation with example of an external configuration file
add auto-generated docs for config options
Update option docs for when log config is used
Updated from global requirements
Add optional 'fixture' dependencies
Change ignore-errors to ignore_errors
Fix the home-page value in setup.cfg with openstack.org
FastWatchedFileHandler class was added

1.11.0

Fix poor examples of exception logging
Updated from global requirements
Updated from global requirements

1.10.0

Fix package name for PublishErrorsHandler
Updated from global requirements
Fix duplicate-key pylint issue
Maintain old oslo logger names

1.9.0

Add Mitaka release to versionutils
Update single letter release names to full names
Provide a way to register versionutils options
Imported Translations from Transifex
Updated from global requirements

1.8.0

Set verbose to True and deprecate it
Define TRACE logging level
Imported Translations from Transifex
Updated from global requirements

1.7.0

Imported Translations from Transifex
Add more default fancier formatting params
Updated from global requirements
Updated from global requirements
Updated from global requirements
Do not report deprecations in subclasses
Imported Translations from Transifex
Updated from global requirements
Add tox target to find missing requirements

1.6.0

Remove duplication of fatal_deprecations option
setting taskflow log level to WARN
Imported Translations from Transifex

1.5.0

Updated from global requirements
Updated from global requirements
Switch badges from 'pypip.in' to 'shields.io'
Deprecate use-syslog-rfc-format for removal

1.4.0

1.3.0

Do not fail if syslog is not available
Allow integer logging levels

1.2.0

Use proper deprecation for use-syslog-rfc-format option
Replace RFCSysLogHandler by a syslog() based one
Make remove_in=0 (no removal) use a better syntax
Remove is_compatible from versionutils
Add versionutils options to list_opts
Add versionutils to API documentation
Advertise support for Python3.4 / Remove support for Python 3.3
Updated from global requirements
Updated from global requirements
Remove run_cross_tests.sh
Deprecate WritableLogger - used for eventlet logging
Log deprecation message when catching deprecated exceptions
Change misleading TRACE to ERROR

1.1.0

Uncap library requirements for liberty
Provide an API to let tempest control the log file
fix pep8 errors
Add pypi download + version badges
Update to latest hacking
Add link to Logging Guidelines
move versionutils into place
Add liberty release name to versionutils
Expose opts entry point for version_utils
Switch from oslo.config to oslo_config
Remove oslo.log code and clean up versionutils API
Remove code that moved to oslo.i18n
Enhance versionutils.deprecated to work with classes
Add Kilo release name to versionutils
Allow deprecated decorator to specify no plan for removal
Add JUNO as a target to versionutils module
pep8: fixed multiple violations
Use oslotest instead of common test module
Use hacking import_exceptions for gettextutils._
fixed typos
Fix violations of H302:import only modules
Adds decorator to deprecate functions and methods
Remove vim header
Add `versionutils` for version compatibility checks
Default to True for use-syslog-rfc-format
Updated from global requirements
Restore automatic unicode conversion
Add migration notes

1.0.0

•: Updated from global requirements

0.4.0

Pickup instance from log format record
Make use_syslog=True log to syslog via /dev/log

0.3.0

Updated from global requirements
update urllib3.util.retry log level to WARN

0.2.0

Expose fixtures through oslo_log.fixture
Add fixture to let tests change log levels
Rename logging fixture module
Update comment to match implementation
fix link to bug tracker in readme
Updated from global requirements
Update Oslo imports to remove namespace package

0.1.0

Updated from global requirements
Add API documentation
Implement resource to logging extra keywords
Use RequestContext store in oslo_context
Correct the translation domain for loading messages
Correct the position of the syslog handler
Enhance the README a bit
Switch to oslo.context
Move files out of the namespace package
Updated from global requirements
Workflow documentation is now in infra-manual
Added helper decorator to log method arguments
Updated from global requirements
Add oslo.config.opts entry_points in setup.cfg
Updated from global requirements
Updated from global requirements
Activate pep8 check that _ is imported
Add pbr to installation requirements
Updated from global requirements
Updated from global requirements
Remove audit log level
Switch from ContextAdapter to ContextFormatter
Move adapter properties to base class
Add KeywordArgumentAdapter
Remove extraneous vim editor configuration comments
Support building wheels (PEP-427)
Imported Translations from Transifex
Imported Translations from Transifex
Use oslo.utils and oslo.serialization
Fix test env order for testrepository db format
log: add missing space in error message
fix typo and formatting in contributing docs
Updated from global requirements
Remove duplicate test and cleanup unnecessary files
Use fixtures from oslo.i18n and oslo.cfg
Extract WritableLogger from log module
Move handlers and formatters out
Remove dependency on global CONF
switch test from info to error
Test formatting errors with log level being emitted
Imported Translations from Transifex
Simple doc cleanup
Work toward Python 3.4 support and testing
warn against sorting requirements
Make the local module private
Move the option definitions into a private file
Initial translation setup
Fix testr failure under python2.6
Get py27 amd pep8 to work
exported from oslo-incubator by graduate.sh
Set stevedore log level to WARN by default
Add unicode coercion of logged messages to ContextFormatter
Correct coercion of logged message to unicode
Except socket.error if syslog isn't running
Fix E126 pep8 errors
log: make tests portable
Set keystonemiddleware and routes.middleware to log on WARN level
Adjust oslo logging to provide adapter is enabled for
Make logging_context_format_string optional in log.set_defaults
log: make set_defaults() tests clean up properly
Add default log level for websocket
Ability to customize default_log_levels for each project
Python 3: enable tests/unit/test_log.py
Move `mask_password` to strutils
update new requests logger to default WARN
Remove extra whitespace
Use oslo.messaging to publish log errors
pep8: fixed multiple violations
Add a RequestContext.from_dict method
Fix common.log.ContextFormatter for Python 3
Mask passwords included without quotes at the ends of commands
Use moxstubout and mockpatch from oslotest
Fixes a simple spelling mistake
always log a traceback in the sys.excepthook
Remove redundant default=None for config options
Fix logging setup for Python 3.4
Mask passwords that are included in commands
Improve help strings
Remove str() from LOG.* and exceptions
Fix python26 compatibility for RFCSysLogHandler
Use oslotest instead of common test module
Revert setting oslo-incubator logs to INFO
Set default log levels for oslo.messaging and oslo-incubator
Python 3: enable tests/unit/middleware/test_request_id.py
Add default user_identity to logging record
Add model_query() to db.sqlalchemy.utils module
Remove None for dict.get()
Rename Openstack to OpenStack
Fixture to reraise exceptions raised during logging
Emit message which merged user-supplied argument in log_handler
Log unit test improvements
Use ContextFormatter for imparting context info
Fix deprecated messages sent multiple times
default connectionpool to WARN log level
Backport 'ident' from python 3.3 for Oslo's SysLogHandler
remove extra newlines that eventlet seems to add
Small edits on help strings
Add error type to unhandled exception log message
Logging excepthook: print exception info if debug=True
Utilizes assertIsNone and assertIsNotNone
Fix spelling errors in comments
Use hacking import_exceptions for gettextutils._
Correct invalid docstrings
Translation Message improvements
Remove keystone from default_log_levels default
Adding domain to context and log
Unify different names between Python2/3 with six.moves
Remove vim header
Don't log to stdout when log_dir is set
Remove uuidutils imports in oslo modules
Adds admin_password as key to be sanitized when logging
Revert "Removes generate_uuid from uuidutils"
Do not name variables as builtins
Removes generate_uuid from uuidutils
Default iso8601 logging to WARN
Use six.text_type instead of unicode function in tests
Add mask password impl from other projects
Use fileutils.write_to_tempfile in LogConfigTestCase
allow keeping of existing loggers with fileConfig
Add amqp=WARN,qpid=WARN to default_log_levels
Replace assert_ with assertTrue
Don't override default value for eventlet.wsgi.server logging
_get_log_file_path explictly return, when logfile/logdire unset
Make openstack.common.log Python 3 compatible
Make Messages unicode before hitting logging
Adding instance_uuid to context and log
Replace using tests.utils part2
Make a cStringIO usage in test_log py3 compatible
Bump hacking to 0.7.0
Replace using tests.utils with openstack.common.test
Modify local.py to not be dependent on Eventlet
python3: handle module moves in log
Enable H302 hacking check
Add missing license header
Fix bad default for show_deleted
Highlighting the deprecated nature of 'log-format'
Enable hacking H404 test
Enable hacking H402 test
python3: python3 binary/text data compatbility
Enable hacking H403 test
Remove the notifier and its dependencies from log.py
Deprecate log_format and change default to None
oslo logging tries to run chmod on file
Improve Python 3.x compatibility
Support for lazily instantiated loggers
Incorrect logging setup - duplicating root handlers
Replaces the standard uuid with common in the context module
Gracefully handle errors in logging config files
clarify --log-file comments
Include PID in default logging_context_format_string
Initialize root logger in _setup_logging_from_conf()
Fix Copyright Headers - Rename LLC to Foundation
Unignore log_format option
Fix inconsistency with auth_tok/auth_token
Setup exception handler after configuring logging
Use oslo-config-2013.1b3
Don't use subprocess for testing excepthook
Emit a warning if RPC calls made with lock
Replace direct use of testtools BaseTestCase
Use testtools as test base class
Move logging config options into the log module
Fixes import order errors
Verbose should not enable debug level logging
Fix pep8 E125 errors
Improve millisecond logging
Enable millisecond logging by default
Allow nova and others to override some logging defaults
update deprecated stanza
Adjust the logging_context_format_string
Fix the log test so it uses the available context fields
Restore proper LoggerTestCase
move nova.common.deprecated to openstack-common
Use pep8 v1.3.3
Improve logging of process id
Fix meaningless test case
Add multiple-driver support to the notifier api
Install a qualified except hook
Remove code to clear basicConfig root log handlers
don't throw exceptions if %(color)s tag is used
fix bug lp:1019348,update openstack-common to support pep8 1.3
Fix missing gettextutils in several modules
Move get_context_from_function_and_args() to context.py
Switch common files to using jsonutils
Pass in stream as positional argument to StreamHandler
Add common logging and notification
Added dictify() and uuids to the common request context
Add greenthread local storage model from nova
add context 'tests'
make the skeleton project a template
reog from import merge
Add some more generic middleware, request context, utils, and versioning. Add basic template for server binary
Initial skeleton project

oslo.log API Reference

oslo_log.fixture

oslo_log.fixture.get_logging_handle_error_fixture(): returns a fixture to make logging raise formatting exceptions.
To use:

from oslo_log import fixture as log_fixture
self.useFixture(log_fixture.get_logging_handle_error_fixture())

class oslo_log.fixture.SetLogLevel(logger_names, level): Override the log level for the named loggers, restoring their previous value at the end of the test.
To use:

from oslo_log import fixture as log_fixture
self.useFixture(log_fixture.SetLogLevel(['myapp.foo'], logging.DEBUG))

Parameters

logger_names (list(str)) -- Sequence of logger names, as would be passed to getLogger().
level (int) -- Logging level, usually one of logging.DEBUG, logging.INFO, etc.

oslo_log.formatters

class oslo_log.formatters.ContextFormatter(*args, **kwargs)

Bases: Formatter

A context.RequestContext aware formatter configured through flags.

The flags used to set format strings are: logging_context_format_string and logging_default_format_string. You can also specify logging_debug_format_suffix to append extra formatting if the log level is debug.

The standard variables available to the formatter are listed at: http://docs.python.org/library/logging.html#formatter

In addition to the standard variables, one custom variable is available to both formatting string: isotime produces a timestamp in ISO8601 format, suitable for producing RFC5424-compliant log messages.

Furthermore, logging_context_format_string has access to all of the data in a dict representation of the context.

format(record): Uses contextstring if request_id is set, otherwise default.

formatException(exc_info, record=None): Format exception output with CONF.logging_exception_prefix.

class oslo_log.formatters.FluentFormatter(fmt=None, datefmt=None, style='%s')

Bases: Formatter

A formatter for fluentd.

format() returns dict, not string. It expects to be used by fluent.handler.FluentHandler. (included in fluent-logger-python)

Added in version 3.17.

format(record): Format the specified record as text.
The record's attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

formatException(exc_info, strip_newlines=True): Format and return the specified exception information as a string.
This default implementation just uses traceback.print_exception()

class oslo_log.formatters.JSONFormatter(fmt=None, datefmt=None, style='%'): Bases: Formatter

format(record): Format the specified record as text.
The record's attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

formatException(ei, strip_newlines=True): Format and return the specified exception information as a string.
This default implementation just uses traceback.print_exception()

oslo_log.handlers

class oslo_log.handlers.ColorHandler(stream=None)

Bases: StreamHandler

Log handler that sets the 'color' key based on the level

To use, include a '%(color)s' entry in the logging_context_format_string. There is also a '%(reset_color)s' key that can be used to manually reset the color within a log line.

LEVEL_COLORS = {5: '\x1b[00;35m', 10: '\x1b[00;32m', 20: '\x1b[00;36m', 21: '\x1b[01;36m', 30: '\x1b[01;33m', 40: '\x1b[01;31m', 50: '\x1b[01;31m'}

format(record): Format the specified record.
If a formatter is set, use it. Otherwise, use the default formatter for the module.

class oslo_log.handlers.OSJournalHandler(facility=None): Bases: Handler

custom_fields = ('project_name', 'project_id', 'user_name', 'user_id', 'request_id')

emit(record): Do whatever it takes to actually log the specified logging record.
This version is intended to be implemented by subclasses and so raises a NotImplementedError.

class oslo_log.handlers.OSSysLogHandler(facility=None): Bases: Handler
Syslog based handler. Only available on UNIX-like platforms.

emit(record): Do whatever it takes to actually log the specified logging record.
This version is intended to be implemented by subclasses and so raises a NotImplementedError.

oslo_log.helpers

Log helper functions.

oslo_log.helpers.log_method_call(method): Decorator helping to log method calls.

Parameters: method (method definition) -- Method to decorate to be logged.

oslo_log.log

OpenStack logging handler.

This module adds to logging functionality by adding the option to specify a context object when calling the various log methods. If the context object is not specified, default formatting is used. Additionally, an instance uuid may be passed as part of the log message, which is intended to make it easier for admins to find messages related to a specific instance.

It also allows setting of formatting information through conf.

class oslo_log.log.BaseLoggerAdapter(logger, extra=None): Bases: LoggerAdapter

property handlers

trace(msg, *args, **kwargs)

warn(msg, *args, **kwargs): Delegate a warning call to the underlying logger.

class oslo_log.log.KeywordArgumentAdapter(logger, extra=None)

Bases: BaseLoggerAdapter

Logger adapter to add keyword arguments to log record's extra data

Keywords passed to the log call are added to the "extra" dictionary passed to the underlying logger so they are emitted with the log message and available to the format string.

Special keywords:

extra: An existing dictionary of extra values to be passed to the logger. If present, the dictionary is copied and extended.
resource

A dictionary-like object containing a name key or type: and id keys.

process(msg, kwargs): Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs.
Normally, you'll only need to override this one method in a LoggerAdapter subclass for your specific needs.

exception oslo_log.log.LogConfigError(log_config, err_msg): Bases: Exception

message = 'Error loading logging config %(log_config)s: %(err_msg)s'

oslo_log.log.getLogger(name=None, project='unknown', version='unknown'): Build a logger with the given name.

Parameters

name (string) -- The name for the logger. This is usually the module name, __name__.
project (string) -- The name of the project, to be injected into log messages. For example, 'nova'.
version (string) -- The version of the project, to be injected into log messages. For example, '2014.2'.

oslo_log.log.get_default_log_levels(): Return the Oslo Logging default log levels.
Returns a copy of the list so an application can change the value and not affect the default value used in the log_opts configuration setup.

oslo_log.log.get_loggers(): Return a copy of the oslo loggers dictionary.

oslo_log.log.is_debug_enabled(conf): Determine if debug logging mode is enabled.

oslo_log.log.register_options(conf): Register the command line and configuration options used by oslo.log.

oslo_log.log.set_defaults(logging_context_format_string=None, default_log_levels=None): Set default values for the configuration options used by oslo.log.

oslo_log.log.setup(conf, product_name, version='unknown', *, fix_eventlet=True): Setup logging for the current application.

oslo_log.log.tempest_set_log_file(filename): Provide an API for tempest to set the logging filename.
WARNING:

Only Tempest should use this function.

We don't want applications to set a default log file, so we don't want this in set_defaults(). Because tempest doesn't use a configuration file we don't have another convenient way to safely set the log file default.

SEE ALSO:

Using oslo.log

oslo_log.versionutils

Helpers for comparing version strings.

exception oslo_log.versionutils.DeprecatedConfig(msg)

class oslo_log.versionutils.deprecated(as_of, in_favor_of=None, remove_in=2, what=None)

A decorator to mark callables as deprecated.

This decorator logs a deprecation message when the callable it decorates is used. The message will include the release where the callable was deprecated, the release where it may be removed and possibly an optional replacement. It also logs a message when a deprecated exception is being caught in a try-except block, but not when subclasses of that exception are being caught.

Examples:

1.: Specifying the required deprecated release

>>> @deprecated(as_of=deprecated.ICEHOUSE)
... def a(): pass

2.: Specifying a replacement:

>>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of='f()')
... def b(): pass

3.: Specifying the release where the functionality may be removed:

>>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=+1)
... def c(): pass

4.: Specifying the deprecated functionality will not be removed:

>>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=None)
... def d(): pass

5.: Specifying a replacement, deprecated functionality will not be removed:

>>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of='f()',
...             remove_in=None)
... def e(): pass

WARNING:

The hook used to detect when a deprecated exception is being caught does not work under Python 3. Deprecated exceptions are still logged if they are thrown.

oslo_log.versionutils.deprecation_warning(what, as_of, in_favor_of=None, remove_in=2, logger=<Logger oslo_log.versionutils (WARNING)>): Warn about the deprecation of a feature.

Parameters

what -- name of the thing being deprecated.
as_of -- the release deprecating the callable.
in_favor_of -- the replacement for the callable (optional)
remove_in -- an integer specifying how many releases to wait before removing (default: 2)
logger -- the logging object to use for reporting (optional).

oslo_log.versionutils.register_options(): Register configuration options used by this library.

oslo_log.versionutils.report_deprecated_feature(logger, msg, *args, **kwargs)

Call this function when a deprecated feature is used.

If the system is configured for fatal deprecations then the message is logged at the 'critical' level and DeprecatedConfig will be raised.

Otherwise, the message will be logged (once) at the 'warn' level.

Raises: DeprecatedConfig if the system is configured for fatal deprecations.

Configuration Options

oslo.log uses oslo.config to define and manage configuration options to allow the deployer to control how an application's logs are handled.

DEFAULT

debug

Type: boolean
Default: False
Mutable: This option can be changed without restarting.

If set to true, the logging level will be set to DEBUG instead of the default INFO level.

log_config_append

Type: string
Default: <None>
Mutable: This option can be changed without restarting.

The name of a logging configuration file. This file is appended to any existing logging configuration files. For details about logging configuration files, see the Python logging module documentation. Note that when logging configuration files are used then all logging configuration is set in the configuration file and other logging configuration options are ignored (for example, log-date-format).

Deprecated Variations

Group	Name
DEFAULT	log-config
DEFAULT	log_config

log_date_format

Type: string
Default: %Y-%m-%d %H:%M:%S

Defines the format string for %(asctime)s in log records. Default: the value above . This option is ignored if log_config_append is set.

log_file

Type: string
Default: <None>

(Optional) Name of log file to send logging output to. If no default is set, logging will go to stderr as defined by use_stderr. This option is ignored if log_config_append is set.

Deprecated Variations

Group	Name
DEFAULT	logfile

log_dir

Type: string
Default: <None>

(Optional) The base directory used for relative log_file paths. This option is ignored if log_config_append is set.

Deprecated Variations

Group	Name
DEFAULT	logdir

watch_log_file

Type: boolean
Default: False

Uses logging handler designed to watch file system. When log file is moved or removed this handler will open a new log file with specified path instantaneously. It makes sense only if log_file option is specified and Linux platform is used. This option is ignored if log_config_append is set.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.

Reason: This function is known to have bene broken for long time, and depends on the unmaintained library

use_syslog

Type: boolean
Default: False

Use syslog for logging. Existing syslog format is DEPRECATED and will be changed later to honor RFC5424. This option is ignored if log_config_append is set.

use_journal

Type: boolean
Default: False

Enable journald for logging. If running in a systemd environment you may wish to enable journal support. Doing so will use the journal native protocol which includes structured metadata in addition to log messages.This option is ignored if log_config_append is set.

syslog_log_facility

Type: string
Default: LOG_USER

Syslog facility to receive log lines. This option is ignored if log_config_append is set.

use_json

Type: boolean
Default: False

Use JSON formatting for logging. This option is ignored if log_config_append is set.

use_stderr

Type: boolean
Default: False

Log output to standard error. This option is ignored if log_config_append is set.

log_color

Type: boolean
Default: False

(Optional) Set the 'color' key according to log levels. This option takes effect only when logging to stderr or stdout is used. This option is ignored if log_config_append is set.

log_rotate_interval

Type: integer
Default: 1

The amount of time before the log files are rotated. This option is ignored unless log_rotation_type is set to "interval".

log_rotate_interval_type

Type: string
Default: days
Valid Values: Seconds, Minutes, Hours, Days, Weekday, Midnight

Rotation interval type. The time of the last file change (or the time when the service was started) is used when scheduling the next rotation.

max_logfile_count

Type: integer
Default: 30

Maximum number of rotated log files.

max_logfile_size_mb

Type: integer
Default: 200

Log file maximum size in MB. This option is ignored if "log_rotation_type" is not set to "size".

log_rotation_type

Type: string
Default: none
Valid Values: interval, size, none

Log rotation type.

Possible values

interval: Rotate logs at predefined time intervals.
size: Rotate logs once they reach a predefined size.
none: Do not rotate log files.

logging_context_format_string

Type: string
Default: %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [%(global_request_id)s %(request_id)s %(user_identity)s] %(instance)s%(message)s

Format string to use for log messages with context. Used by oslo_log.formatters.ContextFormatter

logging_default_format_string

Type: string
Default: %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [-] %(instance)s%(message)s

Format string to use for log messages when context is undefined. Used by oslo_log.formatters.ContextFormatter

logging_debug_format_suffix

Type: string
Default: %(funcName)s %(pathname)s:%(lineno)d

Additional data to append to log message when logging level for the message is DEBUG. Used by oslo_log.formatters.ContextFormatter

logging_exception_prefix

Type: string
Default: %(asctime)s.%(msecs)03d %(process)d ERROR %(name)s %(instance)s

Prefix each line of exception output with this format. Used by oslo_log.formatters.ContextFormatter

logging_user_identity_format

Type: string
Default: %(user)s %(project)s %(domain)s %(system_scope)s %(user_domain)s %(project_domain)s

Defines the format string for %(user_identity)s that is used in logging_context_format_string. Used by oslo_log.formatters.ContextFormatter

default_log_levels

Type: list
Default: ['amqp=WARN', 'amqplib=WARN', 'boto=WARN', 'qpid=WARN', 'sqlalchemy=WARN', 'suds=INFO', 'oslo.messaging=INFO', 'oslo_messaging=INFO', 'iso8601=WARN', 'requests.packages.urllib3.connectionpool=WARN', 'urllib3.connectionpool=WARN', 'websocket=WARN', 'requests.packages.urllib3.util.retry=WARN', 'urllib3.util.retry=WARN', 'keystonemiddleware=WARN', 'routes.middleware=WARN', 'stevedore=WARN', 'taskflow=WARN', 'keystoneauth=WARN', 'oslo.cache=INFO', 'oslo_policy=INFO', 'dogpile.core.dogpile=INFO']

List of package logging levels in logger=LEVEL pairs. This option is ignored if log_config_append is set.

publish_errors

Type: boolean
Default: False

Enables or disables publication of error events.

instance_format

Type: string
Default: "[instance: %(uuid)s] "

The format for an instance that is passed with the log message.

instance_uuid_format

Type: string
Default: "[instance: %(uuid)s] "

The format for an instance UUID that is passed with the log message.

rate_limit_interval

Type: integer
Default: 0

Interval, number of seconds, of log rate limiting.

rate_limit_burst

Type: integer
Default: 0

Maximum number of logged messages per rate_limit_interval.

rate_limit_except_level

Type: string
Default: CRITICAL
Valid Values: CRITICAL, ERROR, INFO, WARNING, DEBUG, ''

Log level name used by rate limiting. Logs with level greater or equal to rate_limit_except_level are not filtered. An empty string means that all levels are filtered.

fatal_deprecations

Type: boolean
Default: False

Enables or disables fatal status of deprecations.

Format Strings and Log Record Metadata

oslo.log builds on top of the Python standard library logging module. The format string supports all of the built-in replacement keys provided by that library, with some additions. Some of the more useful keys are listed here. Refer to the section on LogRecord attributes in the library documentation for complete details about the built-in values.

Basic Information

Format key	Description
%(message)s	The message passed from the application code.

Time Information

Format key	Description
%(asctime)s	Human-readable time stamp of when the logging record was created, formatted as '2003-07-08 16:49:45,896' (the numbers after the comma are milliseconds).
%(isotime)s	Human-readable time stamp of when the logging record was created, using Python's isoformat() function in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm or, if the microseconds value is 0, YYYY-MM-DDTHH:MM:SS).

Location Information

Format key	Description
%(pathname)s	Full name of the source file where the logging call was issued, when it is available.
%(filename)s	Filename portion of pathname.
%(lineno)d	Source line number where the logging call was issued, when it is available.
%(module)s	The module name is derived from the filename.
%(name)s	The name of the logger used to log the call. For OpenStack projects, this usually corresponds to the full module name (i.e., nova.api or oslo_config.cfg).

Severity Information

Format key	Description
%(levelname)s	Text logging level for the message (DEBUG, INFO, WARNING, ERROR, CRITICAL).
%(levelno)s	Numeric logging level for the message. DEBUG level messages have a lower numerical value than INFO, which have a lower value than WARNING, etc.

Error Handling Information

Format key	Description
%(error_summary)s	The name of the exception being processed and any message associated with it.

Identity Information

These keys are only available in OpenStack applications that also use oslo.context.

Format key	Description
%(user_identity)s	The pre-formatted identity information about the user. See the logging_user_identity_format configuration option.
%(user_name)s	The name of the authenticated user, if available.
%(user)s	The ID of the authenticated user, if available.
%(tenant_name)s	The name of the authenticated tenant, if available.
%(tenant)s	The ID of the authenticated tenant, if available.
%(user_domain)s	The ID of the authenticated user domain, if available.
%(project_domain)s	The ID of the authenticated project/tenant, if available.
%(request_id)s	The ID of the current request. This value can be used to tie multiple log messages together as relating to the same operation.
%(resource_uuid)s	The ID of the resource on which the current operation will have effect. For example, the instance, network, volume, etc.

SEE ALSO:

•: Python logging library LogRecord attributes

Administering Applications that use oslo.log

Advanced Configuration Files

The oslo.config options described in Configuration Options make it easy to enable some default logging configuration behavior such as setting the default log level and output file. For more advanced configurations using translations or multiple output destinations oslo.log relies on the Python standard library logging module configuration file features.

The configuration file can be used to tie together the loggers, handlers, and formatters and provide all of the necessary configuration values to enable any desired behavior. Refer to the Python logging Module Tutorial for descriptions of these concepts.

Logger Names

Loggers are configured by name. Most OpenStack applications use logger names based on the source file where the message is coming from. A file named myapp/package/module.py corresponds to a logger named myapp.package.module.

Loggers are configured in a tree structure, and the names reflect their location in this hierarchy. It is not necessary to configure every logger, since messages are passed up the tree during processing. To control the logging for myapp, for example, it is only necessary to set up a logger for myapp and not myapp.package.module.

The base of the tree, through which all log message may pass unless otherwise discarded, is called the root logger.

Example Files

Example Configuration File for nova

This sample configuration file demonstrates how the OpenStack compute service (nova) might be configured.

# nova_sample.conf
[loggers]
keys = root, nova
[handlers]
keys = stderr, stdout, watchedfile, syslog, fluent, null
[formatters]
keys = context, default, fluent
[logger_root]
level = WARNING
handlers = null
[logger_nova]
level = INFO
handlers = stderr
qualname = nova
[logger_amqp]
level = WARNING
handlers = stderr
qualname = amqp
[logger_amqplib]
level = WARNING
handlers = stderr
qualname = amqplib
[logger_sqlalchemy]
level = WARNING
handlers = stderr
qualname = sqlalchemy
# "level = INFO" logs SQL queries.
# "level = DEBUG" logs SQL queries and results.
# "level = WARNING" logs neither.  (Recommended for production systems.)
[logger_boto]
level = WARNING
handlers = stderr
qualname = boto
# NOTE(mikal): suds is used by the vmware driver, removing this will
# cause many extraneous log lines for their tempest runs. Refer to
# https://review.opendev.org/#/c/219225/ for details.
[logger_suds]
level = INFO
handlers = stderr
qualname = suds
[logger_eventletwsgi]
level = WARNING
handlers = stderr
qualname = eventlet.wsgi.server
[handler_stderr]
class = StreamHandler
args = (sys.stderr,)
formatter = context
[handler_stdout]
class = StreamHandler
args = (sys.stdout,)
formatter = context
[handler_watchedfile]
class = handlers.WatchedFileHandler
args = ('nova.log',)
formatter = context
[handler_syslog]
class = handlers.SysLogHandler
args = ('/dev/log', handlers.SysLogHandler.LOG_USER)
formatter = context
[handler_fluent]
class = fluent.handler.FluentHandler
args = ('openstack.nova', 'localhost', 24224)
formatter = fluent
[handler_null]
class = logging.NullHandler
formatter = default
args = ()
[formatter_context]
class = oslo_log.formatters.ContextFormatter
[formatter_default]
format = %(message)s
[formatter_fluent]
class = oslo_log.formatters.FluentFormatter

Two logger nodes are set up, root and nova.

[loggers]
keys = root, nova

Several handlers are created, to send messages to different outputs.

[handlers]
keys = stderr, stdout, watchedfile, syslog, fluent, null

And two formatters are created to be used based on whether the logging location will have OpenStack request context information available or not. A Fluentd formatter is also shown.

[formatters]
keys = context, default, fluent

The root logger is configured to send messages to the null handler, silencing most messages that are not part of the nova application code namespace.

[logger_root]
level = WARNING
handlers = null

The nova logger is configured to send messages marked as INFO and higher level to the standard error stream.

[logger_nova]
level = INFO
handlers = stderr
qualname = nova

The amqp and amqplib loggers, used by the module that connects the application to the message bus, are configured to emit warning messages to the standard error stream.

[logger_amqp]
level = WARNING
handlers = stderr
qualname = amqp
[logger_amqplib]
level = WARNING
handlers = stderr
qualname = amqplib

The sqlalchemy logger, used by the module that connects the application to the database, is configured to emit warning messages to the standard error stream.

[logger_sqlalchemy]
level = WARNING
handlers = stderr
qualname = sqlalchemy
# "level = INFO" logs SQL queries.
# "level = DEBUG" logs SQL queries and results.
# "level = WARNING" logs neither.  (Recommended for production systems.)

Similarly, boto, suds, and eventlet.wsgi.server are configured to send warnings to the standard error stream.

[logger_boto]
level = WARNING
handlers = stderr
qualname = boto
# NOTE(mikal): suds is used by the vmware driver, removing this will
# cause many extraneous log lines for their tempest runs. Refer to
# https://review.opendev.org/#/c/219225/ for details.
[logger_suds]
level = INFO
handlers = stderr
qualname = suds
[logger_eventletwsgi]
level = WARNING
handlers = stderr
qualname = eventlet.wsgi.server

The stderr handler, being used by most of the loggers above, is configured to write to the standard error stream on the console.

[handler_stderr]
class = StreamHandler
args = (sys.stderr,)
formatter = context

The stderr handler uses the context formatter, which takes its configuration settings from oslo.config.

[formatter_context]
class = oslo_log.formatters.ContextFormatter

The stdout and syslog handlers are defined, but not used.

The fluent handler is useful to send logs to fluentd. It is a part of fluent-logger-python and you can install it as following.

$ pip install fluent-logger

This handler is configured to use fluent formatter.

[handler_fluent]
class = fluent.handler.FluentHandler
args = ('openstack.nova', 'localhost', 24224)
formatter = fluent

[formatter_fluent]
class = oslo_log.formatters.FluentFormatter

SEE ALSO:

•: Python logging Module Tutorial

Systemd Journal Support

One of the newer features in oslo.log is the ability to integrate with the systemd journal service (journald) natively on newer Linux systems. When using native journald support, additional metadata will be logged on each log message in addition to the message itself, which can later be used to do some interesting searching through your logs.

Enabling

In order to enable the support you must have Python bindings for systemd installed. On Red Hat based systems, run:

yum install systemd-python

On Ubuntu/Debian based systems, run:

apt install python-systemd

If there is no native package for your distribution, or you are running in a virtualenv, you can install with pip.:

pip install systemd-python

NOTE:

There are also many non official systemd python modules on pypi, with confusingly close names. Make sure you install systemd-python.

After the package is installed, you must enable journald support manually in all services that will be using it. Add the following to the config files for all services:

[DEFAULT]
use_journal = True

In all relevant config files.

Extra Metadata

Journald supports the concept of adding structured metadata in addition to the log message in question. This makes it much easier to take the output of journald and push it into other logging systems like Elastic Search, without needing to regex guess relevant data. It also allows you to search the journal by these fields using journalctl.

We use this facility to add our own structured information, if it is known at the time of logging the message.

CODE_FILE=, CODE_LINE=, CODE_FUNC=

The code location generating this message, if known. Contains the source filename, the line number and the function name. (This is the same as systemd uses)

THREAD_NAME=, PROCESS_NAME=

Information about the thread and process, if known. (This is the same as systemd uses)

EXCEPTION_TEXT=, EXCEPTION_INFO=

Information about an exception, if an exception has been logged.

LOGGER_NAME=

The name of the python logger that emitted the log message. Very often this is the module where the log message was emitted from.

LOGGER_LEVEL=

The name of the python logging level, which allows seeing all 'ERROR' messages very easily without remembering how they are translated to syslog priorities.

SYSLOG_IDENTIFIER=

The binary name identified for syslog compatibility. It will be the basename of the process that emits the log messages (e.g. nova-api, neutron-l3-agent)

PRIORITY=

The syslog priority (based on LOGGER_LEVEL), which allows syslog style filtering of messages based on their priority (an openstack.err log file for instance).

REQUEST_ID=

Most OpenStack services generate a unique request-id on every REST API call, which is then passed between it's sub services as that request is handled. For example, this can be very useful in tracking the build of a nova server from the initial HTTP POST to final VM create.

PROJECT_ID=, PROJECT_NAME=, USER_ID=, USER_NAME=

The keystone known user and project information about the requestor. Both the id and name are provided for easier searching. This can be used to understand when particular users or projects are reporting issues in the environment.

Additional fields may be added over time. It is unlikely that fields will be removed, but if so they will be deprecated for one release cycle before that happens.

Using Journalctl

Because systemd is relatively new in the Linux ecosystem, it's worth noting how one can effectively use journal control.

If you want to follow all the journal logs you would do so with:

journalctl -f

That's going to be nearly everything on your system, which you will probably find overwhelming. You can limit this to a smaller number of things using the SYSLOG_IDENTIFIER=:

journalctl -f SYSLOG_IDENTIFIER=nova-compute SYSLOG_IDENTIFIER=neutron-l3-agent

Specifying a query parameter multiple times defaults to an OR operation, so that will show either nova-compute or neutron-l3-agent logs.

You can also query by request id to see the entire flow of a REST call:

journalctl REQUEST_ID=req-b1903300-77a8-401d-984c-8e7d17e4a15f

References

A complete list of the systemd journal fields is here, it is worth making yourself familiar with them - https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html
The complete journalctl manual is worth reading, especially the -o parameter, as default displayed time resolution is only in seconds (even though systemd internally is tracking microsecs) - https://www.freedesktop.org/software/systemd/man/journalctl.html
The guide for using systemd in devstack provides additional examples of effective journalctl queries - https://opendev.org/openstack/devstack/src/branch/master/doc/source/systemd.rst

Log rotation

oslo.log can work with logrotate, picking up file changes once log files are rotated. Make sure to set the watch-log-file config option.

Log rotation on Windows

On Windows, in-use files cannot be renamed or moved. For this reason, oslo.log allows setting maximum log file sizes or log rotation interval, in which case the service itself will take care of the log rotation (as opposed to having an external daemon).

Configuring log rotation

Use the following options to set a maximum log file size. In this sample, log files will be rotated when reaching 1GB, having at most 30 log files.

[DEFAULT]
log_rotation_type = size
max_logfile_size_mb = 1024  # MB
max_logfile_count = 30

The following sample configures log rotation to be performed every 12 hours.

[DEFAULT]
log_rotation_type = interval
log_rotate_interval = 12
log_rotate_interval_type = Hours
max_logfile_count = 60

NOTE:

The time of the next rotation is computed when the service starts or when a log rotation is performed, using the time of the last file modification or the service start time, to which the configured log rotation interval is added. This means that service restarts may delay periodic log file rotations.

Contributing

If you would like to contribute to the development of oslo's libraries, first you must take a look to this page:

https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html

If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

https://docs.openstack.org/infra/manual/developers.html

Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at:

https://docs.openstack.org/infra/manual/developers.html#development-workflow

Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

https://bugs.launchpad.net/oslo.log

RELEASE NOTES

INDICES AND TABLES

Index
Module Index
Search Page

AUTHOR

Author name not set

COPYRIGHT

2025, OpenStack Foundation

April 2, 2025

7.1.0

oslolog(1)

NAME

CONTENTS

Installation

Using oslo.log

Usage

In an Application

Oslo Logging Setup Methods

Oslo Logging Functions

Oslo Log Translation

Adding Context to Logging

Examples

In a Library

Examples

python_logging.py

oslo_logging.py

usage.py

usage_helper.py

usage_context.py

Logging Guidelines

Motivation

Adding Variables to Log Messages

Definition of Log Levels

Log levels from an operator perspective

Overall logging principles

Debugging start / end messages

Log messages at INFO and above should represent a "unit of work"

Examples of good and bad uses of INFO

Messages shouldn't need a secret decoder ring

Specific event types

WSGI requests

Operator deprecation warnings

REST API deprecation warnings

Stacktraces in logs

Logging by non-OpenStack components

Testing

References

CHANGES

7.1.0

7.0.0

6.2.0

6.1.2

6.1.1

6.1.0

6.0.0

5.5.0

5.4.0

5.3.0

5.1.0

5.0.2

5.0.1

5.0.0

4.8.0

4.7.0

4.6.1

4.6.0

4.5.0

4.4.0

4.3.0

4.2.1

4.2.0

4.1.1

4.1.0

4.0.1

4.0.0

3.45.2

3.45.1

3.45.0

3.44.1

3.44.0

3.43.0

3.42.3

3.42.2

3.42.1

3.42.0

3.41.0

3.40.1

3.39.0

3.38.1

3.38.0