Merge branch 'feature-docs-logger' into develop

docs/developers/clients-api.rst

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

docs/developers/logging.rst

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

docs/devguide.rst

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