Prometheus API

Data Structures
struct	prometheus_collector
	Prometheus collector definition. More...
struct	prometheus_counter
	Type used to represent a Prometheus counter metric. More...
struct	prometheus_gauge
	Type used to represent a Prometheus gauge metric. More...
struct	prometheus_histogram_bucket
	Prometheus histogram bucket definition. More...
struct	prometheus_histogram
	Type used to represent a Prometheus histogram metric. More...
struct	prometheus_label
	Prometheus label definition. More...
struct	prometheus_metric
	Type used to represent a Prometheus metric base. More...
struct	prometheus_summary_quantile
	Prometheus summary quantile definition. More...
struct	prometheus_summary
	Type used to represent a Prometheus summary metric. More...

Macros
#define	PROMETHEUS_COLLECTOR_DEFINE(_name, ...)
	Prometheus Collector definition.
#define	PROMETHEUS_COUNTER_DEFINE(_name, _desc, _label, _collector, ...)
	Prometheus Counter definition.
#define	PROMETHEUS_GAUGE_DEFINE(_name, _desc, _label, _collector, ...)
	Prometheus Gauge definition.
#define	PROMETHEUS_HISTOGRAM_DEFINE(_name, _desc, _label, _collector, ...)
	Prometheus Histogram definition.
#define	MAX_PROMETHEUS_LABELS_PER_METRIC   1
#define	PROMETHEUS_SUMMARY_DEFINE(_name, _desc, _label, _collector, ...)
	Prometheus Summary definition.

Typedefs
typedef int(*	prometheus_scrape_cb_t) (struct prometheus_collector *collector, struct prometheus_metric *metric, void *user_data)
	Callback used to scrape a collector for a specific metric.

Enumerations
enum	prometheus_metric_type { PROMETHEUS_COUNTER = 0 , PROMETHEUS_GAUGE , PROMETHEUS_SUMMARY , PROMETHEUS_HISTOGRAM }
	Prometheus metric types. More...

Functions
int	prometheus_collector_register_metric (struct prometheus_collector *collector, struct prometheus_metric *metric)
	Register a metric with a Prometheus collector.
const void *	prometheus_collector_get_metric (struct prometheus_collector *collector, const char *name)
	Get a metric from a Prometheus collector.
int	prometheus_collector_walk_metrics (struct prometheus_collector_walk_context *ctx, uint8_t *buffer, size_t buffer_size)
	Walk through all metrics in a Prometheus collector and format them into a buffer.
static int	prometheus_collector_walk_init (struct prometheus_collector_walk_context *ctx, struct prometheus_collector *collector)
	Initialize the walker context to walk through all metrics.
int	prometheus_counter_add (struct prometheus_counter *counter, uint64_t value)
	Increment the value of a Prometheus counter metric Increments the value of the specified counter metric by arbitrary amount.
static int	prometheus_counter_inc (struct prometheus_counter *counter)
	Increment the value of a Prometheus counter metric Increments the value of the specified counter metric by one.
int	prometheus_counter_set (struct prometheus_counter *counter, uint64_t value)
	Set the counter value to specific value.
int	prometheus_format_exposition (struct prometheus_collector *collector, char *buffer, size_t buffer_size)
	Format exposition data for Prometheus.
int	prometheus_format_one_metric (struct prometheus_metric *metric, char *buffer, size_t buffer_size, int *written)
	Format exposition data for one metric for Prometheus.
int	prometheus_gauge_set (struct prometheus_gauge *gauge, double value)
	Set the value of a Prometheus gauge metric.
int	prometheus_histogram_observe (struct prometheus_histogram *histogram, double value)
	Observe a value in a Prometheus histogram metric.
int	prometheus_summary_observe (struct prometheus_summary *summary, double value)
	Observes a value in a Prometheus summary metric.
int	prometheus_summary_observe_set (struct prometheus_summary *summary, double value, unsigned long count)
	Set the summary value to specific value.

Detailed Description

Since

4.0

Version

0.1.0

Macro Definition Documentation

MAX_PROMETHEUS_LABELS_PER_METRIC

#define MAX_PROMETHEUS_LABELS_PER_METRIC   1

#include <zephyr/net/prometheus/label.h>

PROMETHEUS_COLLECTOR_DEFINE

#define PROMETHEUS_COLLECTOR_DEFINE	(		_name,
			... )

#include <zephyr/net/prometheus/collector.h>

