metrics.h File Reference

Production-grade metrics engine for CWIST. More...

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

Include dependency graph for metrics.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cwist_metric_value
	Atomic metric value container. More...
struct	cwist_metric
	Single metric definition. More...

Typedefs
typedef enum cwist_metric_type	cwist_metric_type_t
	Supported Prometheus metric kinds.
typedef struct cwist_metric_value	cwist_metric_value_t
	Atomic metric value container.
typedef struct cwist_metric	cwist_metric_t
	Single metric definition.
typedef enum cwist_metric_id	cwist_metric_id_t
	Pre-defined framework metrics.
typedef struct cwist_metrics_registry	cwist_metrics_registry_t
	Global metrics registry (singleton, lazy-initialised).

Enumerations
enum	cwist_metric_type { CWIST_METRIC_COUNTER , CWIST_METRIC_GAUGE , CWIST_METRIC_HISTOGRAM }
	Supported Prometheus metric kinds. More...
enum	cwist_metric_id {   CWIST_METRIC_URING_SQES_PENDING , CWIST_METRIC_URING_BUFFERS_ACTIVE , CWIST_METRIC_STREAMS_HTTP2 , CWIST_METRIC_STREAMS_HTTP3 ,   CWIST_METRIC_FLOW_WINDOW_HEALTH , CWIST_METRIC_VALIDATION_ERRORS , CWIST_METRIC_REQUESTS_TOTAL , CWIST_METRIC_REQUEST_DURATION_NS ,   CWIST_METRIC_HTTP_HEADER_OVERFLOW , CWIST_METRIC_H2_HEADERS_DROPPED , CWIST_METRIC_HTTP_CONTINUATION_SHED , CWIST_METRIC_TLS_HANDSHAKES_TOTAL ,   CWIST_METRIC_TLS_HANDSHAKES_RESUMED , CWIST_METRIC_TLS_CONNECTIONS_ACTIVE , CWIST_METRIC_TLS_HANDSHAKES_TLS12 , CWIST_METRIC_TLS_HANDSHAKES_TLS13 ,   CWIST_METRIC_TLS_CIPHERS_AES128_GCM , CWIST_METRIC_TLS_CIPHERS_AES256_GCM , CWIST_METRIC_TLS_CIPHERS_CHACHA20 , CWIST_METRIC_TLS_CIPHERS_OTHER ,   CWIST_METRIC_COUNT }
	Pre-defined framework metrics. More...

Functions
cwist_metrics_registry_t *	cwist_metrics_registry (void)
	Obtain the global registry, creating it on first call.
void	cwist_metrics_reset (cwist_metrics_registry_t *reg)
	Reset all metrics in the registry to zero.
void	cwist_metric_inc (cwist_metrics_registry_t *reg, cwist_metric_id_t id)
	Increment a counter metric by 1.
void	cwist_metric_add (cwist_metrics_registry_t *reg, cwist_metric_id_t id, uintmax_t delta)
	Increment a counter metric by delta.
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 value into a histogram-like metric.
uintmax_t	cwist_metric_load (const cwist_metrics_registry_t *reg, cwist_metric_id_t id)
	Atomically load the current raw value of a metric.
char *	cwist_metrics_render_prometheus (const cwist_metrics_registry_t *reg)
	Render all metrics in Prometheus text exposition format.
void	cwist_metrics_serve_http (struct cwist_http_response *res)
	Convenience helper: populate an HTTP response with /metrics body.

Detailed Description

Production-grade metrics engine for CWIST.

Exposes Prometheus-compatible text format via a /metrics endpoint. All counters are updated with lock-free atomic operations to ensure zero performance degradation on the hot path.

Definition in file metrics.h.

Typedef Documentation

cwist_metric_id_t

typedef enum cwist_metric_id cwist_metric_id_t

Pre-defined framework metrics.

cwist_metric_t

typedef struct cwist_metric cwist_metric_t

Single metric definition.

cwist_metric_type_t

typedef enum cwist_metric_type cwist_metric_type_t

Supported Prometheus metric kinds.

cwist_metric_value_t

typedef struct cwist_metric_value cwist_metric_value_t

Atomic metric value container.

