StatsD Python Client

Common errors

• ModuleNotFoundError: No module named 'statsd'

  cause The `statsd-python` package was not installed in the current Python environment or is not in the Python path.
  fix `pip install statsd-python`

• AttributeError: module 'statsd' has no attribute 'StatsClient'

  cause This usually indicates that a different `statsd` library (not `statsd-python` by lirsacc) is installed, or a misimport. Some older `statsd` packages might expose the client directly as `statsd.statsd` or have no `StatsClient` attribute.
  fix Ensure `pip show statsd-python` confirms you have the correct library installed. If other `statsd` packages are present (`pip freeze | grep statsd`), try uninstalling them (`pip uninstall <conflicting-package-name>`) and then reinstall `statsd-python`. Also, ensure you are importing `import statsd` and then using `statsd.StatsClient`.

Warnings

• gotcha Metrics are not visible in monitoring tools or appear inconsistent.
  Fix: StatsD uses UDP, a connectionless protocol. Packets are 'fire and forget' and provide no delivery guarantees. Network issues, firewalls, or an unavailable StatsD server will cause silent failures from the client's perspective. Ensure the StatsD server is running, reachable, and listening on the configured host/port. Check firewalls. Use `tcpdump` or Wireshark to verify UDP packets are leaving the client machine and arriving at the server.
• gotcha Name collision with other 'statsd' or 'pystatsd' libraries.
  Fix: There are multiple Python libraries with similar names (`statsd`, `pystatsd`). This registry entry refers to `statsd-python` by lirsacc (`pip install statsd-python`). An older, now archived, library (often referred to as `pystatsd` or `statsd` by jsocol) had a different API. Verify you have installed `statsd-python` (`pip show statsd-python`) and are using its specific API (e.g., `import statsd` then `statsd.StatsClient`). If you encounter unexpected API errors, check for other `statsd` installations (`pip freeze | grep statsd`) and uninstall conflicting ones.

Install

• pip install statsd-python Install `statsd-python`

Imports

• StatsClient
  wrong:

  from statsd import StatsClient

  correct:

  import statsd
  c = statsd.StatsClient(...)

  While 'from statsd import StatsClient' works, 'import statsd' is idiomatic and avoids potential name clashes, aligning with common examples.

Quickstart

This quickstart demonstrates how to initialize the `StatsClient` and send common metric types: counters (`incr`), gauges (`gauge`), and timings (`timing`). It also shows how to use a sample rate for counters.

import statsd
import time
import os

# Configure StatsD client
# Default StatsD host is usually 'localhost', port 8125
# Replace with your StatsD server's host and port if different
statsd_host = os.environ.get('STATSD_HOST', 'localhost')
statsd_port = int(os.environ.get('STATSD_PORT', '8125'))

c = statsd.StatsClient(statsd_host, statsd_port)

print(f"Sending metrics to StatsD server at {statsd_host}:{statsd_port}...")

# Increment a counter
c.incr('my_app.requests_total')
print("Incremented 'my_app.requests_total'")

# Set a gauge value
c.gauge('my_app.active_users', 15)
c.gauge('my_app.memory_usage_mb', 256.7)
print("Set gauges for 'my_app.active_users' and 'my_app.memory_usage_mb'")

# Record a timing (in milliseconds)
start_time = time.time()
time.sleep(0.05) # Simulate some work
end_time = time.time()
duration_ms = (end_time - start_time) * 1000
c.timing('my_app.process_duration_ms', duration_ms)
print(f"Recorded timing for 'my_app.process_duration_ms': {duration_ms:.2f}ms")

# Send with a sample rate (e.g., send only 50% of the time)
c.incr('my_app.sampled_events', rate=0.5)
print("Incremented 'my_app.sampled_events' with a 50% sample rate")

print("Metrics sent. Check your StatsD server for reception.")