aiodogstatsd

library0.16.0.post0pypypi✓ verified 6d ago

aiodogstatsd is an asyncio-based client for sending metrics to StatsD with support for the DogStatsD extension. It supports gauge, counter, histogram, distribution, and timing metric types. The library is actively maintained, currently at version 0.16.0.post0, and features a consistent release cadence with updates for Python version compatibility and framework integrations.

observability http-networking

pip install aiodogstatsd

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · AIODOGSTATSD

aiodogstatsd

observabilitypythonv0.16.0.post0

Install

2.4s avg

Import

204ms

Disk

27MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.16.0.post0 · 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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.218s · 27.1MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 2.4s · import 0.189s · 29MB

27MB installed

● package 27MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from aiodogstatsd import Client

✗ import aiodogstatsd; client = aiodogstatsd.Client() (without then importing Client directly)

The primary client class is named `Client` and is imported directly from the top-level package.

This quickstart demonstrates how to initialize the aiodogstatsd client using an async context manager and send basic increment, gauge, and timing metrics. The context manager ensures proper connection handling. Environment variables are used for host and port configuration, defaulting to 'localhost' and '9125' respectively.

import asyncio import os from aiodogstatsd import Client async def main(): # The client uses port 9125 by default, which is common for statsd_exporter. # For DataDog Agent or standard StatsD (port 8125), configure explicitly. async with Client(host=os.environ.get('STATSD_HOST', 'localhost'), port=int(os.environ.get('STATSD_PORT', '9125'))) as client: client.increment("users.online") client.gauge("server.cpu.usage", value=42.5, tags={"region": "us-east-1"}) with client.timeit("db.query.time"): # Context manager for timing await asyncio.sleep(0.05) print("Metrics sent!") if __name__ == "__main__": asyncio.run(main())

Debug

Known issues

breakingPython 3.6 support has been dropped in version 0.16.0. Projects using this version or newer must migrate to Python 3.7 or higher.

fix

Upgrade your Python environment to 3.7 or newer. Update your `requires_python` specification if applicable.

affects: >=0.16.0

breakingSupport for the Sanic framework was dropped in version 0.16.0. Integrations (listeners, middlewares) for Sanic will no longer work with this version or newer.

fix

If migrating from an older version, remove Sanic-specific integration code. Consider using a Sanic-native StatsD client if Sanic integration is critical, or integrate aiodogstatsd manually if possible for your use case.

affects: >=0.16.0

gotchaThe aiodogstatsd client defaults to port 9125, which is the default for `statsd_exporter`. Standard StatsD and DataDog Agent typically use port 8125. If you're targeting a standard StatsD server or Datadog Agent, you must explicitly set the port during client initialization.

fix

Initialize the client with `Client(port=8125, ...)` if targeting a standard StatsD or Datadog Agent setup.

affects: All versions

gotchaWhile direct `Client` instantiation and manual `await client.connect()` and `await client.close()` calls are possible, using the `async with Client(...) as client:` context manager is the recommended pattern. It ensures that connections are properly initialized and gracefully closed, even in the event of exceptions.

fix

Adopt the `async with` context manager pattern for client initialization and usage to prevent resource leaks and ensure robustness.

affects: All versions

gotchaAs StatsD uses UDP for metric submission, packets can be dropped in high-throughput network scenarios due to network congestion or OS buffer limits, especially in containerized environments. This is a general characteristic of the StatsD protocol, not specific to `aiodogstatsd`.

fix

Monitor for dropped metrics. Consider optimizing network settings, increasing UDP buffer sizes on the host, or exploring client-side aggregation features (if available in a StatsD client, though not a primary feature of `aiodogstatsd`) to reduce packet volume. Ensure your StatsD server (e.g., Datadog Agent) is adequately resourced.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'aiodogstatsd'

The 'aiodogstatsd' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install aiodogstatsd'.

TypeError: 'Client' object is not callable

Attempting to call an instance of 'aiodogstatsd.Client' as a function.

fix

Ensure that 'aiodogstatsd.Client' is instantiated correctly and not called as a function.

AttributeError: module 'aiodogstatsd' has no attribute 'Client'

The 'aiodogstatsd' module does not have a 'Client' attribute, possibly due to an incorrect import.

fix

Import the 'Client' class correctly: 'from aiodogstatsd import Client'.

ConnectionRefusedError: [Errno 111] Connection refused

The application is unable to connect to the StatsD server, possibly because the server is not running or is listening on a different port.

fix

Verify that the StatsD server is running and that the host and port settings in 'aiodogstatsd.Client' match the server's configuration.

RuntimeError: Event loop is closed

An attempt was made to run an asyncio operation after the event loop was closed.

fix

Ensure that all asyncio operations are completed before closing the event loop, and avoid running new operations after it has been closed.

Upgrade

Version history

0.16.0.post0latest on PyPI · released Dec 12, 2021

Audit

Dependencies

pythonrequiredRequires Python 3.7 or newer, but less than 4.0.

aiohttpoptionalOptional dependency for AIOHTTP framework integration (middleware, cleanup context).

starletteoptionalOptional dependency for Starlette framework integration (middleware).

Agent activity

67 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Gr1N/aiodogstatsd ↗

packagehttps://pypi.org/project/aiodogstatsd/ ↗

docshttps://gr1n.github.io/aiodogstatsd ↗