StatsD Tags Client

3.2.1.post1 · active · verified Fri Apr 17

A lightweight Python client for StatsD, extending the basic StatsD protocol with DogStatsD-compatible tags. It simplifies sending metrics with key-value tags to StatsD servers that support the DataDog extension. The current version is 3.2.1.post1, and the project is actively maintained with a stable release cadence.

Common errors

```
ModuleNotFoundError: No module named 'statsd_tags_client'
```
cause Incorrect package name or a common typo used in the import statement.

fix Ensure the import path matches the installed package, which uses underscores: `from statsd_tags import StatsClient`.
```
AttributeError: module 'statsd_tags' has no attribute 'StatsClient'
```
cause The user tried `import statsd_tags` and then attempted to access `statsd_tags.StatsClient` directly, instead of importing the `StatsClient` class explicitly.

fix Import the `StatsClient` class directly from the module: `from statsd_tags import StatsClient`.

Warnings

gotcha This library is designed to send DogStatsD-compatible tags (e.g., `metric:value|#tag:value`). If your StatsD server (e.g., a vanilla `statsd` daemon or a basic implementation) does not explicitly support DogStatsD extensions, the tags will likely be ignored or cause parsing errors on the server side.
Fix: Ensure your StatsD server (e.g., Datadog Agent, Telegraf with DogStatsD input) is specifically configured to handle DogStatsD-formatted metrics. Test with a simple tagged metric to confirm proper tag processing.
gotcha The PyPI package name for installation is `statsd-tags` (with a hyphen), but the Python importable package name uses underscores: `statsd_tags`. Attempting to import `statsd-tags` will result in a `ModuleNotFoundError`.
Fix: Always use `from statsd_tags import StatsClient` (or other symbols) in your Python code, not `from statsd-tags import ...`.
gotcha StatsD typically uses UDP for metric transmission, which is a connectionless protocol. The client will not raise an error if the StatsD server is unreachable, misconfigured, or if packets are dropped by a firewall. Metrics can silently fail to be received.
Fix: Verify network connectivity between your application and the StatsD server (e.g., `netcat -u -z <host> <port>`). Ensure no firewalls are blocking UDP traffic on the StatsD port (default 8125). Monitor the StatsD server logs for incoming metrics to confirm receipt.

Install

pip install statsd-tags Install latest version

Imports

StatsClient
wrong:
```
from statsd_tags.client import StatsClient
```
correct:
```
from statsd_tags import StatsClient
```
The main client class `StatsClient` is directly available under the top-level `statsd_tags` package, not within a sub-module like `client`.

Quickstart

Initialize the `StatsClient` with a host, port, optional prefix, and default tags. Then use methods like `incr`, `gauge`, and `timing` to send various metric types, providing specific tags for each metric call that override or merge with default client tags.

import os
from statsd_tags import StatsClient

# Configure host/port via environment variables for easy deployment
statsd_host = os.environ.get('STATSD_HOST', 'localhost')
statsd_port = int(os.environ.get('STATSD_PORT', '8125'))

# Initialize the StatsD client with a prefix and default tags
client = StatsClient(
    host=statsd_host,
    port=statsd_port,
    prefix='my_application',
    tags={'environment': 'production'}
)

# Increment a counter metric with additional, specific tags
client.incr('request_count', tags={'endpoint': '/api/v1/data', 'status': '200'})

# Set a gauge metric value with custom tags
client.gauge('cpu_utilization', 45.7, tags={'server': 'web_01'})

# Record a timing metric (milliseconds) with event-specific tags
client.timing('db_query_time', 123.45, tags={'query_type': 'read'})

print(f"Sent metrics (incr, gauge, timing) to StatsD at {statsd_host}:{statsd_port}")
print("Note: StatsD uses UDP, so there's no direct confirmation of receipt.")

view raw JSON →