root / docs / developers / logging.rst @ a582b70e
History | View | Annotate | Download (4.8 kB)
1 |
Logging |
---|---|
2 |
======= |
3 |
|
4 |
Kamaki uses the standard python logger package to log some of its |
5 |
functionality. |
6 |
|
7 |
All kamaki loggers are named or prefixed after the package they log, e.g. |
8 |
a logger at `kamaki/cli/argument.__init__.py` should be called |
9 |
`kamaki.cli.argument` whereas a logger at `kamaki/clients/conf.py` should be |
10 |
named `kamaki.clients/conf`. In `kamaki/clients/__init__.py` there are two |
11 |
loggers that use the package name as prefix, and they detailed bellow. |
12 |
|
13 |
Monitor requests and responses |
14 |
------------------------------ |
15 |
|
16 |
The `kamaki.clients` logger contains two subloggers that monitor the HTTP |
17 |
communication of with the servers:: |
18 |
|
19 |
kamaki.clients.send for kamaki requests to the server |
20 |
kamaki.clients.recv for server responses to kamaki |
21 |
|
22 |
These are the only loggers used for purposes other than mere debugging. Both |
23 |
loggers are defined in the CLI code and are used to (a) log HTTP communication |
24 |
to the log file as well as to (b) show users the HTTP requests and responses if |
25 |
kamaki cli is called with options like "verbose" or "debug". |
26 |
|
27 |
Logger in external code |
28 |
----------------------- |
29 |
|
30 |
When a logger is known to be in kamaki code, the script developer may use this |
31 |
logger to log some needed information. This can be happen either by directly |
32 |
using the python `logger` package, or the corresponding kamaki wraper |
33 |
`kamaki.cli.logger` which allows the definition, activation and deactivation |
34 |
of stream (usually console) or file loggers. |
35 |
|
36 |
As an example, we will use |
37 |
`this script <clients-api.html#register-a-banch-of-pre-uploaded-images>`_ |
38 |
that loads images from a set of image files already uploaded to Pithos+ |
39 |
`images` container. |
40 |
|
41 |
First, we shall add a logger to keep HTTP communication in `/tmp/my_kamaki.log` |
42 |
To do this, append the following at the top of the file: |
43 |
|
44 |
.. code-block:: python |
45 |
|
46 |
from kamaki.cli.logger import add_file_logger |
47 |
add_file_logger('kamaki', filename='/tmp/my_kamaki.log') |
48 |
|
49 |
After a run of the script, a new file will be created at `/tmp/my_kamaki.log` |
50 |
that will contain logs of the form:: |
51 |
|
52 |
> POST https://accounts.okeanos.grnet.gr/identity/v2.0/tokens |
53 |
> Content-Length: 74 |
54 |
> Content-Type: application/json |
55 |
> data size:74 |
56 |
|
57 |
< 200 OK |
58 |
< content-length: 2425 |
59 |
< content-language: en-us |
60 |
< expires: Wed, 31 Jul 2013 14:27:47 GMT |
61 |
< vary: X-Auth-Token,Accept-Language |
62 |
< server: gunicorn/0.14.5 |
63 |
< last-modified: Wed, 31 Jul 2013 14:27:47 GMT |
64 |
< connection: close |
65 |
< etag: "43af...36" |
66 |
< cache-control: no-cache, no-store, must-revalidate, max-age=0 |
67 |
< date: Wed, 31 Jul 2013 14:27:47 GMT |
68 |
< content-type: application/json; charset=UTF-8 |
69 |
< data size: 2425 |
70 |
|
71 |
.. note:: user token and http body content are not logged by default |
72 |
|
73 |
As a second example, let's suppose that we need to see only the http requests |
74 |
of the `pithos.list_objects()` method. We decide to print these to the console. |
75 |
To achieve that goal, we should get a stream logger and deactivate it when we |
76 |
do not need it anymore. |
77 |
|
78 |
|
79 |
.. code-block:: python |
80 |
|
81 |
#! /usr/bin/python |
82 |
|
83 |
[...] |
84 |
|
85 |
from kamaki.cli.logger import add_stream_logger, deactivate |
86 |
add_stream_logger('kamaki.clients') |
87 |
|
88 |
for img in pithos.list_objects(): |
89 |
deactivate('kamaki.clients') |
90 |
[...] |
91 |
|
92 |
Logger in kamaki code |
93 |
--------------------- |
94 |
|
95 |
When implementing kamaki code, either as part of the main kamaki project or as |
96 |
an extension, it is often useful to use loggers. The suggested strategy is to |
97 |
use `kamaki.cli.logger` to create one logger per package, named after the |
98 |
package itself. Developers may also directly use the python logger module, but |
99 |
they should respect the naming conventions. |
100 |
|
101 |
In this example, we want to log the arguments of the `register` method found in |
102 |
`kamaki/clients/image/__init__.py`. We will use the python logger module. |
103 |
|
104 |
First, we should add a logger initializer at the top of the file. |
105 |
|
106 |
.. code-block:: python |
107 |
|
108 |
from logging import getLogger |
109 |
|
110 |
log = getLogger(__name__) |
111 |
|
112 |
Now, we should use the `log` biding to actually log what we need. |
113 |
|
114 |
.. code-block:: python |
115 |
|
116 |
[...] |
117 |
|
118 |
def register(self, name, location, params={}, properties={}): |
119 |
log.debug('name: %s' % name) |
120 |
log.debug('location: %s' % location) |
121 |
log.debug('params: %s' % params) |
122 |
log.debug('properties: %s' % properties) |
123 |
[...] |
124 |
|
125 |
The logging module will not log anything by itself. It is the caller scripts |
126 |
responsibility to define the actual logger and set the logging destination. |
127 |
We are going to use the same script as in the previous examples, but we need |
128 |
to define logger for `kamaki.clients.image`. |
129 |
|
130 |
.. code-block:: python |
131 |
|
132 |
#! /usr/bin/python |
133 |
|
134 |
from kamaki.cli.logger import add_file_logger |
135 |
|
136 |
add_file_logger('kamaki.clients.image', filename='/tmp/kamaki_image.log') |
137 |
|
138 |
.. note:: a logger named as `kamaki` will grab everything logged with a name |
139 |
prefixed as `kamaki`, so if we have two loggers, one named `kamaki` and |
140 |
another one named `kamaki.clients.image`, they will both grab the |
141 |
`register` logs. |
142 |
|