Skip to main content

WSGI middleware for statsd timing

Project description

wsgi-statsd documentation Documentation Status

wsgi_statsd is a WSGI middleware that provides an easy way to time all requests. Integration is as easy as just wrapping your existing wsgi application.


In your file wrap your WSGI application as follows:

import statsd
from wsgi_statsd import StatsdTimingMiddleware

def application(environ, start_response):
    response_body = 'The request method was %s' % environ['REQUEST_METHOD']
    status = '200 OK'
    response_headers = [('Content-Type', 'text/plain'),
                        ('Content-Length', str(len(response_body)))]

    start_response(status, response_headers)

    return [response_body]

client = statsd.StatsClient(

application = StatsdTimingMiddleware(application, client)


If an unhandled exception happens, it will not be timed by default. This is a design decision to separate error reporting and actual statistical measurements. To enable exception timing, pass time_exception=True to the middleware constructor:

application = StatsdTimingMiddleware(application, client, time_exceptions=True)

What it does

wsgi-statsd uses the statsd timer function, generates a key and sets the amount of time the request took as the value. The key is constructed as follows:


Using the foo prefix, in your statsd client, and calling the page will result in foo .bar_test.GET.200 having a value equal to the time it took to handle the request.

If you passed time_exceptions=True and any exception occurs during the response, then the key name will be postfixed with the exception class name: foo.bar_test.GET.500.ValueError.

Customizing for your needs

It’s possible to customize the way wsgi_statsd generates the key and/or time. StatsdTimingMiddleware has send_stats and get_key_name which you can override:

class CustomStatsdMiddleware(StatsdTimingMiddleware):

    def get_key_name(self, environ, response_interception):
        return super(self, CustomStatsdMiddleware).get_key_name(environ, response_interception) + '.' + environ['Transfer-Encoding']

    def send_stats(self, start, environ, response_interception):
        super(self, CustomStatsdMiddleware).send_stats(start + 10, environ, response_interception)

wsgi-statsd uses underscores as a separator for the path part of the key that is sent to statsd as that makes it easy to retrieve the data from graphite. You can override this default by passing a separator value to the middleware constructor:

StatsdTimingMiddleware(application, client, separator='.')


If you have questions, bug reports, suggestions, etc. please create an issue on the GitHub project page.


This software is licensed under the MIT license.

Please refer to the license file.

© 2015 Wouter Lansu, Paylogic International and others.



  • Added clean target to Makefile.
  • Added the changes for the 0.2.6 version.


  • Updated documentation.


  • Fixed issue with the separator parameter. It now functions as expected and documented.


  • Add separator parameter to StatsdTimingMiddleware.__init__().


  • Add exception class name to the key when exception happens (bubenkoff)


  • ensure close() is properly called from the response (bubenkoff, GrahamDumpleton)
  • optionally time exceptions (bubenkoff)
  • code readability improvements (bubenkoff)


  • Fixed version numbers
  • Added support for WSGI applications returning generators
  • Added a test to verify that the response body remains the same after passing through the middleware


  • Initial public release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
wsgi-statsd-0.3.1.tar.gz (6.1 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page