StatsD Client

4.0.1 verified Tue May 12 auth: no python install: verified

The `statsd` library is a simple Python client for the StatsD daemon, used for sending various types of metrics (counters, timers, gauges, sets) to monitoring systems like Graphite, Datadog, and Telegraf. It is actively maintained, with the current version being 4.0.1.

pip install statsd

Common errors

error ModuleNotFoundError: No module named 'statsd' ↓

cause The 'statsd' library has not been installed in the Python environment where the code is being executed.

fix

pip install statsd

error AttributeError: type object 'StatsClient' has no attribute 'incr' ↓

cause Methods like 'incr', 'timer', or 'gauge' must be called on an *instance* of the 'StatsClient' class, not on the class itself.

fix

import statsd c = statsd.StatsClient() c.incr('my_metric') # Incorrect: statsd.StatsClient.incr('my_metric')

error ImportError: cannot import name 'Client' from 'statsd' ↓

cause The 'statsd' library exposes its client class directly as 'StatsClient' within the top-level 'statsd' module, not as a nested 'Client' class.

fix

from statsd import StatsClient c = StatsClient() # Alternatively: # import statsd # c = statsd.StatsClient()

error TypeError: 'str' object cannot be interpreted as an integer ↓

cause The 'port' argument for 'statsd.StatsClient' expects an integer, but a string or other non-integer type was provided.

fix

import statsd c = statsd.StatsClient(host='localhost', port=8125) # Incorrect: c = statsd.StatsClient(host='localhost', port='8125')

Warnings

breaking Version 4.0.0 dropped support for Python 2. All users must be on Python 3.7 or newer to use `statsd` v4.x. ↓

fix Upgrade your Python environment to 3.7 or higher.

breaking The global `statsd` object (e.g., `from statsd import statsd`) was removed in version 3.0. This old pattern implicitly picked up configuration. ↓

fix Explicitly instantiate `StatsClient` (e.g., `c = StatsClient('localhost', 8125)`) or use configuration-specific imports like `from statsd.defaults.env import statsd` if relying on environment variables.

gotcha The `statsd` client library does not natively support tagged metrics (e.g., `metric_name#tag:value`) used by some backends like Datadog or Telegraf in the same way as traditional StatsD. Sending tagged metrics without careful naming will result in data loss or misinterpretation. ↓

fix If your monitoring system requires tags, you must adapt your metric naming strategy (e.g., `metric_name.tag_key.tag_value`) or use a client library specifically designed for that system, as this library explicitly avoids 'magic' tagging to prevent silent failures.

gotcha StatsD typically uses UDP port 8125 by default. Firewalls or security settings often block this port, preventing metrics from reaching the StatsD server. ↓

fix Ensure that UDP port 8125 (or your configured StatsD port) is open in your firewall rules on both the client and server machines. Verify connectivity between the client and the StatsD server.

gotcha Incorrect hostname or port in the `StatsClient` configuration is a common cause of metrics not being received. ↓

fix Double-check the `host` and `port` parameters when instantiating `StatsClient` against your StatsD server's configuration.

gotcha The `timing` decorator on `async` functions was broken in versions prior to 4.0.0, incorrectly measuring execution time immediately instead of awaiting the function. ↓

fix Upgrade to `statsd` version 4.0.0 or later to ensure correct timing of asynchronous functions.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.03s 17.9M

3.10 alpine (musl) - - 0.03s 17.9M

3.10 slim (glibc) wheel 1.4s 0.02s 18M

3.10 slim (glibc) - - 0.02s 18M

3.11 alpine (musl) wheel - 0.05s 19.8M

3.11 alpine (musl) - - 0.06s 19.8M

3.11 slim (glibc) wheel 1.6s 0.04s 20M

3.11 slim (glibc) - - 0.04s 20M

3.12 alpine (musl) wheel - 0.05s 11.7M

3.12 alpine (musl) - - 0.05s 11.7M

3.12 slim (glibc) wheel 1.4s 0.05s 12M

3.12 slim (glibc) - - 0.05s 12M

3.13 alpine (musl) wheel - 0.05s 11.4M

3.13 alpine (musl) - - 0.05s 11.3M

3.13 slim (glibc) wheel 1.4s 0.05s 12M

3.13 slim (glibc) - - 0.05s 12M

3.9 alpine (musl) wheel - 0.03s 17.4M

3.9 alpine (musl) - - 0.03s 17.4M

3.9 slim (glibc) wheel 1.7s 0.02s 18M

3.9 slim (glibc) - - 0.02s 18M

Imports

StatsClient
wrong
```
from statsd import statsd
```
correct
```
from statsd import StatsClient
```
Prior to v3.0, a global 'statsd' object was commonly imported. As of v3.0, it's recommended to explicitly instantiate `StatsClient` or import from `statsd.defaults.*` for specific configurations.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to instantiate `StatsClient` and send common metric types: counters, timings, and gauges. It also shows how to use the timing decorator. Ensure a StatsD server is running and accessible at the specified host and port.

import statsd
import time
import os

# Configure connection to StatsD server
# Default StatsD port is 8125
# Replace 'localhost' with your StatsD server's hostname or IP if different
statsd_host = os.environ.get('STATSD_HOST', 'localhost')
statsd_port = int(os.environ.get('STATSD_PORT', 8125))

# Instantiate the StatsClient
c = statsd.StatsClient(statsd_host, statsd_port, prefix='my_app')

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

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

# Set a gauge value
c.gauge('active_users', 15)
print(f"Set 'my_app.active_users' gauge to 15.")

# Using a timing decorator
@c.timer('decorated_function_time')
def my_function():
    time.sleep(0.02) # Simulate work

my_function()
print(f"'my_app.decorated_function_time' recorded using decorator.")