{"id":5708,"library":"python-statsd","title":"Python StatsD Client","description":"python-statsd is a Python client for the StatsD daemon, a front-end/proxy for Graphite's stats collection and graphing server. While the user-provided slug is 'python-statsd' (version 2.1.0), this PyPI project typically redirects to 'statsd' (currently 4.0.1). This entry reflects the features and usage of the actively maintained 'statsd' package on PyPI, which is the direct successor and most commonly used client. It allows applications to send various metrics like counters, timers, and gauges over UDP (or TCP) for aggregation and monitoring. The library generally follows a stable release cadence for minor bug fixes and feature enhancements.","status":"active","version":"4.0.1","language":"en","source_language":"en","source_url":"https://github.com/WoLpH/python-statsd","tags":["metrics","monitoring","statsd","graphite","udp","timing","counters","gauges"],"install":[{"cmd":"pip install statsd","lang":"bash","label":"Install the statsd client"}],"dependencies":[],"imports":[{"symbol":"StatsClient","correct":"from statsd import StatsClient"}],"quickstart":{"code":"import statsd\nimport os\n\n# Configure StatsD client, typically pointing to a local StatsD agent\n# Default host is 'localhost', default port is 8125\n# You can override with environment variables or direct arguments\nstatsd_host = os.environ.get('STATSD_HOST', 'localhost')\nstatsd_port = int(os.environ.get('STATSD_PORT', 8125))\n\nc = statsd.StatsClient(host=statsd_host, port=statsd_port, prefix='my_app')\n\n# Increment a counter\nc.incr('page_views')\nc.incr('successful_requests', 5)\n\n# Record a timing (in milliseconds)\nimport time\nstart_time = time.time()\ntime.sleep(0.05) # Simulate work\nduration_ms = (time.time() - start_time) * 1000\nc.timing('api_response_time', duration_ms)\n\n# Set a gauge value\nc.gauge('current_users', 150)\n\nprint(f\"Sent metrics to StatsD at {statsd_host}:{statsd_port}\")\nprint(\"Check your StatsD server/Graphite for 'my_app.page_views', 'my_app.successful_requests', 'my_app.api_response_time', 'my_app.current_users'\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<4.0.0 (for old `python-statsd`)"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions of `statsd` (PyPI package)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}