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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
.. _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:
.. code-block:: python
from statsd import StatsClient
statsd = StatsClient()
statsd.incr('foo')
There are several arguments to configure your :py:class:`StatsClient` instance.
They, and their defaults, are:
.. code-block:: python
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:
.. code-block:: python
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.
.. versionadded:: 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!
.. versionadded:: 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
-----------
:ref:`TCP-based clients <tcp-chapter>` have an additional ``timeout`` argument,
which defaults to ``None``, and is passed to `settimeout
<https://docs.python.org/2/library/socket.html#socket.socket.settimeout>`_.
UnixSocket Clients
------------------
:ref:`UnixSocket-based clients <unix-socket-chapter>` 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
:py:class:`StatsClient` in the Django settings. All of these settings are
optional.
Here are the settings and their defaults:
.. code-block:: python
STATSD_HOST = 'localhost'
STATSD_PORT = 8125
STATSD_PREFIX = None
STATSD_MAXUDPSIZE = 512
STATSD_IPV6 = False
You can use the default :py:class:`StatsClient` simply:
.. code-block:: python
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:
.. code-block:: bash
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:
.. code-block:: python
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.
.. _statsd: https://github.com/etsy/statsd
.. _Django: https://www.djangoproject.com/
|
