django-statsd 3.0.0__py3-none-any.whl

django_statsd/__init__.py

@@ -0,0 +1,32 @@
+"""django-statsd: submit Django query and view durations to statsd."""
+
+from importlib import metadata
+
+from django_statsd import celery, json, redis, templates
+from django_statsd.middleware import (
+    decorator,
+    decr,
+    incr,
+    named_wrapper,
+    start,
+    stop,
+    with_,
+    wrapper,
+)
+
+__version__: str = metadata.version('django-statsd')
+
+__all__ = [
+    'celery',
+    'decorator',
+    'decr',
+    'incr',
+    'json',
+    'named_wrapper',
+    'redis',
+    'start',
+    'stop',
+    'templates',
+    'with_',
+    'wrapper',
+]

django_statsd/celery.py

@@ -0,0 +1,54 @@
+"""Celery signal integration submitting task counters and timings."""
+
+from collections.abc import Callable
+from typing import Any
+
+from django_statsd import middleware, utils
+
+try:
+    from celery.utils import dispatch
+
+    from celery import signals
+except ImportError:  # pragma: no cover
+    # celery ships no type information (see [[tool.mypy.overrides]]),
+    # so `signals`/`dispatch` are already typed `Any` for mypy and
+    # reassigning `None` here needs no ignore there. ty resolves the
+    # real `celery.utils.dispatch` module instead, so that one needs
+    # its own suppression.
+    signals = None
+    dispatch = None  # ty: ignore[invalid-assignment]
+
+
+if signals is not None and dispatch is not None:
+    counter = utils.get_counter('celery.status')
+
+    def _make_increment(signal_name: str) -> Callable[..., None]:
+        def _increment(**kwargs: Any) -> None:
+            counter.increment(signal_name)
+
+        return _increment
+
+    for _signal_name in dir(signals):
+        _instance = getattr(signals, _signal_name)
+        if isinstance(_instance, dispatch.Signal):
+            # weak=False: the receiver is a closure that would otherwise
+            # be garbage collected immediately and never fire.
+            _instance.connect(_make_increment(_signal_name), weak=False)
+
+    def start(**kwargs: Any) -> None:
+        """Open a scope when a task starts."""
+        middleware.StatsdMiddleware.start('celery')
+
+    def stop(task: Any = None, **kwargs: Any) -> None:
+        """Submit the task's metrics and close the scope."""
+        if task is not None:
+            middleware.StatsdMiddleware.stop(task.name)
+        middleware.StatsdMiddleware.scope.timings = None
+
+    def clear(**kwargs: Any) -> None:
+        """Drop the scope, so a failed task leaves no timer running."""
+        middleware.StatsdMiddleware.scope.timings = None
+
+    signals.task_prerun.connect(start)
+    signals.task_postrun.connect(stop)
+    signals.task_failure.connect(clear)

django_statsd/database.py

