Python StatsD Client

Warnings

• breaking The PyPI package `python-statsd` has effectively been replaced by `statsd` (maintained by `jsocol/pystatsd`). While `WoLpH/python-statsd` GitHub repo lists version 2.1.0, its own documentation links point to the `statsd` package (currently 4.0.1). Installing `python-statsd` via pip today will install the `statsd` package.
  Fix: Use `pip install statsd`. Ensure your code uses `from statsd import StatsClient`. If you specifically need features from older `python-statsd` (2.x), verify its API is compatible or find an archived version.
• gotcha This library (`statsd` on PyPI) explicitly does not support tagged metrics (e.g., `metric:value|#tag1:foo,tag2:bar`) used by systems like Datadog, Telegraf, or Prometheus StatsD exporters. Attempting to send tags will result in data loss or incorrect metric names.
  Fix: If you require tagged metrics, consider alternative Python StatsD clients like `dogstatsd-python` or `statsd-exporter`, or adjust your metric naming strategy to encode tags into the metric name itself (e.g., `my_metric.foo.bar`).
• gotcha StatsD primarily uses UDP for metric transmission, which is a 'fire-and-forget' protocol. While highly performant, it does not guarantee delivery. Packets can be silently dropped by the network or the StatsD server under heavy load or network issues.
  Fix: For critical metrics where delivery is paramount, consider using a StatsD server and client that support TCP (if available in your setup) or explore other monitoring solutions designed for guaranteed delivery. For standard use, acknowledge the UDP trade-off and monitor your StatsD server for dropped packets.
• gotcha Several Python libraries exist on PyPI with 'statsd' in their name (e.g., `statsd`, `statsd-client`, `statsd-exporter`, `statsd-tags`). This can lead to confusion and accidentally installing a different client with a non-compatible API or missing features.
  Fix: Always explicitly `pip install statsd` (for this library). Verify your `import statsd` correctly brings in the `StatsClient` class, and consult the documentation for the specific client you intend to use.

Install

• pip install statsd Install the statsd client

Imports

• StatsClient

  from statsd import StatsClient

Quickstart

This quickstart demonstrates how to initialize a StatsD client and send common metric types: counters, timers, and gauges. It uses environment variables for host and port for easy configuration, defaulting to localhost:8125. A prefix is added to all metrics for better organization.

import statsd
import os

# Configure StatsD client, typically pointing to a local StatsD agent
# Default host is 'localhost', default port is 8125
# You can override with environment variables or direct arguments
statsd_host = os.environ.get('STATSD_HOST', 'localhost')
statsd_port = int(os.environ.get('STATSD_PORT', 8125))

c = statsd.StatsClient(host=statsd_host, port=statsd_port, prefix='my_app')

# Increment a counter
c.incr('page_views')
c.incr('successful_requests', 5)

# Record a timing (in milliseconds)
import time
start_time = time.time()
time.sleep(0.05) # Simulate work
duration_ms = (time.time() - start_time) * 1000
c.timing('api_response_time', duration_ms)

# Set a gauge value
c.gauge('current_users', 150)

print(f"Sent metrics to StatsD at {statsd_host}:{statsd_port}")
print("Check your StatsD server/Graphite for 'my_app.page_views', 'my_app.successful_requests', 'my_app.api_response_time', 'my_app.current_users'")