code.grnet.gr Git - kamaki/blob - docs/developers/logging.rst

   1 Logging
   2 =======
   3
   4 Kamaki uses the standard Python logger package to log some of its functionality.
   5
   6 All kamaki loggers are named or prefixed after the package they log, e.g.,
   7 a logger at `kamaki/cli/argument/__init__.py` should be called
   8 `kamaki.cli.argument` whereas a logger at `kamaki/clients/conf.py` should be
   9 named `kamaki.clients.conf`. In `kamaki/clients/__init__.py` there are two
  10 loggers that use the package name as prefix, and they detailed bellow.
  11
  12 Monitor requests and responses
  13 ------------------------------
  14
  15 The `kamaki.clients` logger contains two subloggers that monitor the HTTP
  16 API calls::
  17
  18         kamaki.clients.send   for kamaki requests to the server
  19         kamaki.clients.recv   for server responses to kamaki
  20
  21 These are the only loggers used for purposes other than mere debugging. Both
  22 loggers are defined in the CLI code and are used to (a) log HTTP communication
  23 to the log file as well as to (b) show users the HTTP requests and responses in
  24 "verbose" or "debug" modes.
  25
  26 Logger in external code
  27 -----------------------
  28
  29 When a logger is known to be in kamaki code, the script developer may use this
  30 logger to log some needed information. This can be happen either by directly
  31 using the Python `logger` package, or the corresponding kamaki wraper
  32 `kamaki.cli.logger` which allows the definition, activation and deactivation
  33 of stream (usually console) or file loggers.
  34
  35 As an example, we will use
  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.
  39
  40 First, we shall add a logger to keep HTTP communication in `/tmp/my_kamaki.log`
  41 To do this, append the following at the top of the file:
  42
  43 .. code-block:: python
  44
  45         from kamaki.cli.logger import add_file_logger
  46         add_file_logger('kamaki', filename='/tmp/my_kamaki.log')
  47
  48 After a run of the script, a new file will be created at `/tmp/my_kamaki.log`
  49 that will contain logs of the form::
  50
  51         > POST https://accounts.okeanos.grnet.gr/identity/v2.0/tokens
  52         >   Content-Length: 74
  53         >   Content-Type: application/json
  54         > data size:74
  55
  56         < 200 OK
  57         <   content-length: 2425
  58         <   content-language: en-us
  59         <   expires: Wed, 31 Jul 2013 14:27:47 GMT
  60         <   vary: X-Auth-Token,Accept-Language
  61         <   server: gunicorn/0.14.5
  62         <   last-modified: Wed, 31 Jul 2013 14:27:47 GMT
  63         <   connection: close
  64         <   etag: "43af...36"
  65         <   cache-control: no-cache, no-store, must-revalidate, max-age=0
  66         <   date: Wed, 31 Jul 2013 14:27:47 GMT
  67         <   content-type: application/json; charset=UTF-8
  68         < data size: 2425
  69
  70 .. note:: user token and http body content are not logged by default. This can
  71         be switched on and off by modifing the *kamaki.client.Client.LOG_TOKEN* and
  72         *kamaki.client.Client.LOG_DATA* flags
  73
  74 As a second example, let's suppose that we need to see only the http requests
  75 of the `pithos.list_objects()` method and print these to stdout. To achieve
  76 that goal, we should get a stream logger and deactivate it when we do not need
  77 it anymore.
  78
  79
  80 .. code-block:: python
  81
  82         #! /usr/bin/python
  83
  84         [...]
  85
  86         from kamaki.cli.logger import add_stream_logger, deactivate
  87         add_stream_logger('kamaki.clients')
  88
  89         for img in pithos.list_objects():
  90                 deactivate('kamaki.clients')
  91                 [...]
  92
  93 Logger in kamaki code
  94 ---------------------
  95
  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.
 101
 102 In this example, we want to log the arguments of the `register` method found in
 103 `kamaki/clients/image/__init__.py`. We will use the Python logger module.
 104
 105 First, we should add a logger initializer at the top of the file.
 106
 107 .. code-block:: python
 108
 109         from logging import getLogger
 110
 111         log = getLogger(__name__)
 112
 113 Now, we should use the `log` biding to actually log what we need.
 114
 115 .. code-block:: python
 116
 117         [...]
 118
 119     def register(self, name, location, params={}, properties={}):
 120         log.debug('name: %s' % name)
 121         log.debug('location: %s' % location)
 122         log.debug('params: %s' % params)
 123         log.debug('properties: %s' % properties)
 124         [...]
 125
 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`.
 130
 131 .. code-block:: python
 132
 133         #! /usr/bin/python
 134
 135         from kamaki.cli.logger import add_file_logger
 136
 137         add_file_logger('kamaki.clients.image', filename='/tmp/kamaki_image.log')
 138
 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