Commit a582b70e authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Add documentation and examples for logging

Also, add a batch image register example script

Refs: #4135
parent abff3366
......@@ -215,7 +215,7 @@ Batch-create servers
.. code-block:: python
#/usr/bin/python
#! /usr/bin/python
from kamaki.clients.astakos import AstakosClient
from kamaki.clients.cyclades import CycladesClient
......@@ -245,7 +245,7 @@ Batch-create 4 servers of the same kind
.. code-block:: python
#/usr/bin/python
#! /usr/bin/python
from kamaki.clients.astakos import AstakosClient
from kamaki.clients.cyclades import CycladesClient
......@@ -262,3 +262,38 @@ Batch-create 4 servers of the same kind
for i in range(4):
name, flavor_id, image_id = 'Server %s' % (i + 1), 3, 'some-image-id'
cyclades.create_server(name, flavor_id, image_id)
Register a banch of pre-uploaded images
'''''''''''''''''''''''''''''''''''''''
.. code-block:: python
#! /usr/bin/python
from kamaki.clients import ClientError
from kamaki.clients.astakos import AstakosClient
from kamaki.clients.pithos import PithosClient
from kamaki.clients.image import ImageClient
AUTHENTICATION_URL = 'https://accounts.example.com/identity/v2.0'
TOKEN = 'replace this with your token'
IMAGE_CONTAINER = 'images'
astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
USER_UUID = astakos.user_term('uuid')
PITHOS_URL = astakos.get_endpoints('object-store')['publicURL']
pithos = PithosClient(PITHOS_URL, TOKEN, USER_UUID, IMAGE_CONTAINER)
IMAGE_URL = astakos.get_endpoints('image')['publicURL']
plankton = ImageClient(IMAGE_URL, TOKEN)
for img in pithos.list_objects():
IMAGE_PATH = img['name']
try:
r = plankton.register(
name='Image %s' % img,
location=(USER_UUID, IMAGE_CONTAINER, IMAGE_PATH))
print 'Image %s registered with id %s' % (r['name'], r['id'])
except ClientError:
print 'Failed to register image %s' % IMAGE_PATH
Logging
=======
Kamaki uses the standard python logger package to log some of its
functionality.
All kamaki loggers are named or prefixed after the package they log, e.g.
a logger at `kamaki/cli/argument.__init__.py` should be called
`kamaki.cli.argument` whereas a logger at `kamaki/clients/conf.py` should be
named `kamaki.clients/conf`. In `kamaki/clients/__init__.py` there are two
loggers that use the package name as prefix, and they detailed bellow.
Monitor requests and responses
------------------------------
The `kamaki.clients` logger contains two subloggers that monitor the HTTP
communication of with the servers::
kamaki.clients.send for kamaki requests to the server
kamaki.clients.recv for server responses to kamaki
These are the only loggers used for purposes other than mere debugging. Both
loggers are defined in the CLI code and are used to (a) log HTTP communication
to the log file as well as to (b) show users the HTTP requests and responses if
kamaki cli is called with options like "verbose" or "debug".
Logger in external code
-----------------------
When a logger is known to be in kamaki code, the script developer may use this
logger to log some needed information. This can be happen either by directly
using the python `logger` package, or the corresponding kamaki wraper
`kamaki.cli.logger` which allows the definition, activation and deactivation
of stream (usually console) or file loggers.
As an example, we will use
`this script <clients-api.html#register-a-banch-of-pre-uploaded-images>`_
that loads images from a set of image files already uploaded to Pithos+
`images` container.
First, we shall add a logger to keep HTTP communication in `/tmp/my_kamaki.log`
To do this, append the following at the top of the file:
.. code-block:: python
from kamaki.cli.logger import add_file_logger
add_file_logger('kamaki', filename='/tmp/my_kamaki.log')
After a run of the script, a new file will be created at `/tmp/my_kamaki.log`
that will contain logs of the form::
> POST https://accounts.okeanos.grnet.gr/identity/v2.0/tokens
> Content-Length: 74
> Content-Type: application/json
> data size:74
< 200 OK
< content-length: 2425
< content-language: en-us
< expires: Wed, 31 Jul 2013 14:27:47 GMT
< vary: X-Auth-Token,Accept-Language
< server: gunicorn/0.14.5
< last-modified: Wed, 31 Jul 2013 14:27:47 GMT
< connection: close
< etag: "43af...36"
< cache-control: no-cache, no-store, must-revalidate, max-age=0
< date: Wed, 31 Jul 2013 14:27:47 GMT
< content-type: application/json; charset=UTF-8
< data size: 2425
.. note:: user token and http body content are not logged by default
As a second example, let's suppose that we need to see only the http requests
of the `pithos.list_objects()` method. We decide to print these to the console.
To achieve that goal, we should get a stream logger and deactivate it when we
do not need it anymore.
.. code-block:: python
#! /usr/bin/python
[...]
from kamaki.cli.logger import add_stream_logger, deactivate
add_stream_logger('kamaki.clients')
for img in pithos.list_objects():
deactivate('kamaki.clients')
[...]
Logger in kamaki code
---------------------
When implementing kamaki code, either as part of the main kamaki project or as
an extension, it is often useful to use loggers. The suggested strategy is to
use `kamaki.cli.logger` to create one logger per package, named after the
package itself. Developers may also directly use the python logger module, but
they should respect the naming conventions.
In this example, we want to log the arguments of the `register` method found in
`kamaki/clients/image/__init__.py`. We will use the python logger module.
First, we should add a logger initializer at the top of the file.
.. code-block:: python
from logging import getLogger
log = getLogger(__name__)
Now, we should use the `log` biding to actually log what we need.
.. code-block:: python
[...]
def register(self, name, location, params={}, properties={}):
log.debug('name: %s' % name)
log.debug('location: %s' % location)
log.debug('params: %s' % params)
log.debug('properties: %s' % properties)
[...]
The logging module will not log anything by itself. It is the caller scripts
responsibility to define the actual logger and set the logging destination.
We are going to use the same script as in the previous examples, but we need
to define logger for `kamaki.clients.image`.
.. code-block:: python
#! /usr/bin/python
from kamaki.cli.logger import add_file_logger
add_file_logger('kamaki.clients.image', filename='/tmp/kamaki_image.log')
.. note:: a logger named as `kamaki` will grab everything logged with a name
prefixed as `kamaki`, so if we have two loggers, one named `kamaki` and
another one named `kamaki.clients.image`, they will both grab the
`register` logs.
......@@ -6,6 +6,7 @@ Developers Guide
:glob:
developers/clients-api
developers/logging
developers/adding-commands
developers/extending-clients-api
developers/code
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment