aiodogstatsd

https://gr1n.github.io/aiodogstatsd/
Admin
aiodogstatsd is an asyncio-based client for sending metrics to StatsD with support for the DogStatsD...
Tokens:2,101
Snippets:37
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install aiodogstatsd

Source: https://gr1n.github.io/aiodogstatsd

Standard installation command for the library.

```bash
pip install aiodogstatsd
```

--------------------------------

### Install aiodogstatsd for AIOHTTP

Source: https://gr1n.github.io/aiodogstatsd/frameworks/aiohttp

Install the library with the required aiohttp extras.

```bash
pip install aiodogstatsd[aiohttp]
```

--------------------------------

### Install aiodogstatsd with framework extras

Source: https://gr1n.github.io/aiodogstatsd

Installation command including optional dependencies for AIOHTTP, Sanic, and Starlette.

```bash
pip install aiodogstatsd[aiohttp,sanic,starlette]
```

--------------------------------

### Install aiodogstatsd for Sanic

Source: https://gr1n.github.io/aiodogstatsd/frameworks/sanic

Install the library with the required extras for Sanic support.

```bash
pip install aiodogstatsd[sanic]
```

--------------------------------

### Install aiodogstatsd for Starlette

Source: https://gr1n.github.io/aiodogstatsd/frameworks/starlette

Install the library with the necessary extras for Starlette support.

```bash
pip install aiodogstatsd[starlette]
```

--------------------------------

### Send metrics with aiodogstatsd

Source: https://gr1n.github.io/aiodogstatsd

Basic usage example demonstrating how to use the client as a context manager to increment a counter.

```python
import asyncio

import aiodogstatsd


async def main():
    async with aiodogstatsd.Client() as client:
        client.increment("users.online")


asyncio.run(main())
```

--------------------------------

### Use Client as Context Manager

Source: https://gr1n.github.io/aiodogstatsd/usage

Using the client as a context manager automatically handles connection initialization and closure.

```python
async with aiodogstatsd.Client() as client:
    client.increment("users.online")
```

--------------------------------

### Initialize AIOHTTP Application with aiodogstatsd

Source: https://gr1n.github.io/aiodogstatsd/frameworks/aiohttp

Configure the AIOHTTP application by adding the middleware and cleanup context factory.

```python
from aiohttp import web

from aiodogstatsd.contrib import aiohttp as aiodogstatsd


app = web.Application(middlewares=[aiodogstatsd.middleware_factory()])
app.cleanup_ctx.append(aiodogstatsd.cleanup_context_factory())
```

--------------------------------

### Initialize aiodogstatsd Client

Source: https://gr1n.github.io/aiodogstatsd/usage

Manual initialization requires explicit calls to connect and close the client.

```python
client = aiodogstatsd.Client(
    host="127.0.0.1",
    port=8125,
    namespace="hello",
    constant_tags={
        "service": "auth",
    },
    read_timeout=0.5,
    close_timeout=0.5,
    sample_rate=1,
)

await client.connect()
client.increment("users.online")
await client.close()
```

--------------------------------

### Initialize Starlette with StatsD Middleware

Source: https://gr1n.github.io/aiodogstatsd/frameworks/starlette

Configure the Starlette application with the StatsD middleware and lifecycle hooks for client connection and closure.

```python
from starlette.applications import Starlette
from starlette.middleware import Middleware

import aiodogstatsd
from aiodogstatsd.contrib.starlette import StatsDMiddleware


client = aiodogstatsd.Client()

app = Starlette(
    middleware=[Middleware(StatsDMiddleware, client=client)],
    on_startup=[client.connect],
    on_shutdown=[client.close],
)
```

--------------------------------

### aiodogstatsd.Client Initialization

Source: https://gr1n.github.io/aiodogstatsd/usage

Initializes the StatsD client with connection settings and optional configuration.

