Django StatsD Integration

Warnings

• breaking 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.
  Fix: Upgrade `django-statsd` to the latest version (2.7.0 or newer) when upgrading Django to 4.2 or 5.0.
• gotcha 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.
  Fix: Ensure your project's Python environment is running Python 3.8 or higher.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Always use `from statsd import statsd` when you need to send custom metrics.

Install

• pip install django-statsd Install latest version

Imports

• django_statsd

  INSTALLED_APPS = ['django_statsd']

  Used to register the app in Django's settings.
• StatsdMiddleware

  from django_statsd.middleware import StatsdMiddleware

  Middleware for tracking request/response cycles.
• StatsdPageTimingMiddleware

  from django_statsd.middleware import StatsdPageTimingMiddleware

  Middleware for measuring page rendering time.
• statsd

  from statsd import statsd

  The primary StatsD client for custom metrics, provided by the `python-statsd` dependency.

Quickstart

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.

import os

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'django_statsd',
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    # Place StatsdMiddleware early to catch all requests
    'django_statsd.middleware.StatsdMiddleware',
    # ... other middlewares
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    # Place StatsdPageTimingMiddleware later to time page rendering
    'django_statsd.middleware.StatsdPageTimingMiddleware',
]

STATSD_HOST = os.environ.get('STATSD_HOST', 'localhost')
STATSD_PORT = int(os.environ.get('STATSD_PORT', '8125'))
STATSD_PREFIX = os.environ.get('STATSD_PREFIX', 'myproject')

# myapp/views.py (example usage)
from django.http import HttpResponse
from statsd import statsd

def my_view(request):
    statsd.incr('my_view.hits')
    # Simulate some work
    import time
    time.sleep(0.05)
    statsd.timing('my_view.processing_time', 50) # In milliseconds
    return HttpResponse("Hello, Django Statsd!")