Value:

        STRUCT_SECTION_ITERABLE(prometheus_collector, _name) = {        \
                .name = STRINGIFY(_name),                               \
                .metrics = SYS_SLIST_STATIC_INIT(&_name.metrics),       \
                .lock = Z_MUTEX_INITIALIZER(_name.lock),                \
                .user_cb = COND_CODE_0(                                 \
                        NUM_VA_ARGS_LESS_1(                             \
                                LIST_DROP_EMPTY(__VA_ARGS__, _)),       \
                        (NULL),                                         \
                        (GET_ARG_N(1, __VA_ARGS__))),                   \
                .user_data = COND_CODE_0(                               \
                        NUM_VA_ARGS_LESS_1(__VA_ARGS__), (NULL),        \
                        (GET_ARG_N(1,                                   \
                                   GET_ARGS_LESS_N(1, __VA_ARGS__)))),  \
        }

Prometheus Collector definition.

This macro defines a Collector.

Parameters

_name	The collector's name.
...	Optional user callback function. If set, this function is called when the collector is scraped. The function should be of type prometheus_scrape_cb_t. Optional user data to pass to the user callback function.

PROMETHEUS_COUNTER_DEFINE

#define PROMETHEUS_COUNTER_DEFINE	(		_name,
			_desc,
			_label,
			_collector,
			... )

#include <zephyr/net/prometheus/counter.h>

Value:

        STRUCT_SECTION_ITERABLE(prometheus_counter, _name) = {          \
                .base.name = STRINGIFY(_name),                          \
                .base.type = PROMETHEUS_COUNTER,                        \
                .base.description = _desc,                              \
                .base.labels[0] = __DEBRACKET _label,                   \
                .base.num_labels = 1,                                   \
                .base.collector = _collector,                           \
                .value = 0ULL,                                          \
                .user_data = COND_CODE_0(                               \
                        NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
                        (NULL),                                         \
                        (GET_ARG_N(1, __VA_ARGS__))),                   \
        }

Prometheus Counter definition.

This macro defines a Counter metric. If you want to make the counter static, then add "static" keyword before the PROMETHEUS_COUNTER_DEFINE.

Parameters

_name	The counter metric name
_desc	Counter description
_label	Label for the metric. Additional labels can be added at runtime.
_collector	Collector to map this metric. Can be set to NULL if it not yet known.
...	Optional user data specific to this metric instance.

Example usage:

PROMETHEUS_COUNTER_DEFINE(http_request_counter, "HTTP request counter",
                          ({ .key = "http_request", .value = "request_count" }),
                          NULL);

PROMETHEUS_GAUGE_DEFINE

#define PROMETHEUS_GAUGE_DEFINE	(		_name,
			_desc,
			_label,
			_collector,
			... )

#include <zephyr/net/prometheus/gauge.h>

Value:

        STRUCT_SECTION_ITERABLE(prometheus_gauge, _name) = {            \
                .base.name = STRINGIFY(_name),                          \
                .base.type = PROMETHEUS_GAUGE,                          \
                .base.description = _desc,                              \
                .base.labels[0] = __DEBRACKET _label,                   \
                .base.num_labels = 1,                                   \
                .base.collector = _collector,                           \
                .value = 0.0,                                           \
                .user_data = COND_CODE_0(                               \
                        NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
                        (NULL),                                         \
                        (GET_ARG_N(1, __VA_ARGS__))),                   \
        }

Prometheus Gauge definition.

This macro defines a Gauge metric. If you want to make the gauge static, then add "static" keyword before the PROMETHEUS_GAUGE_DEFINE.

Parameters

_name	The gauge metric name.
_desc	Gauge description
_label	Label for the metric. Additional labels can be added at runtime.
_collector	Collector to map this metric. Can be set to NULL if it not yet known.
...	Optional user data specific to this metric instance.

Example usage:

PROMETHEUS_GAUGE_DEFINE(http_request_gauge, "HTTP request gauge",
                        ({ .key = "http_request", .value = "request_count" }),
                        NULL);

PROMETHEUS_HISTOGRAM_DEFINE

#define PROMETHEUS_HISTOGRAM_DEFINE	(		_name,
			_desc,
			_label,
			_collector,
			... )

#include <zephyr/net/prometheus/histogram.h>

Value:

        STRUCT_SECTION_ITERABLE(prometheus_histogram, _name) = {        \
                .base.name = STRINGIFY(_name),                          \
                .base.type = PROMETHEUS_HISTOGRAM,                      \
                .base.description = _desc,                              \
                .base.labels[0] = __DEBRACKET _label,                   \
                .base.num_labels = 1,                                   \
                .base.collector = _collector,                           \
                .buckets = NULL,                                        \
                .num_buckets = 0,                                       \
                .sum = 0.0,                                             \
                .count = 0U,                                            \
                .user_data = COND_CODE_0(                               \
                        NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
                        (NULL),                                         \
                        (GET_ARG_N(1, __VA_ARGS__))),                   \
        }

Prometheus Histogram definition.

This macro defines a Histogram metric. If you want to make the histogram static, then add "static" keyword before the PROMETHEUS_HISTOGRAM_DEFINE.

Parameters

_name	The histogram metric name.
_desc	Histogram description
_label	Label for the metric. Additional labels can be added at runtime.
_collector	Collector to map this metric. Can be set to NULL if it not yet known.
...	Optional user data specific to this metric instance.

Example usage:

PROMETHEUS_HISTOGRAM_DEFINE(http_request_histogram, "HTTP request histogram",
                        ({ .key = "request_latency", .value = "request_latency_seconds" }),
                        NULL);

PROMETHEUS_SUMMARY_DEFINE

#define PROMETHEUS_SUMMARY_DEFINE	(		_name,
			_desc,
			_label,
			_collector,
			... )

#include <zephyr/net/prometheus/summary.h>

Value:

        STRUCT_SECTION_ITERABLE(prometheus_summary, _name) = {          \
                .base.name = STRINGIFY(_name),                          \
                .base.type = PROMETHEUS_SUMMARY,                        \
                .base.description = _desc,                              \
                .base.labels[0] = __DEBRACKET _label,                   \
                .base.num_labels = 1,                                   \
                .base.collector = _collector,                           \
                .quantiles = NULL,                                      \
                .num_quantiles = 0,                                     \
                .sum = 0.0,                                             \
                .count = 0U,                                            \
                .user_data = COND_CODE_0(                               \
                        NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
                        (NULL),                                         \
                        (GET_ARG_N(1, __VA_ARGS__))),                   \
        }

Prometheus Summary definition.

This macro defines a Summary metric. If you want to make the summary static, then add "static" keyword before the PROMETHEUS_SUMMARY_DEFINE.

Parameters

_name	The summary metric name.
_desc	Summary description
_label	Label for the metric. Additional labels can be added at runtime.
_collector	Collector to map this metric. Can be set to NULL if it not yet known.
...	Optional user data specific to this metric instance.

Example usage:

PROMETHEUS_SUMMARY_DEFINE(http_request_summary, "HTTP request summary",
                          ({ .key = "request_latency",
                             .value = "request_latency_seconds" }), NULL);

Typedef Documentation

prometheus_scrape_cb_t

typedef int(* prometheus_scrape_cb_t) (struct prometheus_collector *collector, struct prometheus_metric *metric, void *user_data)

#include <zephyr/net/prometheus/collector.h>

Callback used to scrape a collector for a specific metric.

Parameters

collector	A valid pointer on the collector to scrape
metric	A valid pointer on the metric to scrape
user_data	A valid pointer to a user data or NULL

Returns

0 if successful, otherwise a negative error code.

Enumeration Type Documentation

prometheus_metric_type

enum prometheus_metric_type

#include <zephyr/net/prometheus/metric.h>

Prometheus metric types.

• References
• See https://prometheus.io/docs/concepts/metric_types

Enumerator
PROMETHEUS_COUNTER	Prometheus Counter.
PROMETHEUS_GAUGE	Prometheus Gauge.
PROMETHEUS_SUMMARY	Prometheus Summary.
PROMETHEUS_HISTOGRAM	Prometheus Histogram.

Function Documentation

prometheus_collector_get_metric()

const void * prometheus_collector_get_metric	(	struct prometheus_collector *	collector,
		const char *	name )

#include <zephyr/net/prometheus/collector.h>

Get a metric from a Prometheus collector.

Retrieves the metric with the specified name from the given collector.

Parameters

collector	Pointer to the collector to retrieve the metric from.
name	Name of the metric to retrieve.

Returns

Pointer to the retrieved metric, or NULL if not found.

prometheus_collector_register_metric()

int prometheus_collector_register_metric	(	struct prometheus_collector *	collector,
		struct prometheus_metric *	metric )

#include <zephyr/net/prometheus/collector.h>

Register a metric with a Prometheus collector.

Registers the specified metric with the given collector.

Parameters

collector	Pointer to the collector to register the metric with.
metric	Pointer to the metric to register.

Returns

0 if successful, otherwise a negative error code.

Return values

-EINVAL	Invalid arguments.
-ENOMEM	Not enough memory to register the metric.

prometheus_collector_walk_init()

static int prometheus_collector_walk_init ( struct prometheus_collector_walk_context * ctx, struct prometheus_collector * collector )

inlinestatic

#include <zephyr/net/prometheus/collector.h>

Initialize the walker context to walk through all metrics.

Parameters

ctx	Pointer to the walker context.
collector	Pointer to the collector to walk through.

Returns

0 if successful, otherwise a negative error code.

prometheus_collector_walk_metrics()

int prometheus_collector_walk_metrics	(	struct prometheus_collector_walk_context *	ctx,
		uint8_t *	buffer,
		size_t	buffer_size )

#include <zephyr/net/prometheus/collector.h>

Walk through all metrics in a Prometheus collector and format them into a buffer.

Parameters

ctx	Pointer to the walker context.
buffer	Pointer to the buffer to store the formatted metrics.
buffer_size	Size of the buffer.

Returns

0 if successful and we went through all metrics, -EAGAIN if we need to call this function again, any other negative error code means an error occurred.

prometheus_counter_add()

int prometheus_counter_add	(	struct prometheus_counter *	counter,
		uint64_t	value )

#include <zephyr/net/prometheus/counter.h>

Increment the value of a Prometheus counter metric Increments the value of the specified counter metric by arbitrary amount.

Parameters

counter	Pointer to the counter metric to increment.
value	Amount to increment the counter by.

Returns

0 on success, negative errno on error.

prometheus_counter_inc()

static int prometheus_counter_inc ( struct prometheus_counter * counter )

inlinestatic

#include <zephyr/net/prometheus/counter.h>

Increment the value of a Prometheus counter metric Increments the value of the specified counter metric by one.

Parameters

counter

Pointer to the counter metric to increment.

Returns

0 on success, negative errno on error.

prometheus_counter_set()

int prometheus_counter_set	(	struct prometheus_counter *	counter,
		uint64_t	value )

#include <zephyr/net/prometheus/counter.h>

Set the counter value to specific value.

The new value must be higher than the current value. This function can be used if we cannot add individual increments to the counter but need to periodically update the counter value. This function will add the difference between the new value and the old value to the counter.

Parameters

counter	Pointer to the counter metric to increment.
value	New value of the counter.

Returns

0 on success, negative errno on error.

prometheus_format_exposition()

int prometheus_format_exposition	(	struct prometheus_collector *	collector,
		char *	buffer,
		size_t	buffer_size )

#include <zephyr/net/prometheus/formatter.h>

Format exposition data for Prometheus.

Formats the exposition data collected by the specified collector into the provided buffer. Function will format metric data according to Prometheus text-based format

Parameters

collector	Pointer to the collector containing the data to format.
buffer	Pointer to the buffer where the formatted exposition data will be stored.
buffer_size	Size of the buffer.

Returns

0 on success, negative errno on error.

prometheus_format_one_metric()

int prometheus_format_one_metric	(	struct prometheus_metric *	metric,
		char *	buffer,
		size_t	buffer_size,
		int *	written )

#include <zephyr/net/prometheus/formatter.h>

Format exposition data for one metric for Prometheus.

Formats the exposition data of one specific metric into the provided buffer. Function will format metric data according to Prometheus text-based format.

Parameters

metric	Pointer to the metric containing the data to format.
buffer	Pointer to the buffer where the formatted exposition data will be stored.
buffer_size	Size of the buffer.
written	How many bytes have been written to the buffer.

Returns

0 on success, negative errno on error.

prometheus_gauge_set()

int prometheus_gauge_set	(	struct prometheus_gauge *	gauge,
		double	value )

#include <zephyr/net/prometheus/gauge.h>

Set the value of a Prometheus gauge metric.

Sets the value of the specified gauge metric to the given value.

Parameters

gauge	Pointer to the gauge metric to set.
value	Value to set the gauge metric to.

Returns

0 on success, -EINVAL if the value is negative.

prometheus_histogram_observe()

int prometheus_histogram_observe	(	struct prometheus_histogram *	histogram,
		double	value )

#include <zephyr/net/prometheus/histogram.h>

Observe a value in a Prometheus histogram metric.

Observes the specified value in the given histogram metric.

Parameters

histogram	Pointer to the histogram metric to observe.
value	Value to observe in the histogram metric.

Returns

0 on success, -EINVAL if the value is negative.

prometheus_summary_observe()

int prometheus_summary_observe	(	struct prometheus_summary *	summary,
		double	value )

#include <zephyr/net/prometheus/summary.h>

Observes a value in a Prometheus summary metric.

Observes the specified value in the given summary metric.

Parameters

summary	Pointer to the summary metric to observe.
value	Value to observe in the summary metric.

Returns

0 on success, -EINVAL if the value is negative.

prometheus_summary_observe_set()

int prometheus_summary_observe_set	(	struct prometheus_summary *	summary,
		double	value,
		unsigned long	count )

#include <zephyr/net/prometheus/summary.h>

Set the summary value to specific value.

The new value must be higher than the current value. This function can be used if we cannot add individual increments to the summary but need to periodically update the counter value. This function will add the difference between the new value and the old value to the summary fields.

Parameters

summary	Pointer to the summary metric to increment.
value	New value of the summary.
count	New counter value of the summary.

Returns

0 on success, negative errno on error.