Add statsd example.

docs/examples.rst

@@ -0,0 +1,18 @@
+Examples
+========
+
+Sending metrics to StatsD
+-------------------------
+This simple application emits metrics to port 8125 on localhost.  The
+mix-in is configured by passing a ``sprockets.mixins.metrics.statsd``
+key into the application settings as shown below.
+
+.. literalinclude:: ../examples/statsd.py
+   :pyobject: make_application
+
+The request handler is simple.  In fact, there is nothing of interest
+there except that it uses :class:`~sprockets.mixins.metrics.StatsdMixin`
+as a base class.
+
+.. literalinclude:: ../examples/statsd.py
+   :pyobject: SimpleHandler

docs/index.rst

@@ -7,5 +7,6 @@ License
 .. toctree::
    :hidden:
 
+   examples
    contributing
    history

examples/statsd.py

@@ -0,0 +1,54 @@
+import signal
+
+from sprockets.mixins import metrics
+from tornado import gen, ioloop, web
+
+
+class SimpleHandler(metrics.StatsdMixin, web.RequestHandler):
+    """
+    Simply emits a timing metric around the method call.
+
+    The metric namespace and StatsD endpoint are configured in
+    the application settings object so there is nothing to do in
+    a request handler.
+
+    """
+
+    @gen.coroutine
+    def get(self):
+        yield gen.sleep(0.25)
+        self.set_status(204)
+        self.finish()
+
+def _sig_handler(*args_):
+    iol = ioloop.IOLoop.instance()
+    iol.add_callback_from_signal(iol.stop)
+
+
+def make_application():
+    """
+    Create a application configured to send metrics.
+
+    Metrics will be sent to localhost:8125 namespaced with
+    ``webapps``. Run netcat or a similar listener then run this
+    example. HTTP GETs will result in a metric like::
+
+        webapps.SimpleHandler.GET.204:255.24497032165527|ms
+
+    """
+    settings = {
+        metrics.StatsdMixin.SETTINGS_KEY: {
+            'namespace': 'webapps',
+            'host': '127.0.0.1',
+            'port': 8125,
+        }
+    }
+    return web.Application([web.url('/', SimpleHandler)], **settings)
+
+
+if __name__ == '__main__':
+    app = make_application()
+    app.listen(8000)
+    signal.signal(signal.SIGINT, _sig_handler)
+    signal.signal(signal.SIGTERM, _sig_handler)
+    ioloop.IOLoop.instance().start()

setup.py

@@ -36,7 +36,7 @@ setuptools.setup(
     url='https://github.com/sprockets/sprockets.mixins.metrics',
     install_requires=read_requirements('installation.txt'),
     tests_require=read_requirements('testing.txt'),
-    packages=setuptools.find_packages(),
+    packages=setuptools.find_packages(exclude=['examples.']),
     namespace_packages=['sprockets', 'sprockets.mixins'],
     classifiers=[
         'Development Status :: 1 - Planning',