statsd.h File Reference

StatsD metrics client - push counters/gauges/timings/sets to a StatsD collector. More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Enumerations
enum class	StatsdType : uint8_t { STATSD_COUNTER = 'c' , STATSD_GAUGE = 'g' , STATSD_TIMING = 'm' , STATSD_SET = 's' }
	StatsD metric type codes (the token after the |). More...

Functions
size_t	statsd_format (char *out, size_t cap, const char *name, const char *value, StatsdType type, float rate, const char *tags)
	Format one StatsD line: name:value|type[|@rate][|#tags]. Pure - no I/O.
void	statsd_begin (const char *host, uint16_t port, const char *global_tags)
	Point the client at a collector and set optional global tags (added to every metric).
void	statsd_count (const char *name, int64_t delta)
	Increment a counter by delta (may be negative).
void	statsd_count_sampled (const char *name, int64_t delta, float rate)
	Increment a counter, annotated with sample rate (0,1] so the server scales up.
void	statsd_gauge (const char *name, int64_t value)
	Set a gauge to an absolute value.
void	statsd_gauge_delta (const char *name, int64_t delta)
	Adjust a gauge by a signed delta (sent as a +/- gauge update).
void	statsd_timing (const char *name, uint32_t ms)
	Record a timing/duration of ms milliseconds.
void	statsd_set (const char *name, const char *member)
	Add a unique member to a set (counts distinct values server-side).

Detailed Description

StatsD metrics client - push counters/gauges/timings/sets to a StatsD collector.

StatsD is the de-facto push metrics protocol: one line per metric, name:value|type, over UDP (fire-and-forget). It is spoken by Graphite/StatsD, Telegraf, Datadog, InfluxDB, and most observability stacks. This is the push counterpart to the pull-based Prometheus /metrics endpoint: instead of a scraper polling the device, the device shoves metrics out as things happen - handy behind NAT/firewalls where nothing can reach in to scrape.

Types: counter (c), gauge (g, absolute or a signed +/- delta), timing (ms), and set (s). Optional sample rate (|@0.1) and DogStatsD tags (|#env:prod,host:a).

The line builder (statsd_format) is pure and host-tested; the emit helpers format the value and send via the transport UDP service (det_udp_sendto), so they are host-testable through its capture seam too. Zero heap; gated by DETWS_ENABLE_STATSD.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file statsd.h.

Enumeration Type Documentation

StatsdType

enum class StatsdType : uint8_t

strong

StatsD metric type codes (the token after the |).

Enumerator
STATSD_COUNTER
STATSD_GAUGE
STATSD_TIMING	emitted as "ms"
STATSD_SET

Definition at line 32 of file statsd.h.

Function Documentation

statsd_format()

size_t statsd_format	(	char *	out,
		size_t	cap,
		const char *	name,
		const char *	value,
		StatsdType	type,
		float	rate,
		const char *	tags
	)

Format one StatsD line: name:value|type[|@rate][|#tags]. Pure - no I/O.

Parameters

out	output buffer (NUL-terminated on success).
cap	capacity of out.
name	metric name (e.g. "api.requests").
value	the value already rendered as text (e.g. "1", "-3", "42.5").
type	a StatsdType code ('c','g','m','s').
rate	sample rate in (0,1]; >= 1 emits no |@ annotation.
tags	DogStatsD tag string "k:v,k2:v2" (no leading #), or nullptr for none.

Returns

line length (excluding the NUL), or 0 on a bad argument or overflow.

statsd_begin()

void statsd_begin	(	const char *	host,
		uint16_t	port,
		const char *	global_tags
	)

Point the client at a collector and set optional global tags (added to every metric).

Parameters

host	collector hostname/IP.
port	UDP port (0 selects DETWS_STATSD_PORT).
global_tags	DogStatsD tags applied to every metric, or nullptr.

statsd_count()

void statsd_count	(	const char *	name,
		int64_t	delta
	)

Increment a counter by delta (may be negative).

statsd_count_sampled()

void statsd_count_sampled	(	const char *	name,
		int64_t	delta,
		float	rate
	)

Increment a counter, annotated with sample rate (0,1] so the server scales up.

statsd_gauge()

void statsd_gauge	(	const char *	name,
		int64_t	value
	)

Set a gauge to an absolute value.

statsd_gauge_delta()

void statsd_gauge_delta	(	const char *	name,
		int64_t	delta
	)

Adjust a gauge by a signed delta (sent as a +/- gauge update).

statsd_timing()

void statsd_timing	(	const char *	name,
		uint32_t	ms
	)

Record a timing/duration of ms milliseconds.

statsd_set()

void statsd_set	(	const char *	name,
		const char *	member
	)

Add a unique member to a set (counts distinct values server-side).