The StatsClient provides accessors for all the types of data the statsd server supports.

StatsClient(host='localhost', port=8125, prefix=None)

Create a new StatsClient instance with the appropriate connection and prefix information.

• host: the hostname or IPv4 address of the statsd server.
• port: the port of the statsd server.
• prefix: a prefix to distinguish and group stats from an application or environment.

StatsClient().incr(stat, count=1, rate=1)

Increment a :ref:`counter <counter-type>`.

• stat: the name of the counter to increment.
• count: the amount to increment by. Typically an integer. May be negative, but see also :ref:`decr`.
• rate: a sample rate, a float between 0 and 1. Will only send data this percentage of the time. The statsd server will take the sample rate into account for counters.

StatsClient().decr(stat, count=1, rate=1)

Decrement a :ref:`counter <counter-type>`.

• stat: the name of the counter to decrement.
• count: the amount to decrement by. Typically an integer. May be negative but that will have the impact of incrementing the counter. See also :ref:`incr`.
• rate: a sample rate, a float between 0 and 1. Will only send data this percentage of the time. The statsd server will take the sample rate into account for counters.

StatsClient().timing(stat, delta, rate=1)

Record :ref:`timer <timer-type>` information.

• stat: the name of the timer to use.
• delta: the number of milliseconds whatever action took. Should always be milliseconds.
• rate: a sample rate, a float between 0 and 1. Will only send data this percentage of the time. The statsd server does not take the sample rate into account for timers.

with StatsClient().timer(stat, rate=1):
    pass

@StatsClient().timer(stat, rate=1)
def foo():
    pass

Automatically record timing information for a managed block or function call. See also the :ref:`chapter on timing <timing-chapter>`.

• stat: the name of the timer to use.
• rate: a sample rate, a float between 0 and 1. Will only send data this percentage of the time. The statsd server does not take the sample rate into account for timers.

StatsClient().gauge(stat, value, rate=1, delta=False)

Set a :ref:`gauge <gauge-type>` value.

• stat: the name of the gauge to set.
• value: the current value of the gauge.
• rate: a sample rate, a float between 0 and 1. Will only send data this percentage of the time. The statsd server does not take the sample rate into account for gauges. Use with care.
• delta: whether or not to consider this a delta value or an absolute value. See the :ref:`gauge <gauge-type>` type for more detail.

StatsClient().set(stat, value, rate=1)

Increment a :ref:`set <set-type>` value.

• stat: the name of the set to update.
• value: the unique value to count.
• rate: a sample rate, a float between 0 and 1. Will only send data this percentage of the time. The statsd server does not take the sample rate into account for sets. Use with care.

StatsClient().pipeline()

Returns a :ref:`Pipeline <pipeline-chapter>` object for collecting several stats. Can also be used as a context manager:

with StatsClient().pipeline() as pipe:
    pipe.incr('foo')

pipe = StatsClient().pipeline()
pipe.incr('foo')
pipe.send()

Causes a :ref:`Pipeline <pipeline-chapter>` object to send all batched stats.