asyncstatsd

Asyncio compatible StatsD client for sending metrics to statsd server. Unlike jsocol/pystatsd it supports DataDog tagged metrics out of the box. I wanted to keep it simple - no more wondering if dependency is safe to include because of threads, queues, mutexes. It should be easy to extend just as adding tags support was easy to implement.

Installation

$ pip install asyncstatsd

Usage

Pure statsd

import asyncio
from asyncstatsd.client import StatsdClient


def foo(statsd):
    statsd.incr('some.counter')
    statsd.timing('some.timer', 320)


async def bar(statsd):
   statsd.incr('some.counter')
   statsd.timing('some.timer', 320)
   with statsd.timer('some.timer'):
       await asyncio.sleep(1)

async def main():
    client = StatsdClient('localhost', 8125)
    await client.connect()
    foo(client)
    await bar(client)

Statsd extended with Datadog tags

import asyncio
from asyncstatsd.client import DatadogClient


def foo(statsd):
    statsd.incr('some.counter', tags=dict(tag1='value1', tag2='value2'))
    statsd.timing('some.timer', 320, tags=dict(tag1='value1', tag2='value2'))


async def bar(statsd):
   statsd.incr('some.counter', tags=dict(tag1='value1', tag2='value2'))
   statsd.timing('some.timer', 320, tags=dict(tag1='value1', tag2='value2')
   with statsd.timer('some.timer', tags=dict(tag1='value1', tag2='value2'):
       await asyncio.sleep(1)


async def main():
    client = DatadogClient('localhost', 8125)
    await client.connect()
    foo(client)
    await bar(client)

Statsd null client

import asyncio
import os
from asyncstatsd.client import DatadogClient, NullStatsdClient


def get_statsd_client():
    if os.environ.get('STATSD_ENABLED', 'false').lower() == 'true':
        return DatadogClient('localhost', 8125)
    else:
        return NullStatsdClient()


def foo():
    statsd = get_statsd_client()
    statsd.incr('some.counter', tags=dict(tag1='value1', tag2='value2'))
    statsd.timing('some.timer', 320, tags=dict(tag1='value1', tag2='value2'))


async def bar(statsd):
    statsd = get_statsd_client()
    statsd.incr('some.counter', tags=dict(tag1='value1', tag2='value2'))
    statsd.timing('some.timer', 320, tags=dict(tag1='value1', tag2='value2')
    with statsd.timer('some.timer', tags=dict(tag1='value1', tag2='value2'):
        await asyncio.sleep(1)


async def main():
    client = DatadogClient('localhost', 8125)
    await client.connect()
    foo()
    await bar()

Additional notes

By default, UDPClient uses max UDP packet size of 512 bytes in order to make sure that it's not going to be fragmented. You can adjust this value by following advice from statsd spec

Fast Ethernet (1432) - This is most likely for Intranets. Gigabit Ethernet (8932) - Jumbo frames can make use of this feature much more efficient. Commodity Internet (512) - If you are routing over the internet a value in this range will be reasonable. You might be able to go higher, but you are at the mercy of all the hops in your route. (These payload numbers take into account the maximum IP + UDP header sizes)

References

1. statsd/docs/metric_types.md
2. jsocol/pystatsd: A Python client for statsd does not support DataDog tags, see https://statsd.readthedocs.io/en/stable/tags.html?highlight=datadog#unsupported-tagging-metrics and recommended alternative got deleted from github while it's still available on pypi.