statsd

library4.0.1pypypi✓ verified 24d ago

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.

observability

pip install statsd

github ↗package ↗

INSTALL

IMPORT

SIG · STATSD

statsd

observabilitypythonv4.0.1

Install

1.6s avg

Import

43ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.046s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.040s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StatsClient

✓ from statsd import StatsClient

✗ from statsd import statsd

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.

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.")

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

breakingThe 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.

affects: >=3.0.0

gotchaThe `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.

affects: All versions

gotchaStatsD 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.

affects: All versions

gotchaIncorrect 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.

affects: All versions

gotchaThe `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.

affects: <4.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'statsd'

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

fix

pip install statsd

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

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')

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

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()

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

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')

Upgrade

Version history

4.0.1latest on PyPI · released Nov 6, 2022

Audit

Dependencies

Python 3.7+requiredVersion 4.0.0 dropped Python 2 support and requires Python 3.7 or newer.

Agent activity

18 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/jsocol/pystatsd ↗

packagehttps://pypi.org/project/statsd/ ↗