aiodogstatsd

0.16.0.post0 verified Tue Apr 14 auth: no python

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.

pip install aiodogstatsd

Common errors

error ModuleNotFoundError: No module named 'aiodogstatsd' ↓

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

fix

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

error TypeError: 'Client' object is not callable ↓

cause 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.

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

cause 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'.

error ConnectionRefusedError: [Errno 111] Connection refused ↓

cause 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.

error RuntimeError: Event loop is closed ↓

cause 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.

Warnings

breaking Python 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.

breaking Support 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.

gotcha The 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.

gotcha While 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.

gotcha As 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.

Install

pip install aiodogstatsd[aiohttp]

pip install aiodogstatsd[starlette]

Imports

Client

wrong

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

correct

from aiodogstatsd import Client

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

Quickstart

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())