114 lines
4.0 KiB
ReStructuredText
114 lines
4.0 KiB
ReStructuredText
=======
|
|
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.
|
|
|
|
.. autofunction:: openstack.enable_logging
|
|
|
|
.. code-block:: python
|
|
|
|
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``:
|
|
|
|
.. code-block:: python
|
|
|
|
import sys
|
|
from openstack import utils
|
|
|
|
utils.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.
|
|
|
|
.. _fnmatch: https://pymotw.com/2/fnmatch/
|
|
|
|
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
|
|
|
|
.. _keystoneauth: https://docs.openstack.org/keystoneauth/latest/
|
|
|
|
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.
|