```APIDOC
## aiodogstatsd.Client(host, port, namespace, constant_tags, read_timeout, close_timeout, sample_rate)

### Description
Initializes a new StatsD client instance. Connection must be established using `await client.connect()` and closed with `await client.close()`.

### Parameters
- **host** (string) - Optional - StatsD server host (default: localhost)
- **port** (int) - Optional - StatsD server port (default: 9125)
- **namespace** (string) - Optional - Prefix for all metrics
- **constant_tags** (dict) - Optional - Tags applied to all metrics
- **read_timeout** (float) - Optional - Read timeout (default: 0.5)
- **close_timeout** (float) - Optional - Close timeout
- **sample_rate** (float) - Optional - Sample rate (default: 1)
```

--------------------------------

### Initialize aiodogstatsd in Sanic

Source: https://gr1n.github.io/aiodogstatsd/frameworks/sanic

Register listeners and middlewares to the Sanic application instance to enable automatic metric collection.

```python
from sanic import Sanic

from aiodogstatsd.contrib import sanic as aiodogstatsd


app = Sanic(name="aiodogstatsd")

listener_setup, listener_close = aiodogstatsd.listeners_factory()
app.register_listener(listener_setup, "before_server_start")
app.register_listener(listener_close, "after_server_stop")

middleware_req, middleware_resp = aiodogstatsd.middlewares_factory()
app.register_middleware(middleware_req, attach_to="request")
app.register_middleware(middleware_resp, attach_to="response")
```

--------------------------------

### Time Execution with timeit

Source: https://gr1n.github.io/aiodogstatsd/usage

Context manager for timing blocks of code.

```python
with client.timeit("query.time"):
    ...
```

--------------------------------

### Timing Utilities

Source: https://gr1n.github.io/aiodogstatsd/usage

Utilities for measuring execution time of code blocks or tasks.

```APIDOC
## Timing Utilities

### timeit(metric, tags=None, sample_rate=1, threshold_ms=None)
Context manager to time a block of code.

### timeit_task(awaitable, metric, tags=None, sample_rate=1)
Wraps an awaitable in a task and records its execution duration.
```

--------------------------------

### Time Async Tasks with timeit_task

Source: https://gr1n.github.io/aiodogstatsd/usage

Wraps an awaitable in a task and records its duration.

```python
async def do_something():
    await asyncio.sleep(1.0)
await client.timeit_task(do_something(), "task.time")
```

--------------------------------

### Record Timing Metric

Source: https://gr1n.github.io/aiodogstatsd/usage

Records a specific timing value.

```python
client.timing("query.time", value=0.5)
```

--------------------------------

### Send Histogram Metric

Source: https://gr1n.github.io/aiodogstatsd/usage

Samples a histogram value.

```python
client.histogram("request.time", value=0.2)
```

--------------------------------

### Metric Methods

Source: https://gr1n.github.io/aiodogstatsd/usage

Methods for sending various metric types to the StatsD server.

```APIDOC
## Metric Submission Methods

### gauge(metric, value, tags=None, sample_rate=1)
Records a gauge value.

### increment(metric, value=1, tags=None, sample_rate=1)
Increments a counter.

### decrement(metric, value=1, tags=None, sample_rate=1)
Decrements a counter.

### histogram(metric, value, tags=None, sample_rate=1)
Records a histogram value.

### distribution(metric, value, tags=None, sample_rate=1)
Sends a global distribution value.

### timing(metric, value, tags=None, sample_rate=1)
Records a timing value.
```

--------------------------------

### Send Gauge Metric

Source: https://gr1n.github.io/aiodogstatsd/usage

Records a gauge value with optional tags and sample rate.

```python
client.gauge("users.online", value=42)
```

--------------------------------

### Send Distribution Metric

Source: https://gr1n.github.io/aiodogstatsd/usage

Sends a global distribution value.

```python
client.distribution("uploaded.file.size", value=8819)
```

--------------------------------

### Increment Counter

Source: https://gr1n.github.io/aiodogstatsd/usage

Increments a counter metric.

```python
client.increment("users.online")
```

--------------------------------

### Decrement Counter

Source: https://gr1n.github.io/aiodogstatsd/usage

Decrements a counter metric.

```python
client.decrement("users.online")
```
Tokens:
Raw