535f2f48ff
This sucks in the git history for both projects, then moves their files in place. It should not introduce any behavior changes to any of the existing openstacksdk code, nor to openstack.config and openstack.cloud - other than the name change. TODO(shade) comments have been left indicating places where further integration work should be done. It should not be assumed that these are the final places for either to live. This is just about getting them in-tree so we can work with them. The enforcer code for reasons surpassing understanding does not work with python setup.py build_sphinx but it does work with sphinx-build (what?) For now turn it off. We can turn it back on once the build sphinx job is migrated to the new PTI. Change-Id: I9523e4e281285360c61e9e0456a8e07b7ac1243c
4.0 KiB
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 shade functionality.
import openstack.cloud
openstack.cloud.simple_logging()openstack.cloud.simple_logging takes two optional boolean arguments:
- debug
-
Turns on debug logging.
- http_debug
-
Turns on debug logging as well as debug logging of the underlying HTTP calls.
openstack.cloud.simple_logging also sets up a few other loggers and squelches some warnings or log messages that are otherwise uninteresting or unactionable by a openstack.cloud user.
Advanced Usage
openstack.cloud logs to a set of different named loggers.
Most of the logging is set up to log to the root openstack.cloud 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.cloud.task_manager
-
openstack.cloud uses a Task Manager to perform remote calls. The openstack.cloud.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.cloud.task_manager is a good way to get a trace of external actions openstack.cloud is taking without full HTTP Tracing.
- openstack.cloud.request_ids
-
The openstack.cloud.request_ids logger emits a log line at the end of each HTTP interaction with the OpenStack Request ID associated with the interaction. This can be be useful for tracking action taken on the server-side if one does not want HTTP Tracing.
- openstack.cloud.exc
-
If log_inner_exceptions is set to True, shade will emit any wrapped exception to the openstack.cloud.exc logger. Wrapped exceptions are usually considered implementation details, but can be useful for debugging problems.
- openstack.cloud.iterate_timeout
-
When shade needs to poll a resource, it does so in a loop that waits between iterations and ultimately timesout. The openstack.cloud.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.cloud.http
-
shade will sometimes log additional information about HTTP interactions to the openstack.cloud.http logger. This can be verbose, as it sometimes logs entire response bodies.
- openstack.cloud.fnmatch
-
shade will try to use fnmatch on given name_or_id arguments. It's a best effort attempt, so pattern misses are logged to openstack.cloud.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 shade and are not using openstack.cloud.simple_logging, set the log level of the keystoneauth logger to DEBUG.
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.