metrics.c File Reference

Lock-free metrics registry and Prometheus exposition. More...

#include <cwist/sys/metrics/metrics.h>
#include <cwist/net/http/http.h>
#include <cwist/net/http/https.h>
#include <cwist/core/sstring/sstring.h>
#include <cwist/core/mem/alloc.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>

Include dependency graph for metrics.c:

Go to the source code of this file.

Functions
cwist_metrics_registry_t *	cwist_metrics_registry (void)
	Return the process-wide singleton metrics registry.
void	cwist_metrics_reset (cwist_metrics_registry_t *reg)
	Reset all metrics in a registry to zero.
void	cwist_metric_inc (cwist_metrics_registry_t *reg, cwist_metric_id_t id)
	Increment a metric's value by one and bump its observation count.
void	cwist_metric_add (cwist_metrics_registry_t *reg, cwist_metric_id_t id, uintmax_t delta)
	Add a delta to a metric's value and bump its observation count.
void	cwist_metric_set (cwist_metrics_registry_t *reg, cwist_metric_id_t id, long double value)
	Set a gauge metric to an absolute value.
void	cwist_metric_observe (cwist_metrics_registry_t *reg, cwist_metric_id_t id, long double value)
	Observe a sample for a metric: accumulate sum and bump the count.
uintmax_t	cwist_metric_load (const cwist_metrics_registry_t *reg, cwist_metric_id_t id)
	Read the current raw value of a metric.
char *	cwist_metrics_render_prometheus (const cwist_metrics_registry_t *reg)
	Render the full registry in Prometheus text exposition format.
void	cwist_metrics_serve_http (cwist_http_response *res)
	HTTP handler that serves the metrics registry as Prometheus text.

Detailed Description

Lock-free metrics registry and Prometheus exposition.

Definition in file metrics.c.

Function Documentation

cwist_metric_add()

void cwist_metric_add	(	cwist_metrics_registry_t *	reg,
		cwist_metric_id_t	id,
		uintmax_t	delta
	)

Add a delta to a metric's value and bump its observation count.

Increment a counter metric by delta.

Lock-free relaxed atomic update; safe to call from any thread.

Parameters

reg	Registry holding the metric; NULL is a no-op.
id	Metric identifier; out-of-range ids are ignored.
delta	Value increment to add.

Definition at line 194 of file metrics.c.

References cap, and CWIST_METRIC_COUNT.

Referenced by cwist_mw_metrics_handler().

cwist_metric_inc()

void cwist_metric_inc	(	cwist_metrics_registry_t *	reg,
		cwist_metric_id_t	id
	)

Increment a metric's value by one and bump its observation count.

Increment a counter metric by 1.

Lock-free relaxed atomic update; safe to call from any thread.

Parameters

reg	Registry holding the metric; NULL is a no-op.
id	Metric identifier; out-of-range ids are ignored.

Definition at line 179 of file metrics.c.

References cap, and CWIST_METRIC_COUNT.

Referenced by cwist_http_async_rearm(), cwist_http_receive_request(), cwist_http_receive_request_nb(), and cwist_mw_metrics_handler().

cwist_metric_load()

uintmax_t cwist_metric_load	(	const cwist_metrics_registry_t *	reg,
		cwist_metric_id_t	id
	)

Read the current raw value of a metric.

Atomically load the current raw value of a metric.

Acquire load of the stored raw (fixed-point scaled) value. For CWIST_METRIC_HTTP_CONTINUATION_SHED the value is read live from the net/http shed counter instead of the registry.

Parameters

reg	Registry holding the metric; NULL returns 0.
id	Metric identifier; out-of-range ids return 0.

Returns

Current raw metric value.

Definition at line 247 of file metrics.c.

References cap, cwist_http_continuation_shed_count(), CWIST_METRIC_COUNT, and CWIST_METRIC_HTTP_CONTINUATION_SHED.

cwist_metric_observe()

void cwist_metric_observe	(	cwist_metrics_registry_t *	reg,
		cwist_metric_id_t	id,
		long double	value
	)