@@ -0,0 +1,33 @@
+"""Database query timing through Django's ``execute_wrapper`` hooks.
+
+Enabled by the ``STATSD_TRACK_DATABASE`` setting;
+:class:`~django_statsd.middleware.StatsdMiddleware` wraps every configured
+connection for the duration of each request and submits the query
+durations as ``sql.<alias>`` timings.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+QueryContext = dict[str, Any]
+ExecuteFunc = Callable[[str, Any, bool, QueryContext], Any]
+ExecuteWrapper = Callable[[ExecuteFunc, str, Any, bool, QueryContext], Any]
+
+
+def statsd_execute_wrapper(alias: str) -> ExecuteWrapper:
+    """Build an execute wrapper timing queries as ``sql.<alias>``."""
+    # Imported here to avoid a circular import: middleware imports this
+    # module when installing the wrappers.
+    from django_statsd import middleware
+
+    def timed_execute(
+        execute: ExecuteFunc,
+        sql: str,
+        params: Any,
+        many: bool,
+        context: QueryContext,
+    ) -> Any:
+        with middleware.with_(f'sql.{alias}'):
+            return execute(sql, params, many, context)
+
+    return timed_execute

django_statsd/json.py

@@ -0,0 +1,21 @@
+# The module is intentionally named `json` to mirror the patched
+# library (like `celery.py`/`redis.py`/`templates.py`); it is public
+# API (`django_statsd.json`, see `__init__.__all__` and
+# `docs/django_statsd.rst`), so renaming it would be a breaking change.
+# ruff: noqa: A005
+"""Time stdlib :mod:`json` calls as ``json.<function>`` metrics."""
+
+import json
+
+from django_statsd import middleware
+
+if not hasattr(json, 'statsd_patched'):
+    # Monkeypatching the stdlib json module: none of the checkers know
+    # about `statsd_patched`, and ty additionally resolves `json.load`
+    # et al. to their concrete stdlib signatures, so a wrapped callable
+    # is not assignable there either.
+    json.statsd_patched = True  # type: ignore[attr-defined]  # ty: ignore[unresolved-attribute]
+    json.load = middleware.wrapper('json', json.load)  # ty: ignore[invalid-assignment]
+    json.loads = middleware.wrapper('json', json.loads)  # ty: ignore[invalid-assignment]
+    json.dump = middleware.wrapper('json', json.dump)  # ty: ignore[invalid-assignment]
+    json.dumps = middleware.wrapper('json', json.dumps)  # ty: ignore[invalid-assignment]

django_statsd/middleware.py

@@ -0,0 +1,581 @@
+"""Statsd middleware tracking view, middleware and database timings."""
+
+import collections
+import functools
+import logging
+import re
+import time
+import warnings
+from collections.abc import Callable
+from contextlib import ExitStack
+from types import TracebackType
+from typing import Any, ClassVar, ParamSpec, TypeVar
+
+import statsd
+from asgiref.local import Local
+from django.db import connections
+from django.http import HttpRequest
+from django.http.response import HttpResponseBase
+
+from django_statsd import settings, utils
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+P = ParamSpec('P')
+T = TypeVar('T')
+
+GetResponse = Callable[[HttpRequest], HttpResponseBase]
+
+TAGS_LIKE_SUPPORTED: tuple[str, ...] = ('=', '_is_')
+
+
+def _get_tags_like() -> str | None:
+    """Validate ``STATSD_TAGS_LIKE`` into a separator or ``None``."""
+    tags_like = settings.STATSD_TAGS_LIKE
+    if tags_like is None:
+        return None
+    if tags_like is True:
+        return '_is_'
+    if tags_like in TAGS_LIKE_SUPPORTED:
+        return str(tags_like)
+
+    warnings.warn(
+        'Unsupported `STATSD_TAGS_LIKE` setting. '
+        f'Please, choose from {TAGS_LIKE_SUPPORTED!r}',
+        stacklevel=2,
+    )
+    return None
+
+
+MAKE_TAGS_LIKE: str | None = _get_tags_like()
+
+
+def is_ajax(request: HttpRequest) -> bool:
+    """Recreate the old Django ``is_ajax`` check (jQuery-style ajax)."""
+    return request.headers.get('x-requested-with') == 'XMLHttpRequest'
+
+
+class WithTimer:
+    """Context manager returned by calling a :class:`Timer`."""
+
+    def __init__(self, timer: 'Timer', key: str) -> None:
+        """Bind the timer and the key this block will be recorded under."""
+        self.timer = timer
+        self.key = key
+
+    def __enter__(self) -> None:
+        """Start the timer."""
+        self.timer.start(self.key)
+
+    def __exit__(
+        self,
+        type_: type[BaseException] | None,
+        value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Stop the timer, however the block was left."""
+        self.timer.stop(self.key)
+
+
+class Client:
+    """Base for the scope's metric holders.
+
+    Collects values during a request and submits them in one go, so a
+    request produces one burst of packets instead of a trickle.
+    """
+
+    class_: ClassVar[type[Any]] = statsd.Client
+
+    def __init__(self, prefix: str = 'view') -> None:
+        """Build the prefix, nesting it under ``STATSD_PREFIX``."""
+        if settings.STATSD_PREFIX:
+            prefix = f'{settings.STATSD_PREFIX}.{prefix}'
+        self.prefix: str = prefix
+
+    def get_client(self, *args: str | None) -> Any:
+        """Build a python-statsd client for this prefix plus `args`."""
+        prefix = '.'.join(a for a in (self.prefix, *args) if a)
+        return utils.get_client(prefix, class_=self.class_)
+
+    def submit(self, *args: str | None) -> None:
+        """Send everything collected. Subclasses define what that means.
+
+        Raises:
+            NotImplementedError: always, on the base class.
+
+        """
+        raise NotImplementedError('Subclasses must define a `submit` function')
+
+
+class Counter(Client):
+    """Counters accumulated over one request or task."""
+
+    class_: ClassVar[type[Any]] = statsd.Counter
+
+    def __init__(self, prefix: str = 'view') -> None:
+        """Start with every counter at zero."""
+        super().__init__(prefix)
+        self.data: collections.defaultdict[str, int] = collections.defaultdict(
+            int
+        )
+
+    def increment(self, key: str, delta: int = 1) -> None:
+        """Add `delta` to `key`."""
+        self.data[key] += delta
+
+    def decrement(self, key: str, delta: int = 1) -> None:
+        """Subtract `delta` from `key`."""
+        self.data[key] -= delta
+
+    def submit(self, *args: str | None) -> None:
+        """Send every counter that moved. Zeroes are not worth a packet."""
+        client = self.get_client(*args)
+        for key, value in self.data.items():
+            if value:
+                client.increment(key, value)
+
+
+class Timer(Client):
+    """Timings accumulated over one request or task.
+
+    A key may be started more than once before it is stopped, so the
+    starts are kept on a stack and the durations add up.
+    """
+
+    class_: ClassVar[type[Any]] = statsd.Timer
+
+    def __init__(self, prefix: str = 'view') -> None:
+        """Start with no timers running and nothing recorded."""
+        super().__init__(prefix)
+        self.starts: collections.defaultdict[str, collections.deque[float]] = (
+            collections.defaultdict(collections.deque)
+        )
+        self.data: collections.defaultdict[str, float] = (
+            collections.defaultdict(float)
+        )
+
+    def start(self, key: str) -> None:
+        """Start timing `key`."""
+        self.starts[key].append(time.time())
+
+    def stop(self, key: str) -> float:
+        """Stop timing `key` and add the elapsed time to its total.
+
+        Args:
+            key: The name passed to a matching :meth:`start`.
+
+        Returns:
+            The seconds that elapsed since that `start`.
+
+        Raises:
+            AssertionError: if `key` was never started.
+
+        """
+        assert self.starts[key], (
+            f'Unable to stop tracking {key}, never started tracking it'
+        )
+
+        delta = time.time() - self.starts[key].pop()
+        # Clean up when we're done
+        if not self.starts[key]:
+            del self.starts[key]
+
+        self.data[key] += delta
+        return delta
+
+    def submit(self, *args: str | None) -> None:
+        """Send every recorded timing and clear them.
+
+        Raises:
+            AssertionError: under ``STATSD_DEBUG``, if a timer was
+                started and never stopped.
+
+        """
+        client = self.get_client(*args)
+        for key in list(self.data.keys()):
+            client.send(key, self.data.pop(key))
+
+        if settings.STATSD_DEBUG:
+            assert not self.starts, (
+                f'Timer(s) {dict(self.starts)!r} were started but '
+                'never stopped'
+            )
+
+    def __call__(self, key: str) -> WithTimer:
+        """Return a context manager timing `key`."""
+        return WithTimer(self, key)
+
+
+class StatsdMiddleware:
+    """Opens the scope and submits the per-view metrics.
+
+    Goes at the top of ``MIDDLEWARE``, with
+    :class:`StatsdMiddlewareTimer` at the bottom. The scope lives on
+    :class:`asgiref.local.Local`, so each request gets its own under
+    both WSGI and ASGI.
+    """
+
+    scope: ClassVar[Local] = Local()
+
+    def __init__(self, get_response: GetResponse) -> None:
+        """Store the next callable in the middleware chain."""
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponseBase:
+        """Time one request, wrapping the database if asked to."""
+        # Store the timings in the request so it can be used everywhere
+        self.process_request(request)
+        try:
+            with ExitStack() as stack:
+                if settings.STATSD_TRACK_DATABASE:
+                    # Imported here to avoid a circular import at load
+                    # time: database.py needs this module's helpers.
+                    from django_statsd import database
+
+                    for alias in connections:
+                        stack.enter_context(
+                            connections[alias].execute_wrapper(
+                                database.statsd_execute_wrapper(alias)
+                            )
+                        )
+                response = self.get_response(request)
+            return self.process_response(request, response)
+        finally:
+            self.cleanup(request)
+
+    @classmethod
+    def _scope_get(cls, name: str) -> Any:
+        return getattr(cls.scope, name, None)
+
+    @classmethod
+    def skip_view(cls, view_name: str) -> bool:
+        """Whether `view_name` matches ``STATSD_VIEWS_TO_SKIP``."""
+        for pattern in settings.STATSD_VIEWS_TO_SKIP:
+            if re.match(pattern, view_name):
+                logger.debug('Skipping metric `%s`', view_name)
+                return True
+
+        return False
+
+    @classmethod
+    def start(cls, prefix: str = 'view') -> Local:
+        """Open a scope and start the total timer.
+
+        Args:
+            prefix: The metric prefix, ``view`` for requests and
+                ``celery`` for tasks.
+
+        Returns:
+            The scope, which the middleware puts on ``request.statsd``.
+
+        """
+        cls.scope.timings = Timer(prefix)
+        cls.scope.timings.start('total')
+        cls.scope.counter = Counter(prefix)
+        cls.scope.counter.increment('hit')
+        cls.scope.counter_codes = Counter(prefix)
+        cls.scope.counter_codes.increment('hit')
+        cls.scope.counter_site = Counter(prefix)
+        cls.scope.counter_site.increment('hit')
+        cls.scope.view_name = None
+        return cls.scope
+
+    @classmethod
+    def stop(cls, *key: str) -> None:
+        """Stop the total timer and submit everything collected."""
+        timings: Timer | None = cls._scope_get('timings')
+        if not timings:
+            return
+
+        timings.stop('total')
+        timings.submit(*key)
+        counter: Counter | None = cls._scope_get('counter')
+        if counter:
+            counter.submit(*key)
+        counter_site: Counter | None = cls._scope_get('counter_site')
+        if counter_site:
+            counter_site.submit('site')
+
+    def process_request(self, request: HttpRequest) -> None:
+        """Open the scope and hang it off the request."""
+        # request.statsd is a documented dynamic attribute (see
+        # docs/django_statsd.rst) set by this middleware; neither
+        # django-stubs nor ty know about it.
+        request.statsd = self.start()  # type: ignore[attr-defined]  # ty: ignore[unresolved-attribute]
+        if settings.STATSD_TRACK_MIDDLEWARE:
+            self.scope.timings.start('process_request')
+
+    def process_view(
+        self,
+        request: HttpRequest,
+        view_func: Callable[..., HttpResponseBase],
+        view_args: tuple[Any, ...],
+        view_kwargs: dict[str, Any],
+    ) -> None:
+        """Name the metric after the view Django resolved."""
+        timings: Timer | None = self._scope_get('timings')
+        if settings.STATSD_TRACK_MIDDLEWARE and timings:
+            timings.start('process_view')
+
+        # View name is defined as module.view
+        # (e.g. django.contrib.auth.views.login)
+        view_name = view_func.__module__
+
+        # CBV and callable-instance specific
+        if hasattr(view_func, '__name__'):
+            view_name = f'{view_name}.{view_func.__name__}'
+        else:
+            view_name = f'{view_name}.{view_func.__class__.__name__}'
+
+        if MAKE_TAGS_LIKE:
+            view_name = view_name.replace('.', '_')
+            view_name = f'view{MAKE_TAGS_LIKE}{view_name}'
+
+        self.scope.view_name = view_name
+
+    def process_response(
+        self,
+        request: HttpRequest,
+        response: HttpResponseBase,
+    ) -> HttpResponseBase:
+        """Count the status class and submit the request's metrics."""
+        view_name: str | None = self._scope_get('view_name')
+        if view_name and self.skip_view(view_name):
+            return response
+
+        counter_codes: Counter | None = self._scope_get('counter_codes')
+        if counter_codes:
+            counter_codes.increment(f'{response.status_code // 100}xx')
+            counter_codes.submit('http_codes')
+
+        timings: Timer | None = self._scope_get('timings')
+        if settings.STATSD_TRACK_MIDDLEWARE and timings:
+            timings.stop('process_response')
+
+        method = (request.method or 'get').lower()
+        if MAKE_TAGS_LIKE:
+            tag_method = f'method{MAKE_TAGS_LIKE}{method.replace(".", "_")}'
+            ajax = f'is_ajax_{MAKE_TAGS_LIKE}{str(is_ajax(request)).lower()}'
+            if view_name:
+                self.stop(tag_method, view_name, ajax)
+        else:
+            if is_ajax(request):
+                method += '_ajax'
+            if view_name:
+                self.stop(method, view_name)
+
+        self.cleanup(request)
+        return response
+
+    def process_exception(
+        self,
+        request: HttpRequest,
+        exception: BaseException,
+    ) -> None:
+        """Stop the timer and count the failure as a 5xx."""
+        timings: Timer | None = self._scope_get('timings')
+        if settings.STATSD_TRACK_MIDDLEWARE and timings:
+            timings.stop('process_exception')
+
+        counter_codes: Counter | None = self._scope_get('counter_codes')
+        if counter_codes:
+            counter_codes.increment('5xx')
+            counter_codes.submit('http_codes')
+
+    def process_template_response(
+        self,
+        request: HttpRequest,
+        response: HttpResponseBase,
+    ) -> HttpResponseBase:
+        """Stop the template timer."""
+        timings: Timer | None = self._scope_get('timings')
+        if settings.STATSD_TRACK_MIDDLEWARE and timings:
+            timings.stop('process_template_response')
+        return response
+
+    def cleanup(self, request: HttpRequest) -> None:
+        """Clear the scope so the next request starts fresh."""
+        self.scope.timings = None
+        self.scope.counter = None
+        self.scope.counter_codes = None
+        self.scope.counter_site = None
+        self.scope.view_name = None
+        request.statsd = None  # type: ignore[attr-defined]  # ty: ignore[unresolved-attribute]
+
+
+class StatsdMiddlewareTimer:
+    """Closes the timers :class:`StatsdMiddleware` opened.
+
+    Goes at the bottom of ``MIDDLEWARE``. Between the pair they time
+    every middleware you install in between.
+    """
+
+    def __init__(self, get_response: GetResponse) -> None:
+        """Store the next callable in the middleware chain."""
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponseBase:
+        """Time the inner half of the stack."""
+        self.process_request(request)
+        return self.process_response(request, self.get_response(request))
+
+    @staticmethod
+    def _timings() -> Timer | None:
+        if settings.STATSD_TRACK_MIDDLEWARE:
+            return getattr(StatsdMiddleware.scope, 'timings', None)
+        return None
+
+    def process_request(self, request: HttpRequest) -> None:
+        """Stop the inbound timer the tracker started."""
+        timings = self._timings()
+        if timings:
+            timings.stop('process_request')
+
+    def process_view(
+        self,
+        request: HttpRequest,
+        view_func: Callable[..., HttpResponseBase],
+        view_args: tuple[Any, ...],
+        view_kwargs: dict[str, Any],
+    ) -> None:
+        """Stop the view timer."""
+        timings = self._timings()
+        if timings:
+            timings.stop('process_view')
+
+    def process_response(
+        self,
+        request: HttpRequest,
+        response: HttpResponseBase,
+    ) -> HttpResponseBase:
+        """Start the outbound timer the tracker will stop."""
+        timings = self._timings()
+        if timings:
+            timings.start('process_response')
+        return response
+
+    def process_exception(
+        self,
+        request: HttpRequest,
+        exception: BaseException,
+    ) -> None:
+        """Start the exception timer the tracker will stop."""
+        timings = self._timings()
+        if timings:
+            timings.start('process_exception')
+
+    def process_template_response(
+        self,
+        request: HttpRequest,
+        response: HttpResponseBase,
+    ) -> HttpResponseBase:
+        """Start the template timer the tracker will stop."""
+        timings = self._timings()
+        if timings:
+            timings.start('process_template_response')
+        return response
+
+
+class DummyWith:
+    """Stands in for :class:`WithTimer` outside a tracked request.
+
+    Lets the module-level helpers be used anywhere without the caller
+    checking whether a request is being timed.
+    """
+
+    def __enter__(self) -> None:
+        """Do nothing."""
+
+    def __exit__(
+        self,
+        type_: type[BaseException] | None,
+        value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Do nothing."""
+
+
+def _timings() -> Timer | None:
+    return getattr(StatsdMiddleware.scope, 'timings', None)
+
+
+def _counter() -> Counter | None:
+    return getattr(StatsdMiddleware.scope, 'counter', None)
+
+
+def start(key: str) -> None:
+    """Start timing `key` in the current scope, if there is one."""
+    timings = _timings()
+    if timings:
+        timings.start(key)
+
+
+def stop(key: str) -> float | None:
+    """Stop timing `key`.
+
+    Returns:
+        The elapsed seconds, or ``None`` outside a tracked request.
+
+    """
+    timings = _timings()
+    if timings:
+        return timings.stop(key)
+    return None
+
+
+def with_(key: str) -> WithTimer | DummyWith:
+    """Return a context manager timing `key`.
+
+    Returns:
+        A timer inside a tracked request, and a no-op outside one.
+
+    """
+    timings = _timings()
+    if timings:
+        return timings(key)
+    return DummyWith()
+
+
+def incr(key: str, value: int = 1) -> None:
+    """Add `value` to the counter `key`, if a scope is open."""
+    counter = _counter()
+    if counter:
+        counter.increment(key, value)
+
+
+def decr(key: str, value: int = 1) -> None:
+    """Subtract `value` from the counter `key`, if a scope is open."""
+    counter = _counter()
+    if counter:
+        counter.decrement(key, value)
+
+
+def wrapper(prefix: str, f: Callable[P, T]) -> Callable[P, T]:
+    """Wrap `f` so each call is timed as ``<prefix>.<function name>``."""
+    # Not every Callable exposes __name__ (e.g. functools.partial or a
+    # callable instance), so fall back to the type name instead of
+    # assuming a plain function.
+    name = getattr(f, '__name__', type(f).__name__)
+
+    @functools.wraps(f)
+    def _wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        with with_(f'{prefix}.{name.lower()}'):
+            return f(*args, **kwargs)
+
+    return _wrapper
+
+
+def named_wrapper(name: str, f: Callable[P, T]) -> Callable[P, T]:
+    """Wrap `f` so each call is timed as `name`."""
+
+    @functools.wraps(f)
+    def _wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        with with_(name):
+            return f(*args, **kwargs)
+
+    return _wrapper
+
+
+def decorator(prefix: str) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Return a decorator timing each call under `prefix`."""
+    return functools.partial(wrapper, prefix)

django_statsd/redis.py

@@ -0,0 +1,47 @@
+"""Patch :class:`redis.Redis` to time commands as ``redis.<command>``."""
+
+from collections.abc import Callable
+from typing import Any, cast
+
+from django_statsd import middleware
+
+try:
+    import redis
+except ImportError:  # pragma: no cover
+    redis = None  # type: ignore[assignment]
+
+
+if (
+    # mypy infers `redis` as non-Optional here because the `except
+    # ImportError: redis = None` assignment above is itself a type
+    # error (silenced via ignore[assignment]) and so does not widen
+    # the declared type; the guard is still required at runtime for
+    # environments where the optional `redis` dependency is missing.
+    redis is not None  # type: ignore[redundant-expr]
+    and not getattr(redis.Redis, 'statsd_patched', False)
+):
+    # The pre-patch class, kept as a handle for tests and for anything
+    # that needs to reach past the patch. The class below subclasses
+    # `redis.Redis` by name so its base stays statically resolvable.
+    _original_redis = redis.Redis
+
+    class StatsdRedis(redis.Redis):
+        """A :class:`redis.Redis` that times every command it runs."""
+
+        statsd_patched = True
+
+        def execute_command(self, *args: Any, **kwargs: Any) -> Any:
+            """Run a command, timed as ``redis.<command>``."""
+            name = str(args[0]).lower() if args else 'unknown'
+            with middleware.with_(f'redis.{name}'):
+                # redis ships py.typed but leaves execute_command
+                # unannotated. Casting keeps the unknown from leaking
+                # into this method's return value.
+                # mypy already reads it as Callable, hence the
+                # redundant-cast suppression.
+                call = cast(  # type: ignore[redundant-cast]
+                    'Callable[..., Any]', super().execute_command
+                )
+                return call(*args, **kwargs)
+
+    redis.Redis = StatsdRedis  # type: ignore[misc]  # ty: ignore[invalid-assignment]

django_statsd/settings.py

@@ -0,0 +1,62 @@
+"""Django settings wrappers with safe defaults for django-statsd."""
+
+from typing import Any
+
+from django.conf import settings
+from django.core import exceptions
+
+
+def get_setting(key: str, default: Any = None) -> Any:
+    """Read `key` from Django's settings.
+
+    Returns `default` when Django is not configured yet, so importing
+    this module never raises.
+
+    """
+    try:
+        return getattr(settings, key, default)
+    except exceptions.ImproperlyConfigured:
+        return default
+
+
+#: Enable tracking all requests using the middleware
+STATSD_TRACK_MIDDLEWARE = get_setting('STATSD_TRACK_MIDDLEWARE', False)
+
+#: Set the global statsd prefix if needed. Otherwise use the root
+STATSD_PREFIX = get_setting('STATSD_PREFIX')
+
+#: Enable warnings such as timers which are started but not finished.
+#: Defaults to ``DEBUG`` if not configured
+STATSD_DEBUG = get_setting('STATSD_DEBUG', get_setting('DEBUG'))
+
+#: Statsd disabled mode, avoids sending metrics to the real server.
+#: Useful for debugging purposes.
+STATSD_DISABLED = get_setting('STATSD_DISABLED', False)
+
+#: Enable creating tags as well as the bare version. This causes an ajax
+#: view to be stored both as the regular view name and as the ajax tag.
+#: Supported separators are ``_is_`` and ``=``
+STATSD_TAGS_LIKE = get_setting('STATSD_TAGS_LIKE')
+
+#: Statsd host, defaults to 127.0.0.1
+STATSD_HOST = get_setting('STATSD_HOST', '127.0.0.1')
+
+#: Statsd port, defaults to 8125
+STATSD_PORT = get_setting('STATSD_PORT', 8125)
+
+#: Statsd sample rate, lowering this decreases the (random) odds of
+#: actually submitting the data. Between 0 and 1 where 1 means always
+STATSD_SAMPLE_RATE = get_setting('STATSD_SAMPLE_RATE', 1.0)
+
+#: List of regular expressions of views to skip
+STATSD_VIEWS_TO_SKIP = get_setting(
+    'STATSD_VIEWS_TO_SKIP',
+    [
+        r'django.contrib.admin',
+    ],
+)
+
+#: Track database query timings via ``connection.execute_wrapper``. The
+#: middleware wraps every configured connection for the duration of each
+#: request and submits ``sql.<alias>`` timings.
+STATSD_TRACK_DATABASE = get_setting('STATSD_TRACK_DATABASE', False)

django_statsd/templates.py

@@ -0,0 +1,15 @@
+"""Time Django template rendering as ``render_django`` metrics."""
+
+from django.template import loader
+
+from django_statsd import middleware
+
+if not hasattr(loader, 'statsd_patched'):
+    # Monkeypatching django.template.loader: none of the checkers know
+    # about `statsd_patched`, and ty additionally resolves
+    # `render_to_string` to its concrete signature, so the wrapped
+    # callable is not assignable there either.
+    loader.statsd_patched = True  # type: ignore[attr-defined]  # ty: ignore[unresolved-attribute]
+    loader.render_to_string = middleware.named_wrapper(  # ty: ignore[invalid-assignment]
+        'render_django', loader.render_to_string
+    )

django_statsd/utils.py

@@ -0,0 +1,51 @@
+"""Helpers to build python-statsd connections and clients."""
+
+from typing import Any
+
+import statsd
+
+from django_statsd import settings
+
+
+def get_connection(
+    host: str | None = None,
+    port: int | None = None,
+    sample_rate: float | None = None,
+    disabled: bool | None = None,
+) -> Any:
+    """Build a python-statsd connection, defaulting to the settings."""
+    if not host:
+        host = settings.STATSD_HOST
+
+    if not port:
+        port = settings.STATSD_PORT
+
+    if not sample_rate:
+        sample_rate = settings.STATSD_SAMPLE_RATE
+
+    if not disabled:
+        disabled = settings.STATSD_DISABLED
+
+    return statsd.Connection(host, port, sample_rate, disabled)
+
+
+def get_client(
+    name: str,
+    connection: Any = None,
+    class_: type[Any] = statsd.Client,
+) -> Any:
+    """Build a python-statsd client of `class_` named `name`."""
+    if not connection:
+        connection = get_connection()
+
+    return class_(name, connection)
+
+
+def get_timer(name: str, connection: Any = None) -> Any:
+    """Build a :class:`statsd.Timer` named `name`."""
+    return get_client(name, connection, statsd.Timer)
+
+
+def get_counter(name: str, connection: Any = None) -> Any:
+    """Build a :class:`statsd.Counter` named `name`."""
+    return get_client(name, connection, statsd.Counter)

django_statsd-3.0.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: django-statsd
+Version: 3.0.0
+Summary: Django app that submits query and view durations to statsd.
+Author: Rick van Hattem
+Author-email: Rick van Hattem <Wolph@Wol.ph>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Dist: asgiref>=3.6
+Requires-Dist: django>=5.2
+Requires-Dist: python-statsd>=2.1
+Requires-Dist: matplotlib>=3.8 ; extra == 'assets'
+Requires-Dist: pillow>=10.0 ; extra == 'assets'
+Requires-Dist: playwright>=1.40 ; extra == 'assets'
+Requires-Dist: django-statsd[tests] ; extra == 'dev'
+Requires-Dist: ruff>=0.15.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.14 ; extra == 'dev'
+Requires-Dist: django-stubs[compatible-mypy]>=5.1 ; extra == 'dev'
+Requires-Dist: basedpyright>=1.0 ; extra == 'dev'
+Requires-Dist: pyrefly>=0.1 ; extra == 'dev'
+Requires-Dist: ty>=0.0.1 ; extra == 'dev'
+Requires-Dist: sphinx>=8.0 ; extra == 'docs'
+Requires-Dist: furo>=2025.1 ; extra == 'docs'
+Requires-Dist: sphinxcontrib-mermaid>=1.0 ; extra == 'docs'
+Requires-Dist: pytest>=8.0 ; extra == 'tests'
+Requires-Dist: pytest-django>=4.8 ; extra == 'tests'
+Requires-Dist: pytest-cov>=6.0 ; extra == 'tests'
+Requires-Dist: coverage>=7.0 ; extra == 'tests'
+Requires-Dist: celery>=5.3 ; extra == 'tests'
+Requires-Dist: redis>=5.0 ; extra == 'tests'
+Requires-Dist: tox>=4.0 ; extra == 'tox'
+Requires-Dist: tox-uv>=1.0 ; extra == 'tox'
+Requires-Dist: tox-gh-actions>=3.0 ; extra == 'tox'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/WoLpH/django-statsd/
+Project-URL: Documentation, https://django-stats.readthedocs.io/
+Project-URL: Changelog, https://github.com/WoLpH/django-statsd/blob/master/CHANGELOG.md
+Provides-Extra: assets
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: tests
+Provides-Extra: tox
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/WoLpH/django-statsd/master/docs/images/logo.png" alt="django-statsd" width="420">
+</p>
+
+<p align="center">
+  <a href="https://github.com/WoLpH/django-statsd/actions/workflows/ci.yml"><img src="https://github.com/WoLpH/django-statsd/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/django-statsd/"><img src="https://img.shields.io/pypi/v/django-statsd" alt="PyPI"></a>
+  <a href="https://pypi.org/project/django-statsd/"><img src="https://img.shields.io/pypi/pyversions/django-statsd" alt="Python"></a>
+  <a href="https://pypi.org/project/django-statsd/"><img src="https://img.shields.io/pypi/dm/django-statsd" alt="Downloads"></a>
+  <a href="https://django-stats.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/django-stats/badge/?version=latest" alt="Documentation"></a>
+  <a href="https://github.com/WoLpH/django-statsd/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/django-statsd" alt="License"></a>
+</p>
+
+Two middleware entries, and every view, query, template and Celery task
+in your Django project reports its duration to
+[statsd](https://github.com/statsd/statsd).
+
+![Metric names arriving as requests are served](https://raw.githubusercontent.com/WoLpH/django-statsd/master/docs/images/terminal.gif)
+
+That recording is real. So is every transcript below: they are produced
+by running the code and checked by the test suite, so a claim on this
+page cannot outlive the behaviour it describes.
+
+## Quick Start
+
+```bash
+pip install django-statsd
+```
+
+```python
+INSTALLED_APPS = [
+    'django_statsd',
+]
+
+MIDDLEWARE = [
+    'django_statsd.middleware.StatsdMiddleware',
+    'django_statsd.middleware.StatsdMiddlewareTimer',
+]
+
+STATSD_HOST = '127.0.0.1'
+STATSD_PORT = 8125
+STATSD_PREFIX = 'myproject'
+STATSD_TRACK_MIDDLEWARE = True
+```
+
+The tracker goes at the top of `MIDDLEWARE` and the timer at the
+bottom. Your own middlewares go between them, and the pair times
+everything in between.
+
+## What you get
+
+One `GET /dashboard/` puts this on the wire:
+
+<!-- transcript: views -->
+```text
+myproject.view.get.myproject.views.dashboard.hit
+myproject.view.get.myproject.views.dashboard.process_request
+myproject.view.get.myproject.views.dashboard.process_response
+myproject.view.get.myproject.views.dashboard.process_view
+myproject.view.get.myproject.views.dashboard.total
+myproject.view.http_codes.2xx
+myproject.view.http_codes.hit
+myproject.view.site.hit
+```
+<!-- /transcript -->
+
+`total` is the request, the three `process_*` names are the phases
+inside it, and `hit` is a counter so you get a rate per view without
+dividing anything. The last two are project-wide.
+
+## Features
+
+- **Views** timed by method and dotted view path, with status classes
+  counted separately
+- **Queries** timed through Django's `execute_wrapper`, nested under
+  the view that ran them, so you get query time per view
+- **Celery tasks** timed per task, plus a counter for every signal
+  Celery exports
+- **Templates, `json` and `redis`** patched on import and timed
+  without a line of configuration
+- **Your own code**, timed through `request.statsd` or the
+  module-level helpers, nested under the view that was running
+- **Async safe.** The scope lives on `asgiref.local.Local`, so ASGI
+  and async views report correctly
+
+## Requirements
+
+- Python 3.10 through 3.14
+- Django 5.2, 6.0 or 6.1
+
+Celery and redis are optional. django-statsd patches them if they
+import and does nothing if they don't.
+
+## Where your milliseconds go
+
+![Timing breakdown of one request](https://raw.githubusercontent.com/WoLpH/django-statsd/master/docs/images/timing_breakdown.png)
+
+Recorded from a real request. The phases don't sum to
+`total`, and the gap is the part of the request outside the section
+the middleware pair wraps.
+
+## Usage Examples
+
+Time a block inside a view through `request.statsd`:
+
+```python
+def some_view(request):
+    with request.statsd.timings('build_queryset'):
+        ...
+
+def some_other_view(request):
+    request.statsd.timings.start('build_queryset')
+    ...
+    request.statsd.timings.stop('build_queryset')
+```
+
+Or reach the same scope from anywhere during a tracked request, and
+from inside a Celery task:
+
+```python
+import django_statsd
+
+with django_statsd.with_('payment.authorise'):
+    ...
+
+django_statsd.incr('payment.attempt')
+
+@django_statsd.decorator('payment')
+def authorise():
+    ...
+```
+
+Both land nested inside the view that was running, so the same helper
+called from two views gives you two series.
+
+## In a dashboard
+
+![django-statsd metrics in Grafana](https://raw.githubusercontent.com/WoLpH/django-statsd/master/docs/images/dashboard.png)
+
+statsd, Graphite and Grafana, fed by django-statsd over UDP. The
+compose file and the provisioning that produced this are in
+`docs/generate/dashboard/`.
+
+## Settings
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `STATSD_HOST` | `127.0.0.1` | Where to send |
+| `STATSD_PORT` | `8125` | Which port |
+| `STATSD_PREFIX` | none | Nests every metric under one name |
+| `STATSD_TRACK_MIDDLEWARE` | `False` | The view metrics |
+| `STATSD_TRACK_DATABASE` | `False` | Query timings |
+| `STATSD_SAMPLE_RATE` | `1.0` | Odds a metric is really sent |
+| `STATSD_VIEWS_TO_SKIP` | admin | Regexes of views to ignore |
+| `STATSD_DISABLED` | `False` | Loaded and silent |
+| `STATSD_DEBUG` | `DEBUG` | Warn about unstopped timers |
+
+Full list with docstrings:
+[settings reference](https://django-stats.readthedocs.io/en/latest/reference/settings.html).
+
+## Documentation
+
+- [Documentation](https://django-stats.readthedocs.io/en/latest/)
+- [Metric reference](https://django-stats.readthedocs.io/en/latest/reference/metrics.html)
+- [Changelog](https://github.com/WoLpH/django-statsd/blob/master/CHANGELOG.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/WoLpH/django-statsd/blob/master/CONTRIBUTING.md).
+Every code sample on this page is executed by the test suite, so a
+change to the API that breaks an example fails the build.
+
+## Links
+
+- [Source](https://github.com/WoLpH/django-statsd)
+- [Issues](https://github.com/WoLpH/django-statsd/issues)
+- [PyPI](https://pypi.org/project/django-statsd/)
+
+## License
+
+[BSD 3-Clause](https://github.com/WoLpH/django-statsd/blob/master/LICENSE)

django_statsd-3.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+django_statsd/__init__.py,sha256=cPKLckzVLJEr8ygBrvG6S_Yopn1NlYz3JiOxCoQFc4o,541
+django_statsd/celery.py,sha256=2h4Cv-eE2-H9HkL9T8gJyTS6oRfVnUtONIcHoNyBX-c,1985
+django_statsd/database.py,sha256=lXlcxh-J9Jg2Y7tLAD5VGniBVnNLtDWiAz5pURdAado,1103
+django_statsd/json.py,sha256=gnGd0KJ2k8ZQOprpm7vnLC9Z2SUtV9aFVe8N6ZayI-4,1146
+django_statsd/middleware.py,sha256=0YN3-tlUOt6uL6yLhC0g2gx5taOH9T3dfTJACtP8nZI,18523
+django_statsd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_statsd/redis.py,sha256=kvza60PyMU86SLUR2lSaM4zi1s5XKHD2D-IGks7SXac,1951
+django_statsd/settings.py,sha256=HhUkTA4VrQ6c2sX982cMGA6xVfMxhqnvsIsdWNjSHl4,2111
+django_statsd/templates.py,sha256=p1fpQulLP3j8rIT20exnYGhgqkhNR03yKCFbpvEEFGI,672
+django_statsd/utils.py,sha256=5QKe_KwaUdy1itU-Co79T1v7z7c_CD9ajoJYABkY-1s,1297
+django_statsd-3.0.0.dist-info/licenses/LICENSE,sha256=UX7NzXkqWry4CAkM5cI43h1cCZJnWw3gbnEeOVw-9pk,1536
+django_statsd-3.0.0.dist-info/WHEEL,sha256=-i9oRNYVXXZJUIYl5zclLIg6onEb0NLibTX34uln84w,81
+django_statsd-3.0.0.dist-info/METADATA,sha256=K8FaRHkQOV7-G7Fc0ScOgsGF3AJKX3zO8WM5Mb80ncE,8899
+django_statsd-3.0.0.dist-info/RECORD,,

django_statsd-3.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.13
+Root-Is-Purelib: true
+Tag: py3-none-any

django_statsd-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2012-2026, Rick van Hattem (Wolph)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.