Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge pull request #2129 from dkavanagh/request_hook_docs

Add a tutorial for the request hooks addition. Fixes #2129.
  • Loading branch information...
commit 64eedcea100c46db21a74953b0d809177c746bb7 2 parents 141077f + 74eb19f
@danielgtaylor danielgtaylor authored
Showing with 62 additions and 0 deletions.
  1. +1 −0  docs/source/index.rst
  2. +61 −0 docs/source/request_hook_tut.rst
View
1  docs/source/index.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`_
View
61 docs/source/request_hook_tut.rst
@@ -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 boto.requestlog.py, 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
+thread.
+
+One thing to note is that the boto request object has an additional value
+"start_time", which is a datetime.now() 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'
+
Please sign in to comment.
Something went wrong with that request. Please try again.