cwist_metrics_registry_t

typedef struct cwist_metrics_registry cwist_metrics_registry_t

Global metrics registry (singleton, lazy-initialised).

The registry is safe to access from multiple threads without external locking because every update is an atomic operation.

Definition at line 87 of file metrics.h.

Enumeration Type Documentation

cwist_metric_id

enum cwist_metric_id

Pre-defined framework metrics.

Enumerator
CWIST_METRIC_URING_SQES_PENDING	Active SQEs waiting for kernel.
CWIST_METRIC_URING_BUFFERS_ACTIVE	In-flight fixed buffers.
CWIST_METRIC_STREAMS_HTTP2	Active HTTP/2 streams.
CWIST_METRIC_STREAMS_HTTP3	Active HTTP/3 streams.
CWIST_METRIC_FLOW_WINDOW_HEALTH	Flow-control window health (0-100).
CWIST_METRIC_VALIDATION_ERRORS	Validation error frequency.
CWIST_METRIC_REQUESTS_TOTAL	Total HTTP requests handled.
CWIST_METRIC_REQUEST_DURATION_NS	Request duration (nanoseconds sum).
CWIST_METRIC_HTTP_HEADER_OVERFLOW	H1 connections dropped: headers exceeded read buffer.
CWIST_METRIC_H2_HEADERS_DROPPED	H2 header fields dropped: unresolvable HPACK index.
CWIST_METRIC_HTTP_CONTINUATION_SHED	Pipelined continuations dropped due to full reactor queue.
CWIST_METRIC_TLS_HANDSHAKES_TOTAL	TLS handshakes completed (full + resumed).
CWIST_METRIC_TLS_HANDSHAKES_RESUMED	TLS handshakes resumed via session/ticket.
CWIST_METRIC_TLS_CONNECTIONS_ACTIVE	Currently established TLS connections.
CWIST_METRIC_TLS_HANDSHAKES_TLS12	Handshakes negotiated as TLS 1.2.
CWIST_METRIC_TLS_HANDSHAKES_TLS13	Handshakes negotiated as TLS 1.3.
CWIST_METRIC_TLS_CIPHERS_AES128_GCM	TLS_AES_128_GCM_SHA256 handshakes.
CWIST_METRIC_TLS_CIPHERS_AES256_GCM	TLS_AES_256_GCM_SHA384 handshakes.
CWIST_METRIC_TLS_CIPHERS_CHACHA20	TLS_CHACHA20_POLY1305_SHA256 handshakes.
CWIST_METRIC_TLS_CIPHERS_OTHER	Handshakes with any other cipher.
CWIST_METRIC_COUNT

Definition at line 51 of file metrics.h.

cwist_metric_type

enum cwist_metric_type

Supported Prometheus metric kinds.

Enumerator
CWIST_METRIC_COUNTER	Monotonically increasing counter.
CWIST_METRIC_GAUGE	Arbitrary value that can go up or down.
CWIST_METRIC_HISTOGRAM	Bucketed observations (simplified).

Definition at line 29 of file metrics.h.

Function Documentation

cwist_metric_add()

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

Increment a counter metric by delta.

Parameters

reg	Registry.
id	Metric identifier.
delta	Amount to add.

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 counter metric by 1.

Parameters

reg	Registry.
id	Metric identifier.

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
	)

Atomically load the current raw value of a metric.

Parameters

reg	Registry.
id	Metric identifier.

Returns

Current raw value.

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 value into a histogram-like metric.

Parameters

reg	Registry.
id	Metric identifier.
value	Observed value.

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.

Parameters

reg	Registry.
id	Metric identifier.
value	New absolute value (internally scaled by 1000).

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

)

Obtain the global registry, creating it on first call.

Returns

Pointer to the global 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 all metrics in Prometheus text exposition format.

The returned string is heap-allocated and must be freed by the caller using standard free().

Parameters

reg	Registry to render.

Returns

Null-terminated Prometheus text, or NULL on OOM.

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 the registry to zero.

Parameters

reg	Registry to clear.

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

)

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

Sets Content-Type to text/plain; version=0.0.4 and fills the body with the current Prometheus snapshot.

Parameters

res	Response to populate.

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.