Configuring Statsd

It’s easy to configure and use Statsd at runtime, but there are also two shortcuts available.

Runtime

If you are running the statsd server locally and on the default port, it’s extremely easy:

from statsd import StatsClient

statsd = StatsClient()
statsd.incr('foo')

There are several arguments to configure your StatsClient instance. They, and their defaults, are:

from statsd import StatsClient

statsd = StatsClient(host='localhost',
                     port=8125,
                     prefix=None,
                     maxudpsize=512,
                     ipv6=False)

host is the host running the statsd server. It will support any kind of name or IP address you might use.

port is the statsd server port. The default for both server and client is 8125.

prefix helps distinguish multiple applications or environments using the same statsd server. It will be prepended to all stats, automatically. For example:

from statsd import StatsClient

foo_stats = StatsClient(prefix='foo')
bar_stats = StatsClient(prefix='bar')

foo_stats.incr('baz')
bar_stats.incr('baz')

will produce two different stats, foo.baz and bar.baz. Without the prefix argument, or with the same prefix, two StatsClient instances will update the same stats.

New in version 2.0.3.

maxudpsize specifies the maximum packet size statsd will use. This is an advanced option and should not be changed unless you know what you are doing. Larger values then the default of 512 are generally deemed unsafe for use on the internet. On a controlled local network or when the statsd server is running on 127.0.0.1 larger values can decrease the number of UDP packets when pipelining many metrics. Use with care!

New in version 3.2.

ipv6 tells the client explicitly to look up the host using IPv6 (True) or IPv4 (False).

Note

Python will will inherently bind to an ephemeral port on all interfaces (0.0.0.0) for each configured client. This is due to the underlying Sockets API in the operating system/kernel. It is safe to block incoming traffic on your firewall if you wish.

TCP Clients

TCP-based clients have an additional timeout argument, which defaults to None, and is passed to settimeout.

UnixSocket Clients

UnixSocket-based clients have a single required socket_path argument instead of host and port.

In Django

If you are using Statsd in a Django application, you can configure a default StatsClient in the Django settings. All of these settings are optional.

Here are the settings and their defaults:

STATSD_HOST = 'localhost'
STATSD_PORT = 8125
STATSD_PREFIX = None
STATSD_MAXUDPSIZE = 512
STATSD_IPV6 = False

You can use the default StatsClient simply:

from statsd.defaults.django import statsd

statsd.incr('foo')

From the Environment

StatsD isn’t only useful in Django or on the web. A default instance can also be configured via environment variables.

Here are the environment variables and their defaults:

STATSD_HOST=localhost
STATSD_PORT=8125
STATSD_PREFIX=None
STATSD_MAXUDPSIZE=512
STATSD_IPV6=0

and then in your Python application, you can simply do:

from statsd.defaults.env import statsd

statsd.incr('foo')

Note

As of version 3.0, this default instance is always available, configured with the default values, unless overridden by the environment.