aiodogstatsd

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 Base installation
• pip install aiodogstatsd[aiohttp] For AIOHTTP integration
• pip install aiodogstatsd[starlette] For Starlette integration

Imports

• Client

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