{"id":4518,"library":"django-statsd","title":"Django StatsD Integration","description":"django-statsd is a Django application that integrates with Etsy's statsd service to submit query and view durations, helping monitor application performance. It's actively maintained, with minor releases typically focused on maintaining compatibility with new Django versions.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/WoLpH/django-statsd","tags":["django","monitoring","statsd","metrics"],"install":[{"cmd":"pip install django-statsd","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for Django framework integration.","package":"Django","optional":false},{"reason":"Provides the underlying StatsD client functionality.","package":"python-statsd","optional":false}],"imports":[{"note":"Used to register the app in Django's settings.","symbol":"django_statsd","correct":"INSTALLED_APPS = ['django_statsd']"},{"note":"Middleware for tracking request/response cycles.","symbol":"StatsdMiddleware","correct":"from django_statsd.middleware import StatsdMiddleware"},{"note":"Middleware for measuring page rendering time.","symbol":"StatsdPageTimingMiddleware","correct":"from django_statsd.middleware import StatsdPageTimingMiddleware"},{"note":"The primary StatsD client for custom metrics, provided by the `python-statsd` dependency.","symbol":"statsd","correct":"from statsd import statsd"}],"quickstart":{"code":"import os\n\n# settings.py\nINSTALLED_APPS = [\n    # ... other apps\n    'django_statsd',\n]\n\nMIDDLEWARE = [\n    'django.middleware.security.SecurityMiddleware',\n    # Place StatsdMiddleware early to catch all requests\n    'django_statsd.middleware.StatsdMiddleware',\n    # ... other middlewares\n    'django.contrib.sessions.middleware.SessionMiddleware',\n    'django.middleware.common.CommonMiddleware',\n    'django.middleware.csrf.CsrfViewMiddleware',\n    'django.contrib.auth.middleware.AuthenticationMiddleware',\n    'django.contrib.messages.middleware.MessageMiddleware',\n    'django.middleware.clickjacking.XFrameOptionsMiddleware',\n    # Place StatsdPageTimingMiddleware later to time page rendering\n    'django_statsd.middleware.StatsdPageTimingMiddleware',\n]\n\nSTATSD_HOST = os.environ.get('STATSD_HOST', 'localhost')\nSTATSD_PORT = int(os.environ.get('STATSD_PORT', '8125'))\nSTATSD_PREFIX = os.environ.get('STATSD_PREFIX', 'myproject')\n\n# myapp/views.py (example usage)\nfrom django.http import HttpResponse\nfrom statsd import statsd\n\ndef my_view(request):\n    statsd.incr('my_view.hits')\n    # Simulate some work\n    import time\n    time.sleep(0.05)\n    statsd.timing('my_view.processing_time', 50) # In milliseconds\n    return HttpResponse(\"Hello, Django Statsd!\")","lang":"python","description":"Configure `django-statsd` by adding it to `INSTALLED_APPS` and integrating its middlewares into your `MIDDLEWARE` list in `settings.py`. Define `STATSD_HOST`, `STATSD_PORT`, and `STATSD_PREFIX` for your StatsD server. For custom metrics, import the `statsd` client directly from the `statsd` library and use its methods (e.g., `incr`, `timing`) within your application code, such as views or services."},"warnings":[{"fix":"Upgrade `django-statsd` to the latest version (2.7.0 or newer) when upgrading Django to 4.2 or 5.0.","message":"Older versions of `django-statsd` are not compatible with newer Django versions. Specifically, versions prior to `2.7.0` lack official support for Django 4.2 and 5.0.","severity":"breaking","affected_versions":"<2.7.0"},{"fix":"Ensure your project's Python environment is running Python 3.8 or higher.","message":"The `django-statsd` library itself (version 2.7.0+) requires Python 3.8 or newer. Attempting to use it with older Python versions will result in installation or runtime errors.","severity":"gotcha","affected_versions":"All versions >=2.7.0"},{"fix":"Review your `MIDDLEWARE` configuration. Place `StatsdMiddleware` near the top and `StatsdPageTimingMiddleware` near the bottom, after other relevant middlewares, as shown in the quickstart example.","message":"The order of middlewares is crucial. `StatsdMiddleware` should generally be placed early in your `MIDDLEWARE` list to ensure it wraps all requests, even those handled by other middlewares. `StatsdPageTimingMiddleware` should be placed later, after middlewares that might affect page rendering, to accurately measure rendering time.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `from statsd import statsd` when you need to send custom metrics.","message":"The `statsd` client for sending custom metrics (`statsd.incr()`, `statsd.timing()`, etc.) is imported directly from the `statsd` package (which is `python-statsd`), not from `django_statsd`. Incorrectly trying to import it from `django_statsd` will fail.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}