Registry / observability / statsd-tags

statsd-tags

JSON →
library3.2.1.post1pypypi✓ verified 83d ago

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.

pip install statsd-tags
INSTALL
IMPORT
SIG · STATSD-TAGS
S
statsd-tags
observabilitypythonv3.2.1.post1
Install
1.5s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.1.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

StatsClient
from statsd import StatsClient
from statsd_tags import StatsClient
TCPStatsClient
from statsd import TCPStatsClient
from statsd_tags import TCPStatsClient
VERSION
from statsd import VERSION
from statsd_tags import VERSION

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.")
Debug
Known issues
gotchaThis 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.
affects: All versions
gotchaThe 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 ...`.
affects: All versions
gotchaStatsD 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.
affects: All versions
Upgrade
Version history
3.2.1.post1latest on PyPI · released Dec 24, 2016
Audit
Dependencies

No dependency data recorded yet.

Agent activity
26 hits · last 30 days
node
20
OpenAI (training)
1
Resources
statsd-tags — pip install statsd-tags · libregistry