Revision cfb87e18 docs/developers/logging.rst
b/docs/developers/logging.rst | ||
---|---|---|
1 | 1 |
Logging |
2 | 2 |
======= |
3 | 3 |
|
4 |
Kamaki uses the standard Python logger package to log some of its functionality.
|
|
4 |
Kamaki uses the standard Python logger. |
|
5 | 5 |
|
6 | 6 |
All kamaki loggers are named or prefixed after the package they log, e.g., |
7 | 7 |
a logger at `kamaki/cli/argument/__init__.py` should be called |
... | ... | |
32 | 32 |
`kamaki.cli.logger` which allows the definition, activation and deactivation |
33 | 33 |
of stream (usually console) or file loggers. |
34 | 34 |
|
35 |
As an example, we will use
|
|
35 |
We will use
|
|
36 | 36 |
`this script <clients-api.html#register-a-banch-of-pre-uploaded-images>`_ |
37 |
that loads images from a set of image files already uploaded to Pithos+
|
|
38 |
`images` container.
|
|
37 |
as an example to work on. The script registers images from a set of
|
|
38 |
pre-uploaded image files.
|
|
39 | 39 |
|
40 |
First, we shall add a logger to keep HTTP communication in `/tmp/my_kamaki.log`
|
|
40 |
First, we shall add a logger to track HTTP communication in `/tmp/my_kamaki.log`
|
|
41 | 41 |
To do this, append the following at the top of the file: |
42 | 42 |
|
43 | 43 |
.. code-block:: python |
44 | 44 |
|
45 | 45 |
from kamaki.cli.logger import add_file_logger |
46 |
add_file_logger('kamaki', filename='/tmp/my_kamaki.log') |
|
46 |
add_file_logger('kamaki.clients.send', filename='/tmp/my_kamaki.log') |
|
47 |
add_file_logger('kamaki.clients.recv', filename='/tmp/my_kamaki.log') |
|
47 | 48 |
|
48 | 49 |
After a run of the script, a new file will be created at `/tmp/my_kamaki.log` |
49 | 50 |
that will contain logs of the form:: |
... | ... | |
76 | 77 |
that goal, we should get a stream logger and deactivate it when we do not need |
77 | 78 |
it anymore. |
78 | 79 |
|
79 |
|
|
80 | 80 |
.. code-block:: python |
81 | 81 |
|
82 | 82 |
#! /usr/bin/python |
... | ... | |
94 | 94 |
--------------------- |
95 | 95 |
|
96 | 96 |
When implementing kamaki code, either as part of the main kamaki project or as |
97 |
an extension, it is often useful to use loggers. The suggested strategy is to |
|
98 |
use `kamaki.cli.logger` to create one logger per package, named after the |
|
99 |
package itself. Developers may also directly use the Python logger module, but |
|
100 |
they should respect the naming conventions. |
|
97 |
an extension, it is often useful to use loggers. Developers may also directly |
|
98 |
use the Python logger module with respect to the naming conventions. |
|
101 | 99 |
|
102 | 100 |
In this example, we want to log the arguments of the `register` method found in |
103 | 101 |
`kamaki/clients/image/__init__.py`. We will use the Python logger module. |
... | ... | |
123 | 121 |
log.debug('properties: %s' % properties) |
124 | 122 |
[...] |
125 | 123 |
|
126 |
The logging module will not log anything by itself. It is the caller scripts
|
|
127 |
responsibility to define the actual logger and set the logging destination.
|
|
128 |
We are going to use the same script as in the previous examples, but we need
|
|
129 |
to define logger for `kamaki.clients.image`.
|
|
124 |
Loggers defined in higher levels of the package hierarchy are inherited. This
|
|
125 |
may cause duplication in logs. Use either a high level loger (e.g. 'kamaki' or
|
|
126 |
'kamaki.clients') to log everything, or a specific logger (e.g.
|
|
127 |
'kamaki.clients.image').
|
|
130 | 128 |
|
131 | 129 |
.. code-block:: python |
132 | 130 |
|
133 |
#! /usr/bin/python |
|
134 |
|
|
135 |
from kamaki.cli.logger import add_file_logger |
|
136 |
|
|
137 | 131 |
add_file_logger('kamaki.clients.image', filename='/tmp/kamaki_image.log') |
138 | 132 |
|
139 |
.. note:: a logger named as `kamaki` will grab everything logged with a name |
|
140 |
prefixed as `kamaki`, so if we have two loggers, one named `kamaki` and |
|
141 |
another one named `kamaki.clients.image`, they will both grab the |
|
142 |
`register` logs. |
|
143 |
|
Also available in: Unified diff