{"id":5836,"library":"aiodogstatsd","title":"aiodogstatsd","description":"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.","status":"active","version":"0.16.0.post0","language":"en","source_language":"en","source_url":"https://github.com/Gr1N/aiodogstatsd","tags":["asyncio","dogstatsd","statsd","metrics","monitoring","aiohttp","starlette"],"install":[{"cmd":"pip install aiodogstatsd","lang":"bash","label":"Base installation"},{"cmd":"pip install aiodogstatsd[aiohttp]","lang":"bash","label":"For AIOHTTP integration"},{"cmd":"pip install aiodogstatsd[starlette]","lang":"bash","label":"For Starlette integration"}],"dependencies":[{"reason":"Requires Python 3.7 or newer, but less than 4.0.","package":"python","optional":false},{"reason":"Optional dependency for AIOHTTP framework integration (middleware, cleanup context).","package":"aiohttp","optional":true},{"reason":"Optional dependency for Starlette framework integration (middleware).","package":"starlette","optional":true}],"imports":[{"note":"The primary client class is named `Client` and is imported directly from the top-level package.","wrong":"import aiodogstatsd; client = aiodogstatsd.Client() (without then importing Client directly)","symbol":"Client","correct":"from aiodogstatsd import Client"}],"quickstart":{"code":"import asyncio\nimport os\nfrom aiodogstatsd import Client\n\nasync def main():\n    # The client uses port 9125 by default, which is common for statsd_exporter.\n    # For DataDog Agent or standard StatsD (port 8125), configure explicitly.\n    async with Client(host=os.environ.get('STATSD_HOST', 'localhost'), port=int(os.environ.get('STATSD_PORT', '9125'))) as client:\n        client.increment(\"users.online\")\n        client.gauge(\"server.cpu.usage\", value=42.5, tags={\"region\": \"us-east-1\"})\n        with client.timeit(\"db.query.time\"): # Context manager for timing\n            await asyncio.sleep(0.05)\n        print(\"Metrics sent!\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer. Update your `requires_python` specification if applicable.","message":"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.","severity":"breaking","affected_versions":">=0.16.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"Initialize the client with `Client(port=8125, ...)` if targeting a standard StatsD or Datadog Agent setup.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adopt the `async with` context manager pattern for client initialization and usage to prevent resource leaks and ensure robustness.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}