From ae984132721ad807aa56a7a0b4a9081b74355f9a Mon Sep 17 00:00:00 2001
From: Alexis Le-Quoc <alq@datadoghq.com>
Date: Mon, 12 May 2014 18:26:51 +0200
Subject: [PATCH] More in-depth documentation of the new instrumentation layer

---
 README.rst                    | 30 ++++++++++++++++++++++++++++++
 gunicorn/instrument/statsd.py |  1 +
 2 files changed, 31 insertions(+)

diff --git a/README.rst b/README.rst
index e0a06b5b..1ad7fbed 100644
--- a/README.rst
+++ b/README.rst
@@ -142,6 +142,35 @@ For example:
 It is all here. No configuration files nor additional python modules to
 write !!
 
+Instrumentation
+---------------
+
+Gunicorn provides an optional instrumentation of the arbiter and
+workers using the statsD_ protocol over UDP. Thanks to the 
+`gunicorn.instrument.statsd` module, Gunicorn becomes a statsD client
+The use of UDP cleanly isolates Gunicorn from the receiving end of the statsD
+metrics so that instrumentation does not cause Gunicorn to be heldeup by a slow
+statsD consumer.
+
+To use this instrumentation mechanism, simply use a new logger::
+
+    $ gunicorn --logging-class gunicorn.instrument.statsd.Statsd ...
+
+The `Statsd` logger overrides `gunicorn.glogging.Logger` to track
+all requests. The following metrics are generated:
+
+  * `gunicorn.requests`: request rate per second
+  * `gunicorn.request.duration`: histogram of request duration
+  * `gunicorn.workers`: number of workers managed by the arbiter (gauge)
+  * `gunicorn.log.critical`: rate of critical log messages
+  * `gunicorn.log.error`: rate of error log messages
+  * `gunicorn.log.warning`: rate of warning log messages
+  * `gunicorn.log.exception`: rate of exceptional log messages
+
+To generate new metrics you can `log.info` with a few additional keywords::
+
+    log.info("...", metric="my.metric", value=1.2, mtype="gauge")
+
 LICENSE
 -------
 
@@ -159,4 +188,5 @@ details.
 .. _`production page`: http://docs.gunicorn.org/en/latest/deploy.html
 .. _`config file`: http://docs.gunicorn.org/en/latest/configure.html
 .. _setproctitle: http://pypi.python.org/pypi/setproctitle/
+.. _statsD: http://github.com/etsy/statsd
 .. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE
diff --git a/gunicorn/instrument/statsd.py b/gunicorn/instrument/statsd.py
index de348a17..ec7f9697 100644
--- a/gunicorn/instrument/statsd.py
+++ b/gunicorn/instrument/statsd.py
@@ -99,6 +99,7 @@ class Statsd(Logger):
                 pass
 
     # statsD methods
+    # you can use those directly if you want
     def gauge(self, name, value):
         try:
             if self.sock: