#statsd API reference

A StatsD client (over UDP): emit metric:value|type lines for a StatsD / Datadog / Telegraf agent to aggregate. This is the push counterpart to a pull-based scrape - it is fire-and-forget (UDP, no reply, no error on a missing agent), so a metric costs one datagram and never blocks the program.

A Client holds the sending socket, the agent address, and an optional metric-name prefix (namespace). The verbs map to the StatsD types: count / increment / decrement are counters (c), gauge a gauge (g), timing a timer in milliseconds (ms), and set a unique-member set (s). Needs the default jennifer binary (net).

Optional StatsD / DogStatsD extensions are layered on top: a |@rate sample-rate suffix (the *Rate verbs), |#key:value Datadog tags (the *Tagged verbs, carrying a map of string to string), float-valued counters / gauges (countFloat / gaugeFloat), and a Batch accumulator that packs several metrics into one datagram (batch / add* / flush). Every line - metric name, prefix, value, and tag keys / values - is control-character validated before it reaches the wire, so untrusted request data cannot forge extra metrics.

Import with import "statsd.j" as statsd;. See the statsd guide for prose and examples.

#Functions

#statsd.addCount(b as Batch, name as string, value as int)

Append a counter delta to the batch. Returns a new Batch.

Parameters

• b {Batch} - the accumulator
• name {string} - the metric name
• value {int} - the counter delta

Returns {Batch} - a new accumulator with "name:value|c" appended

#statsd.addDecrement(b as Batch, name as string)

Append a counter -1 to the batch. Returns a new Batch.

Parameters

• b {Batch} - the accumulator
• name {string} - the metric name

Returns {Batch} - a new accumulator with "name:-1|c" appended

#statsd.addGauge(b as Batch, name as string, value as int)

Append an absolute gauge to the batch. A negative value appends a 0-then-decrement pair (see gauge). Returns a new Batch.

Parameters

• b {Batch} - the accumulator
• name {string} - the metric name
• value {int} - the gauge value

Returns {Batch} - a new accumulator with "name:value|g" appended

#statsd.addIncrement(b as Batch, name as string)

Append a counter +1 to the batch. Returns a new Batch.

Parameters

• b {Batch} - the accumulator
• name {string} - the metric name

Returns {Batch} - a new accumulator with "name:1|c" appended

#statsd.addSet(b as Batch, name as string, value as string)

Append a unique set member to the batch. Returns a new Batch.

Parameters

• b {Batch} - the accumulator
• name {string} - the metric name
• value {string} - the set member

Returns {Batch} - a new accumulator with "name:value|s" appended

#statsd.addTiming(b as Batch, name as string, ms as int)

Append a timing (milliseconds) to the batch. Returns a new Batch.

Parameters

• b {Batch} - the accumulator
• name {string} - the metric name
• ms {int} - the duration in milliseconds

Returns {Batch} - a new accumulator with "name:ms|ms" appended

#statsd.batch(c as Client)

Start an empty Batch, capturing the client's metric-name prefix.

Parameters

• c {Client} - the client whose prefix the batched lines inherit

Returns {Batch} - an empty accumulator

#statsd.client(host as string)

Open a client to a StatsD agent on host at the default port (8125), with no metric prefix.

Parameters

• host {string} - the agent host (e.g. "127.0.0.1")

Returns {Client} - a ready-to-use client

#statsd.clientWith(address as string, prefix as string)

Open a client to a StatsD agent at a full host:port address, with a metric-name prefix ("" for none). The prefix is joined to every metric name with a "." (so prefix "web" and metric "hits" send "web.hits").

Parameters

• address {string} - the agent "host:port"
• prefix {string} - a metric-name namespace ("" for none)

Returns {Client} - a ready-to-use client

#statsd.close(c as Client)

Close the client's sending socket.

Parameters

• c {Client} - the client

#statsd.count(c as Client, name as string, value as int)

Adjust a counter by value (may be negative). Sends "name:value|c".

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {int} - the counter delta

#statsd.countFloat(c as Client, name as string, value as float)

Adjust a counter by a fractional value. Sends "name:value|c" with the float formatted compactly (e.g. "3.5", no trailing zeros beyond the canonical form).

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {float} - the counter delta

#statsd.countRate(c as Client, name as string, value as int, rate as float)

Adjust a counter by value at a sample rate. Sends "name:value|c|@rate" (the "|@rate" suffix is omitted when rate >= 1). The agent scales the received count back up by 1/rate, so a rate of 0.1 emitted from a tenth of the events reconstructs the full total.

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {int} - the counter delta
• rate {float} - the sample rate in (0, 1]; >= 1 sends no suffix

#statsd.countTagged(c as Client, name as string, value as int, tags as map of string to string)

Adjust a counter by value, carrying DogStatsD tags. Sends "name:value|c|#k:v,...". Tag keys / values are control-character validated.

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {int} - the counter delta
• tags {map of string to string} - tags rendered as "|#k:v,..." (insertion order)

#statsd.decrement(c as Client, name as string)

Decrement a counter by 1. Sends "name:-1|c".

Parameters

• c {Client} - the client
• name {string} - the metric name

#statsd.decrementTagged(c as Client, name as string, tags as map of string to string)

Decrement a counter by 1, carrying DogStatsD tags. Sends "name:-1|c|#k:v,...".

Parameters

• c {Client} - the client
• name {string} - the metric name
• tags {map of string to string} - tags rendered as "|#k:v,..." (insertion order)

#statsd.flush(c as Client, b as Batch)

Send every accumulated line in one UDP datagram (lines joined by "\n"). An empty batch sends nothing. Fire-and-forget, like the single-metric verbs.

Parameters

• c {Client} - the client
• b {Batch} - the accumulator to flush

#statsd.gauge(c as Client, name as string, value as int)

Set a gauge to an absolute value. Sends "name:value|g".

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {int} - the gauge value

#statsd.gaugeFloat(c as Client, name as string, value as float)

Set a gauge to a fractional absolute value (e.g. a load average). Sends "name:value|g", the float formatted compactly. A negative value is set as a 0-then-decrement pair (see gauge).

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {float} - the gauge value

#statsd.gaugeTagged(c as Client, name as string, value as int, tags as map of string to string)

Set a gauge to an absolute value, carrying DogStatsD tags. Sends "name:value|g|#k:v,...". A negative value is set as a 0-then-decrement pair (see gauge), each line carrying the tags.

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {int} - the gauge value
• tags {map of string to string} - tags rendered as "|#k:v,..." (insertion order)

#statsd.increment(c as Client, name as string)

Increment a counter by 1. Sends "name:1|c".

Parameters

• c {Client} - the client
• name {string} - the metric name

#statsd.incrementTagged(c as Client, name as string, tags as map of string to string)

Increment a counter by 1, carrying DogStatsD tags. Sends "name:1|c|#k:v,...".

Parameters

• c {Client} - the client
• name {string} - the metric name
• tags {map of string to string} - tags rendered as "|#k:v,..." (insertion order)

#statsd.set(c as Client, name as string, value as string)

Record a unique member in a set (the agent counts distinct values). Sends "name:value|s".

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {string} - the set member

#statsd.setTagged(c as Client, name as string, value as string, tags as map of string to string)

Record a unique set member, carrying DogStatsD tags. Sends "name:value|s|#k:v,...".

Parameters

• c {Client} - the client
• name {string} - the metric name
• value {string} - the set member
• tags {map of string to string} - tags rendered as "|#k:v,..." (insertion order)

#statsd.timing(c as Client, name as string, ms as int)

Record a timing in milliseconds. Sends "name:ms|ms".

Parameters

• c {Client} - the client
• name {string} - the metric name
• ms {int} - the duration in milliseconds

#statsd.timingRate(c as Client, name as string, ms as int, rate as float)

Record a timing in milliseconds at a sample rate. Sends "name:ms|ms|@rate" (the "|@rate" suffix is omitted when rate >= 1).

Parameters

• c {Client} - the client
• name {string} - the metric name
• ms {int} - the duration in milliseconds
• rate {float} - the sample rate in (0, 1]; >= 1 sends no suffix

#statsd.timingTagged(c as Client, name as string, ms as int, tags as map of string to string)

Record a timing in milliseconds, carrying DogStatsD tags. Sends "name:ms|ms|#k:v,...".

Parameters

• c {Client} - the client
• name {string} - the metric name
• ms {int} - the duration in milliseconds
• tags {map of string to string} - tags rendered as "|#k:v,..." (insertion order)

#Structs

#statsd.Batch

An accumulator of formatted metric lines to pack into one UDP datagram (the StatsD multi-metric packet, lines separated by "\n"). Value-semantic: each add* verb returns a fresh Batch with the line appended, leaving the input unchanged. flush sends the whole packet through a client. The prefix is captured from the client at batch time and applied to every line.

#statsd.Client

A StatsD client: a bound sending socket plus the agent address and an optional metric-name prefix. Value-copies share the underlying socket (the usual handle carve-out), so copying a Client is safe and cheap.