1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
.. _configuring-chapter:
==================
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,
suffix=None)
``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.
``suffix`` can also be used to distinguish between hosts or environments.
The suffix will be appended to all stats, automatically. This is useful
when working with clusters consisting of multiple hosts. For example::
from statsd import StatsClient
from os import uname
myhostname = uname()[1].split(".")[0]
stats = StatsClient(suffix=myhostname)
will append ``.hostname`` to all stats sent to statsd. Without this, all
hosts in a cluster would update the same stats.
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_SUFFIX = None
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
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``.
.. _statsd: https://github.com/etsy/statsd
.. _Django: https://www.djangoproject.com/
|
