{"id":4782,"library":"statshog","title":"statshog","description":"statshog is a simple Python client for emitting metrics to StatsD servers, including both Etsy's original StatsD and InfluxDB's Telegraf StatsD server. It provides functionalities for incrementing counters, recording gauges, and tracking timings. The library is currently at version 1.0.6, with a stable but infrequent release cadence, reflecting its mature and focused functionality.","status":"active","version":"1.0.6","language":"en","source_language":"en","source_url":"https://github.com/macobo/statshog","tags":["statsd","metrics","monitoring","client","telegraf"],"install":[{"cmd":"pip install statshog","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"symbol":"StatsClient","correct":"from statshog import StatsClient"},{"note":"This import is for Django-specific integration and assumes configuration via Django settings. For standalone use, initialize StatsClient directly.","wrong":"import statsd # if not configured via Django settings","symbol":"statsd (Django default)","correct":"from statshog.defaults.django import statsd"}],"quickstart":{"code":"import statshog\nimport time\n\n# Initialize a StatsD client (defaults to localhost:8125)\n# For Telegraf's StatsD with tags, use telegraf=True\nstatsd = statshog.StatsClient(host='127.0.0.1', port=8125, telegraf=True)\n\n# Increment a counter\nstatsd.incr('my_app.requests_total')\nstatsd.incr('my_app.errors', tags={'type': 'database_error'})\n\n# Record a gauge value\nstatsd.gauge('my_app.cpu_usage', 55)\nstatsd.gauge('my_app.memory_percent', 72.5, tags={'host': 'server_a'})\n\n# Record a timing\nstart_time = time.time()\ntime.sleep(0.05) # Simulate some work\nend_time = time.time()\nduration_ms = (end_time - start_time) * 1000\nstatsd.timing('my_app.api_response_time', duration_ms, tags={'endpoint': '/api/data'})\n\nprint('Metrics sent to StatsD.')\n# In a real application, ensure your StatsD server (e.g., Telegraf) is running on 127.0.0.1:8125\n# and listening for UDP packets.","lang":"python","description":"This quickstart demonstrates how to initialize the `StatsClient` and send common metric types: increments, gauges, and timings. It also shows how to use tags when `telegraf=True` is enabled."},"warnings":[{"fix":"Be aware of UDP's unreliable nature; implement checks at the monitoring backend level if metric integrity is paramount. For high-volume, non-critical metrics, UDP is generally acceptable.","message":"StatsD clients, including statshog, typically use UDP for sending metrics. UDP is an unreliable protocol, meaning there is no guarantee that packets will reach the StatsD server. For critical metrics, consider the implications of potential packet loss.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly pass `host` and `port` to `statshog.StatsClient(...)` or confirm that `localhost:8125` is indeed where your StatsD server is listening.","message":"When initializing `StatsClient`, ensure `host` and `port` parameters are correctly configured for your StatsD server. The defaults (`localhost:8125`) might not match your deployment.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only set `telegraf=True` if your StatsD backend explicitly supports the Telegraf (or similar) tagged StatsD format. Otherwise, tags will not be transmitted correctly.","message":"Using the `telegraf=True` parameter changes the wire format for sending tags. If your StatsD server is not Telegraf-compatible (or another server that understands Telegraf's tag format), tags will likely be ignored or cause parsing errors.","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"}