Install & Compatibility
Where this runs
tested against v1.0.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.026s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.026s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StatsClient
✓ from statshog import StatsClient
statsd (Django default)
✓ from statshog.defaults.django import statsd
✗ import statsd # if not configured via Django settings
This import is for Django-specific integration and assumes configuration via Django settings. For standalone use, initialize StatsClient directly.
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.
import statshog
import time
# Initialize a StatsD client (defaults to localhost:8125)
# For Telegraf's StatsD with tags, use telegraf=True
statsd = statshog.StatsClient(host='127.0.0.1', port=8125, telegraf=True)
# Increment a counter
statsd.incr('my_app.requests_total')
statsd.incr('my_app.errors', tags={'type': 'database_error'})
# Record a gauge value
statsd.gauge('my_app.cpu_usage', 55)
statsd.gauge('my_app.memory_percent', 72.5, tags={'host': 'server_a'})
# Record a timing
start_time = time.time()
time.sleep(0.05) # Simulate some work
end_time = time.time()
duration_ms = (end_time - start_time) * 1000
statsd.timing('my_app.api_response_time', duration_ms, tags={'endpoint': '/api/data'})
print('Metrics sent to StatsD.')
# In a real application, ensure your StatsD server (e.g., Telegraf) is running on 127.0.0.1:8125
# and listening for UDP packets.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'statshog'
The `statshog` package has not been installed in the current Python environment.
socket.gaierror: [Errno -2] Name or service not known
The hostname provided to `statshog.configure()` is invalid, misspelled, or cannot be resolved by the system's DNS.
fixstatshog.configure(host='your_valid_statsd_host', port=8125)
TypeError: an integer is required (got type str)
The port number provided to `statshog.configure()` was supplied as a string or another non-integer type.
fixstatshog.configure(host='localhost', port=8125)
TypeError: increment() missing 1 required positional argument: 'metric_name'
A required argument, such as `metric_name` for `statshog.increment()`, was not provided when calling the function.
fixstatshog.increment('my.app.event_count') Upgrade
Version history
1.0.6latest on PyPI · released May 7, 2021
Audit
Dependencies
No dependency data recorded yet.