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

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 options 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!

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

You can use the default StatsClient simply:

from statsd import statsd

statsd.incr('foo')

This instance will use the settings, if provided by Django. If no Django settings can be imported, it won’t be available.

From the Environment

Statsd isn’t only useful in Django or on the web. A default instance will also be available if you configure at least two environment variables. These do not have defaults.

You can set these variables in the environment:

STATSD_HOST
STATSD_PORT
STATSD_PREFIX
STATSD_MAXUDPSIZE

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

from statsd import statsd

statsd.incr('foo')

Note

To make this default instance available, you will need to set at least STATSD_HOST and STATSD_PORT, even if using the default values of localhost and 8125.