Install & Compatibility
Where this runs
tested against v2.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
django_statsd
✓ import django_statsd
✗ import django_statsd
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!")
Debug
Known issues
breakingOlder 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.fixUpgrade `django-statsd` to the latest version (2.7.0 or newer) when upgrading Django to 4.2 or 5.0.
affects: <2.7.0
gotchaThe `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.fixEnsure your project's Python environment is running Python 3.8 or higher.
affects: All versions >=2.7.0
gotchaThe 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.fixReview your `MIDDLEWARE` configuration. Place `StatsdMiddleware` near the top and `StatsdPageTimingMiddleware` near the bottom, after other relevant middlewares, as shown in the quickstart example.
affects: All
gotchaThe `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.fixAlways use `from statsd import statsd` when you need to send custom metrics.
affects: All
Upgrade
Version history
2.7.0latest on PyPI · released Jul 21, 2024
Audit
Dependencies
DjangorequiredRequired for Django framework integration.
python-statsdrequiredProvides the underlying StatsD client functionality.