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.
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=False, http_debug=False, path=None, stream=None, format_stream=False, format_template='%(asctime)s %(levelname)s: %(name)s %(message)s')¶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: |
|
---|---|
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.
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
logger.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
. 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 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 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.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.