Logging¶

Note

TODO(shade) This document is written from a shade POV. It needs to be combined with the existing logging guide, but also the logging systems need to be rationalized.

openstacksdk uses Python Logging. As openstacksdk is a library, it does not configure logging handlers automatically, expecting instead for that to be the purview of the consuming application.

Simple Usage¶

For consumers who just want to get a basic logging setup without thinking about it too deeply, there is a helper method. If used, it should be called before any other openstacksdk functionality.

openstack.enable_logging(debug: bool = False, http_debug: bool = False, path: str | None = None, stream: TextIO | None = None, format_stream: bool = False, format_template: str = '%(asctime)s %(levelname)s: %(name)s %(message)s', handlers: List[Handler] | None = None) → None¶

Enable logging output.

Helper function to enable logging. This function is available for debugging purposes and for folks doing simple applications who want an easy ‘just make it work for me’. For more complex applications or for those who want more flexibility, the standard library logging package will receive these messages in any handlers you create.

Parameters:

debug (bool) – Set this to True to receive debug messages.
http_debug (bool) – Set this to True to receive debug messages including HTTP requests and responses. This implies debug=True.
path (str) – If a path is specified, logging output will written to that file in addition to sys.stderr. The path is passed to logging.FileHandler, which will append messages the file (and create it if needed).
stream – One of None `` or ``sys.stdout or sys.stderr. If it is None, nothing is logged to a stream. If it isn’t None, console output is logged to this stream.
format_stream (bool) – If format_stream is False, the default, apply format_template to path but not to stream outputs. If True, apply format_template to stream outputs as well.
format_template (str) – Template to pass to logging.Formatter.

Return type:

None

import openstack
openstack.enable_logging()

The stream parameter controls the stream where log message are written to. It defaults to sys.stdout which will result in log messages being written to STDOUT. It can be set to another output stream, or to None to disable logging to the console.

The path parameter sets up logging to log to a file. By default, if path is given and stream is not, logging will only go to path.

You can combine the path and stream parameters to log to both places simultaneously.

To log messages to a file called openstack.log and the console on stdout:

import sys
import openstack

openstack.enable_logging(
    debug=True, path='openstack.log', stream=sys.stdout)

openstack.enable_logging also sets up a few other loggers and squelches some warnings or log messages that are otherwise uninteresting or unactionable by an openstacksdk user.

Advanced Usage¶

openstacksdk logs to a set of different named loggers.

Most of the logging is set up to log to the root openstack logger. There are additional sub-loggers that are used at times, primarily so that a user can decide to turn on or off a specific type of logging. They are listed below.

openstack.config: Issues pertaining to configuration are logged to the openstack.config logger.
openstack.task_manager: openstacksdk uses a Task Manager to perform remote calls. The openstack.task_manager logger emits messages at the start and end of each Task announcing what it is going to run and then what it ran and how long it took. Logging openstack.task_manager is a good way to get a trace of external actions openstacksdk is taking without full HTTP Tracing.
openstack.iterate_timeout: When openstacksdk needs to poll a resource, it does so in a loop that waits between iterations and ultimately times out. The openstack.iterate_timeout logger emits messages for each iteration indicating it is waiting and for how long. These can be useful to see for long running tasks so that one can know things are not stuck, but can also be noisy.
openstack.fnmatch: openstacksdk will try to use fnmatch on given name_or_id arguments. It’s a best effort attempt, so pattern misses are logged to openstack.fnmatch. A user may not be intending to use an fnmatch pattern - such as if they are trying to find an image named Fedora 24 [official], so these messages are logged separately.

HTTP Tracing¶

HTTP Interactions are handled by keystoneauth. If you want to enable HTTP tracing while using openstacksdk and are not using openstack.enable_logging, set the log level of the keystoneauth logger to DEBUG.

For more information see https://docs.openstack.org/keystoneauth/latest/using-sessions.html#logging

Python Logging¶

Python logging is a standard feature of Python and is documented fully in the Python Documentation, which varies by version of Python.

For more information on Python Logging for Python v2, see https://docs.python.org/2/library/logging.html.

For more information on Python Logging for Python v3, see https://docs.python.org/3/library/logging.html.

last updated: UTC - commit: