From 55f824686a84cfb0a970205fd76cce7a8b50a07b Mon Sep 17 00:00:00 2001
From: Andy McKay <amckay@mozilla.com>
Date: Thu, 22 Dec 2011 09:22:42 -0800
Subject: [PATCH] license and readme updates

---
 LICENSE.rst |  4 +++-
 README.rst  | 60 ++++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 51 insertions(+), 13 deletions(-)

diff --git a/LICENSE.rst b/LICENSE.rst
index d3564e9..6770c52 100644
--- a/LICENSE.rst
+++ b/LICENSE.rst
@@ -1,3 +1,5 @@
 BSD and MPL
 
-Todo: portions of this is from commonware
+Portions of this are from commonware:
+
+https://github.com/jsocol/commonware/blob/master/LICENSE
diff --git a/README.rst b/README.rst
index 5fda5de..23bda11 100644
--- a/README.rst
+++ b/README.rst
@@ -1,18 +1,39 @@
+Django Statsd
+=============
+
 Integration between statsd and django. It allows you to use different clients,
 sends timings as middleware and integrates with django debug toolbar.
 
-Requirement, pystatsd: https://github.com/jsocol/pystatsd
+Credits:
+
+- jbalogh and jsocol for statsd and commonware, which I just ripped parts out
+  of and put in here.
+- robhudson for django-debug-toolbar
+
+Requirement, pystatsd:
+
+https://github.com/jsocol/pystatsd
 
 First off, pick your client, one of:
 
-- django_statsd.clients.null  (does nothing, good for development)
-- django_statsd.clients.toolbar  (use for the toolbar)
-- django_statsd.clients.statsd  (use for production, just passes through to pystatsd)
+- django_statsd.clients.null
+
+  This one does nothing, good for development. No point in wasting those UDP
+  packets.
+
+- django_statsd.clients.toolbar
+
+  Use for the django debug toolbar, stores all the statsd pings on the request
+  so they can be used in the toolbar.
+
+- django_statsd.clients.statsd
+
+  Use this for production, it just passes through to the real actual pystatsd.
 
 Usage
 -----
 
-To send timings from your code, use just like statsd, but change your imports
+To send timings from your code, use just like pystatsd, but change your imports
 to read::
 
         from django_statsd.clients import statsd
@@ -22,6 +43,12 @@ For example::
         from django_statsd.clients import statsd
         statsd.incr('response.200')
 
+Django statsd will choose the client as specified in your config and send the
+data to it. You can change you client by specifying it in the config, the
+default is::
+
+        STATSD_CLIENT = 'django_statsd.clients.statsd'
+
 To send timings or counts with every request, add in some middleware::
 
         MIDDLEWARE_CLASSES = (
@@ -45,7 +72,8 @@ This will show you the statsd timings in the toolbar::
                 'debug_toolbar.middleware.DebugToolbarMiddleware',
                 ) + MIDDLEWARE_CLASSES
 
-Note: this must go before the GraphiteMiddleware.
+Note: this must go before the GraphiteMiddleware so that we've got the timing
+data in before we show the toolbar panel.
 
 Add in the panel::
 
@@ -58,9 +86,11 @@ Set the client::
 
         STATSD_CLIENT = 'django_statsd.clients.toolbar'
 
-Finally, to show data from a graphite server, if you have one, link it up::
+Finally if you have production data coming into a graphite server, you can
+show data from that server. If you have one, link it up::
 
-Configure where the toolbar shows graphs::
+Here's the configuration we use on AMO. Because triggers and counts go
+to different spots, you can configure them differently::
 
         TOOLBAR_STATSD = {
                 'graphite': 'https://graphite-phx.mozilla.org/render/',
@@ -70,8 +100,14 @@ Configure where the toolbar shows graphs::
                 }
         }
 
-Credits:
+The key is added on to the root. So if you've got a key of `view.GET` this
+would look that up on the graphite server with the key::
 
-- jbalogh and jsocol for statsd and commonware, which I just ripped out
-  and put in here.
-- robhudson for django-debug-toolbar
+        stats.addons.view.GET
+
+More
+----
+
+- More tests.
+
+- More measuring things.