|
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 |
|