{"id":9338,"library":"statsd-python","title":"StatsD Python Client","description":"The `statsd-python` library (version 0.6.1) provides a simple Python client for sending metrics to a StatsD server via UDP. It supports incrementing counters, setting gauges, and recording timings. The library has a stable API and sees infrequent updates, making it a reliable choice for basic StatsD integration.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/lirsacc/statsd_client_python","tags":["metrics","monitoring","statsd","udp","observability"],"install":[{"cmd":"pip install statsd-python","lang":"bash","label":"Install `statsd-python`"}],"dependencies":[],"imports":[{"note":"While 'from statsd import StatsClient' works, 'import statsd' is idiomatic and avoids potential name clashes, aligning with common examples.","wrong":"from statsd import StatsClient","symbol":"StatsClient","correct":"import statsd\nc = statsd.StatsClient(...)"}],"quickstart":{"code":"import statsd\nimport time\nimport os\n\n# Configure StatsD client\n# Default StatsD host is usually 'localhost', port 8125\n# Replace with your StatsD server's host and port if different\nstatsd_host = os.environ.get('STATSD_HOST', 'localhost')\nstatsd_port = int(os.environ.get('STATSD_PORT', '8125'))\n\nc = statsd.StatsClient(statsd_host, statsd_port)\n\nprint(f\"Sending metrics to StatsD server at {statsd_host}:{statsd_port}...\")\n\n# Increment a counter\nc.incr('my_app.requests_total')\nprint(\"Incremented 'my_app.requests_total'\")\n\n# Set a gauge value\nc.gauge('my_app.active_users', 15)\nc.gauge('my_app.memory_usage_mb', 256.7)\nprint(\"Set gauges for 'my_app.active_users' and 'my_app.memory_usage_mb'\")\n\n# Record a timing (in milliseconds)\nstart_time = time.time()\ntime.sleep(0.05) # Simulate some work\nend_time = time.time()\nduration_ms = (end_time - start_time) * 1000\nc.timing('my_app.process_duration_ms', duration_ms)\nprint(f\"Recorded timing for 'my_app.process_duration_ms': {duration_ms:.2f}ms\")\n\n# Send with a sample rate (e.g., send only 50% of the time)\nc.incr('my_app.sampled_events', rate=0.5)\nprint(\"Incremented 'my_app.sampled_events' with a 50% sample rate\")\n\nprint(\"Metrics sent. Check your StatsD server for reception.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Metrics are not visible in monitoring tools or appear inconsistent.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Name collision with other 'statsd' or 'pystatsd' libraries.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"`pip install statsd-python`","cause":"The `statsd-python` package was not installed in the current Python environment or is not in the Python path.","error":"ModuleNotFoundError: No module named 'statsd'"},{"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`.","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.","error":"AttributeError: module 'statsd' has no attribute 'StatsClient'"}]}