Observe a sample for a metric: accumulate sum and bump the count.

Observe a value into a histogram-like metric.

The value is stored with fixed-point scaling (roundl(value * 1000)), added to both the raw accumulated value and the sum, while the observation count is incremented by one. Lock-free relaxed atomic update; safe to call from any thread.

Parameters

reg	Registry holding the metric; NULL is a no-op.
id	Metric identifier; out-of-range ids are ignored.
value	Observed sample value.

Definition at line 228 of file metrics.c.

References cap, and CWIST_METRIC_COUNT.

cwist_metric_set()

void cwist_metric_set	(	cwist_metrics_registry_t *	reg,
		cwist_metric_id_t	id,
		long double	value
	)

Set a gauge metric to an absolute value.

The value is stored with fixed-point scaling: the raw value is roundl(value * 1000), so one unit is 0.001 in rendered output.

Parameters

reg	Registry holding the metric; NULL is a no-op.
id	Metric identifier; out-of-range ids are ignored.
value	New absolute value.

Definition at line 210 of file metrics.c.

References cap, and CWIST_METRIC_COUNT.

cwist_metrics_registry()

cwist_metrics_registry_t * cwist_metrics_registry

(

void

)

Return the process-wide singleton metrics registry.

Obtain the global registry, creating it on first call.

Allocates and initializes the registry on first call; later calls return the cached pointer. All metric atomics are zero-initialized from the static metric_defaults table.

Returns

Pointer to the singleton registry, or NULL on allocation failure.

Definition at line 112 of file metrics.c.

References cap, cwist_alloc(), CWIST_METRIC_COUNT, and cwist_metrics_registry().

Referenced by cwist_http_async_rearm(), cwist_http_receive_request(), cwist_http_receive_request_nb(), cwist_metrics_registry(), cwist_metrics_serve_http(), and cwist_mw_metrics_handler().

cwist_metrics_render_prometheus()

char * cwist_metrics_render_prometheus

(

const cwist_metrics_registry_t *

reg

)

Render the full registry in Prometheus text exposition format.

Render all metrics in Prometheus text exposition format.

Before rendering, synchronizes the HTTP_CONTINUATION_SHED metric from the live net/http shed counter into the registry (cast away const for that store). The output buffer grows by doubling and is heap-allocated; the caller owns it.

Parameters

reg	Registry to render; NULL returns NULL.

Returns

Newly allocated NUL-terminated exposition text, or NULL on allocation or formatting failure.

Definition at line 286 of file metrics.c.

References cap, count, cwist_http_continuation_shed_count(), CWIST_METRIC_COUNT, and CWIST_METRIC_HTTP_CONTINUATION_SHED.

Referenced by cwist_metrics_serve_http().

cwist_metrics_reset()

void cwist_metrics_reset

(

cwist_metrics_registry_t *

reg

)

Reset all metrics in a registry to zero.

Reset all metrics in the registry to zero.

Parameters

reg	Registry to reset; NULL is a no-op.

Definition at line 133 of file metrics.c.

References cap, and CWIST_METRIC_COUNT.

cwist_metrics_serve_http()

void cwist_metrics_serve_http

(

cwist_http_response *

res

)

HTTP handler that serves the metrics registry as Prometheus text.

Convenience helper: populate an HTTP response with /metrics body.

On success sets the response status to 200 OK with the exposition text as body and a Prometheus text Content-Type header. On render failure sets 500 INTERNAL_ERROR with a "metrics render failed" body.

Parameters

res	Response to fill; NULL is a no-op. The body sstring is assigned via cwist_sstring_assign.

Definition at line 366 of file metrics.c.

References cwist_http_response::body, cap, cwist_http_header_add(), CWIST_HTTP_INTERNAL_ERROR, CWIST_HTTP_OK, cwist_metrics_registry(), cwist_metrics_render_prometheus(), cwist_sstring_assign(), cwist_http_response::headers, and cwist_http_response::status_code.