statshog

Statshog is a Python client for the StatsD protocol, forked from the widely used pystatsd project to add first-class support for InfluxDB Telegraf’s tagged StatsD dialect. It ships UDP, TCP, and Unix-domain-socket transports behind a shared base client, so applications can switch how metrics reach the collector without touching call sites.

The library covers the full StatsD surface — counters, gauges, sets, and timers — plus a Timer helper usable as either a context manager or a function decorator, and a pipelining API that batches metrics before flushing them in one send. Drop-in configuration modules read settings from Django or environment variables, making it a low-friction way to add instrumentation to existing Python services.

What You Get

• UDP, TCP, and Unix-domain-socket StatsD clients sharing one protocol implementation
• Counters, gauges, sets, and millisecond timers via incr/decr/gauge/set/timing
• A Timer class usable as a context manager or a function decorator for instrumenting code blocks
• A pipeline API that batches multiple stats into fewer network sends
• Telegraf-style tagged metrics via an optional tags argument on every metric call
• Ready-made Django and environment-variable configuration modules

Common Use Cases

• Instrumenting a Django app’s request/response cycle with timing metrics read from settings.py
• Emitting tagged metrics from a service to a Telegraf agent for storage in InfluxDB
• Wrapping hot functions with the @timer decorator to track latency without duplicating instrumentation code
• Batching many counters in a single request using the pipeline() context manager to cut UDP packet count
• Switching a service between UDP, TCP, or Unix-socket transport to the metrics collector without changing call sites

Under The Hood

Architecture The library centers on StatsClientBase in statshog/client/base.py, which owns all protocol-formatting logic — building the stat:value|type wire format, applying prefixes, sample rates, and Telegraf tag suffixes — while leaving _send abstract. Three concrete transports subclass it: StatsClient (UDP, in client/udp.py), and TCPStatsClient/UnixSocketStatsClient (both built on a shared StreamClientBase in client/stream.py) that add lazy connect/reconnect semantics. A parallel PipelineBase hierarchy mirrors this split — the UDP Pipeline coalesces buffered stats up to maxudpsize before flushing, while the stream StreamPipeline simply joins buffered stats with newlines — so batching behavior stays specific to each transport’s constraints. A separate Timer class in client/timer.py composes with any client via constructor injection, letting it double as a context manager or a decorator without the base client needing to know about it.

Tech Stack Pure Python 3.6+ with no runtime dependencies — only the standard library’s socket and collections.deque are used in the core client. The package ships a py.typed marker for PEP 561 type-checking support and is built with a classic setup.py/setuptools layout rather than a pyproject.toml. Development tooling (requirements.txt) pins flake8 for linting, mypy for type-checking, and the legacy nose/mock combination for testing. Documentation is built with Sphinx (docs/conf.py, multiple .rst pages), and GitHub Actions workflows handle both test runs and PyPI publishing.

Code Quality Type hints are applied consistently across the client classes and shipped for downstream consumers via py.typed. Tests in statshog/tests.py use nose and mock to parametrize the same assertions across all three transports (UDP/TCP/Unix), checking wire-format output, sampling, and pipelining behavior. Error handling is deliberately permissive rather than strict: the UDP client’s _send swallows socket.error/RuntimeError outright so a down metrics collector can never crash the instrumented application — a common, intentional pattern for fire-and-forget metrics clients rather than an oversight. Naming and structure are consistent and flake8-clean, though the project has had no commits since its 2021 fork and still relies on the unmaintained nose test runner.

API Design The public API mirrors the long-established pystatsd conventions (incr, decr, gauge, set, timing) so it’s immediately familiar to anyone who has used a StatsD client before, while adding two concrete improvements: a tags keyword threaded through every metric call that raises a clear ValueError if used without telegraf=True (rather than silently dropping tags), and ready-made statshog.defaults.django / statshog.defaults.env modules that construct a configured client automatically from Django settings or environment variables. The Timer class’s dual context-manager/decorator interface lets a single class cover both “time this block” and “time this function” without extra code.