Browse files

Merge pull request #2129 from dkavanagh/request_hook_docs

Add a tutorial for the request hooks addition. Fixes #2129.
  • Loading branch information...
danielgtaylor committed Feb 28, 2014
2 parents 141077f + 74eb19f commit 64eedcea100c46db21a74953b0d809177c746bb7
Showing with 62 additions and 0 deletions.
  1. +1 −0 docs/source/index.rst
  2. +61 −0 docs/source/request_hook_tut.rst
@@ -98,6 +98,7 @@ Additional Resources
* :doc:`Command Line Utilities <commandline>`
* :doc:`Boto Config Tutorial <boto_config_tut>`
* :doc:`Contributing to Boto <contributing>`
+* :doc:`Evaluating Application performance with Boto logging <request_hook_tut>`
* `Boto Source Repository`_
* `Boto Issue Tracker`_
* `Boto Twitter`_
@@ -0,0 +1,61 @@
+.. _request_hook_tut.rst:
+An Introduction to boto's request hook
+This tutorial shows you how to use the request hook for data gathering.
+It is often important to measure things we do as developers to better
+understand application performance and the interactions between components
+of the system. Boto plays a key role in some of those interactions as any
+client library would.
+We'll go over how to use the request hook to do some simple request logging.
+Creating a connection
+For this example, let's use the EC2 interface as an example. Any connection
+will work (IAM, SQS, etc..)::
+ >>> from boto import ec2
+ >>> conn = ec2.connect_to_region('us-west-2')
+You will be using this conn object for the remainder of the tutorial to send
+commands to EC2.
+Adding your own hook
+The hook interface is defined in boto.utils.RequestHook
+The method signature looks like::
+ def handle_request_data(self, request, response, error=False):
+In, there is an implementation of this interface which
+is written to handle multiple threads sending data to a single log
+writing thread. Exammining this file, you'll see a log file, queue and thread
+are created, then as requests are made, the handle_request_data() method is
+called. It extracts data from the request and respose object to create a log
+message. That's inserted into the queue and handled by the _request_log_worker
+One thing to note is that the boto request object has an additional value
+"start_time", which is a as of the time right before the
+request was issued. This can be used along with the current time (after the
+request) to calculate the duration of the request.
+To add this logger to your connection::
+ >>> from boto.requestlog import RequestLogger
+ >>> conn.set_request_hook(RequestLogger())
+That's all you need to do! Now, if you make a request, like::
+ >>> conn.get_all_volumes()
+The log message produced might look something like this::
+ '2014-02-26 21:38:27', '200', '0.791542', '592', 'DescribeVolumes'

0 comments on commit 64eedce

Please sign in to comment.