The collector registry registers collectors for metric exposition. More...

#include <stdbool.h>
#include "prom_collector.h"
#include "prom_metric.h"

Include dependency graph for prom_collector_registry.h:

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

Macros
#define	METRIC_LABEL_SCRAPE "libprom"
	Reserved label value for libprom's own scrape duration metrics. More...

#define	METRIC_NAME_SCRAPE "scrape_duration_seconds"
	Reserved name for libprom's own scrape duration metric. More...

#define	COLLECTOR_NAME_DEFAULT "default"
	Reserved name for libprom's own default prom collector, where usually new metrics get attached. More...

#define	COLLECTOR_NAME_PROCESS "process"
	Reserved name for libprom's own process stats prom collector. More...

#define	REGISTRY_NAME_DEFAULT "default"
	Reserved name for libprom's own default prom collector registry. More...

#define	PROM_COLLECTOR_REGISTRY_DEFAULT PROM_COLLECTOR_REGISTRY
	backward compatibility to 0.1.3 - will vanish soon.

Typedefs
typedef unsigned int	PROM_INIT_FLAGS
	collection of prom collector registry features. More...

typedef struct pcr	pcr_t
	A prom_registry_t is responsible for registering metrics and briding them to the string exposition format.

Enumerations
enum	prom_init_flag { PROM_NONE = 0, PROM_PROCESS = 1, PROM_SCRAPETIME = 2, PROM_SCRAPETIME_ALL = 4, PROM_COMPACT = 8 }
	flags for the setup of a prom collector registry. More...

Functions
int	pcr_default_init (void)
	Initializes the default collector registry. More...

int	pcr_init (PROM_INIT_FLAGS features, const char *mprefix)
	Initializes the default collector registry `PROM_COLLECTOR_REGISTRY` named `REGISTRY_NAME_DEFAULT`. More...

pcr_t *	pcr_new (const char *name)
	Constructs a registry named `default` which contains one empty prom collector named `default` , only. More...

int	pcr_destroy (pcr_t *self)
	Destroy the given collector registry. More...

int	pcr_enable_process_metrics (pcr_t *self)
	Enable process metrics on the given collector registry. More...

int	pcr_enable_scrape_metrics (pcr_t *self)
	Create a scrape duration gauge metric and attach it to the given prom collector registry. More...

prom_metric_t *	pcr_must_register_metric (prom_metric_t *metric)
	Registers a metric with the default collector on PROM_COLLECTOR_REGISTRY. More...

int	pcr_register_metric (prom_metric_t *metric)
	Registers a metric with the default collector on PROM_COLLECTOR_REGISTRY. More...

int	pcr_register_collector (pcr_t self, prom_collector_t collector)
	Register a collector with the given registry. More...

prom_collector_t *	pcr_get (pcr_t self, const char name)
	Get a reference to the prom collector with the given name from the given prom collector registry. More...

char *	pcr_bridge (pcr_t *self)
	Export all relevant metrics registered with the given registry in the default metric exposition format as a single string. More...

int	pcr_validate_metric_name (pcr_t self, const char metric_name)
	Validates that the given metric name complies with the specification: More...

int	pcr_check_name (const char *name, bool is_label)
	Check whether the given label \| metric name complies with the specification: More...

Variables
pcr_t *	PROM_COLLECTOR_REGISTRY
	Initialize the default registry by calling pcr_init() within your app. More...

Detailed Description

The collector registry registers collectors for metric exposition.

Macro Definition Documentation

◆ COLLECTOR_NAME_DEFAULT

#define COLLECTOR_NAME_DEFAULT "default"

Reserved name for libprom's own default prom collector, where usually new metrics get attached.

Note: Do not use unless you know, what you are doing.

◆ COLLECTOR_NAME_PROCESS

#define COLLECTOR_NAME_PROCESS "process"

Reserved name for libprom's own process stats prom collector.

Note: Do not use unless you know, what you are doing.

◆ METRIC_LABEL_SCRAPE

#define METRIC_LABEL_SCRAPE "libprom"

Reserved label value for libprom's own scrape duration metrics.

Note: Do not use unless you know, what you are doing.

◆ METRIC_NAME_SCRAPE

#define METRIC_NAME_SCRAPE "scrape_duration_seconds"

Reserved name for libprom's own scrape duration metric.

Note: Do not use unless you know, what you are doing.

◆ REGISTRY_NAME_DEFAULT

#define REGISTRY_NAME_DEFAULT "default"

Reserved name for libprom's own default prom collector registry.

Note: Do not use unless you know, what you are doing.

Typedef Documentation

◆ PROM_INIT_FLAGS

typedef unsigned int PROM_INIT_FLAGS

collection of prom collector registry features.

See also: prom_init_flag

Enumeration Type Documentation

◆ prom_init_flag

enum prom_init_flag

flags for the setup of a prom collector registry.

See also: pcr_init()

Enumerator
PROM_NONE	placeholder for `0` - implies nothing
PROM_PROCESS	Automatically setup and attach a `process` collector, which collects stats of this process on `pcr_bridge()` and appends its to the output.
PROM_SCRAPETIME	Automatically create and use a metric to monitor the time needed to dump all the metrics of all registered collectors in Prometheus exposition format and include it in the dump as well. The metric gets labeled as `METRIC_LABEL_SCRAPE` , the metric's implied name is `METRIC_NAME_SCRAPE` .
PROM_SCRAPETIME_ALL	Implies `PROM_SCRAPETIME`, but measures and dumps the dump time of every single collector as well. The related metrics get labeled with the name of the collector.
PROM_COMPACT	Omit any "# HELP" and `"# TYPE"` lines in metric exports. These are wrt. the Prometheus exposition format optional and e.g. Victoria-Metrics vmagent as well as timeseries DB ignore them completely because simply not needed. So allows less trash and communication overhead.

Function Documentation

◆ pcr_bridge()

char* pcr_bridge ( pcr_t * self )

Export all relevant metrics registered with the given registry in the default metric exposition format as a single string.

This string MUST be freed to avoid unnecessary heap memory growth.

Reference: https://prometheus.io/docs/instrumenting/exposition_formats/

Parameters

self	The registry containing the collectors with the relevant metrics.

Returns: NULL on failure, the export otherwise.

◆ pcr_check_name()

int pcr_check_name	(	const char *	name,
		bool	is_label
	)

Check whether the given label | metric name complies with the specification:

Reference: https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels

Parameters

name	Name to validate
is_label	Use 0 to indicate name is a metric name, or 1 to force a label name check.

Returns: 0 if the given name is ok, a non-zero integer value otherwise.

◆ pcr_default_init()

int pcr_default_init ( void )

Initializes the default collector registry.

PROM_COLLECTOR_REGISTRY and enables metric collection on the executing process and sets the metric name prefix to METRIC_LABEL_SCRAPE + "_". Same as pcr_init(PROM_PROCESS|PROM_SCRAPETIME, METRIC_LABEL_SCRAPE "_").

Returns: A non-zero integer value upon failure. 0 otherwise.

◆ pcr_destroy()

int pcr_destroy ( pcr_t * self )

Destroy the given collector registry.

Before it releases its handles to registered collectors, it calls prom_collector_destroy() on them, and this in turn calls prom_metric_destroy() for all the collector's metrics. So keep in mind, that after this call all registered collectors and related metrics will not work anymore.

Parameters

self	Registry to destroy.

Returns: A non-zero integer value upon failure, 0 otherwise.

Note: No matter what is returned, one should always set the pointer of the given registry to NULL because it gets always passed to free() and thus points to an invalid memory location on return.

◆ pcr_enable_process_metrics()

int pcr_enable_process_metrics ( pcr_t * self )

Enable process metrics on the given collector registry.

Parameters

self	The registry, where to attach the process metrics.

Returns: A non-zero integer value upon failure, 0 otherwise.

◆ pcr_enable_scrape_metrics()

int pcr_enable_scrape_metrics ( pcr_t * self )

Create a scrape duration gauge metric and attach it to the given prom collector registry.

If available, pcr_bridge() measures the time needed to collect and export all metrics of the registry, updates the metric and appends it to the export.

Parameters

self	Where to enable scrape duration monitoring.

Returns: A non-zero integer if the given registry is NULL, or the metric could not be added to its default collector, 0 otherwise.

◆ pcr_get()

prom_collector_t* pcr_get	(	pcr_t *	self,
		const char *	name
	)

Get a reference to the prom collector with the given name from the given prom collector registry.

Parameters

self	Registry to query.
name	Name of the collector to lookup.

Returns: NULL if not found, a reference to the related prom collector otherwise.

◆ pcr_init()

int pcr_init	(	PROM_INIT_FLAGS	features,
		const char *	mprefix
	)

Initializes the default collector registry PROM_COLLECTOR_REGISTRY named REGISTRY_NAME_DEFAULT.

Parameters

features	If `0`, a prom collector registry gets created, which just contains a single empty collector named `COLLECTOR_NAME_DEFAULT` where per default all new metrics get attached.
mprefix	If not `NULL`, prefix each metric's name with this string when metrics get exposed. E.g. one may use "appname_".

Returns: A non-zero integer value upon failure - the registry is unusable.

◆ pcr_must_register_metric()

prom_metric_t* pcr_must_register_metric ( prom_metric_t * metric )

Registers a metric with the default collector on PROM_COLLECTOR_REGISTRY.

The metric to be registered MUST NOT already be registered with the given. If so, the function calls exit() - probably not what you want! NOTE: PROM_COLLECTOR_REGISTRY must be registered via pcr_init() prior to calling this function. The metric will be added to the default registry's default collector.

Parameters

metric The metric to register.

Returns: The registered metric, or NULL if registration failed.

◆ pcr_new()

pcr_t* pcr_new ( const char * name )

Constructs a registry named default which contains one empty prom collector named default , only.

Parameters

name	Name of the collector registry. It MUST NOT be `default`.

Returns: The new registry on success, NULL otherwise.

◆ pcr_register_collector()

int pcr_register_collector	(	pcr_t *	self,
		prom_collector_t *	collector
	)

Register a collector with the given registry.

If the registry already contains a collector with the same name, the registration will fail.

Parameters

self	Where to register the collector.
collector	The collector to register.

Returns: A non-zero integer value upon failure, 0 otherwise.

◆ pcr_register_metric()

int pcr_register_metric ( prom_metric_t * metric )

Registers a metric with the default collector on PROM_COLLECTOR_REGISTRY.

◆ pcr_validate_metric_name()

int pcr_validate_metric_name	(	pcr_t *	self,
		const char *	metric_name
	)

Validates that the given metric name complies with the specification:

Reference: https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels

Returns a non-zero integer value on failure, 0 otherwise.

Parameters

self	Registry to use.
metric_name	Name to validate

Returns: A non-zero integer value upon failure, 0 otherwise.

Deprecated:: since 1.1.0

See also: Use pcr_check_name(name, 1) instead.

Variable Documentation

◆ PROM_COLLECTOR_REGISTRY

pcr_t* PROM_COLLECTOR_REGISTRY

Initialize the default registry by calling pcr_init() within your app.

Note: You MUST NOT modify this value.

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ COLLECTOR_NAME_DEFAULT

◆ COLLECTOR_NAME_PROCESS

◆ METRIC_LABEL_SCRAPE

◆ METRIC_NAME_SCRAPE

◆ REGISTRY_NAME_DEFAULT

Typedef Documentation

◆ PROM_INIT_FLAGS

Enumeration Type Documentation

◆ prom_init_flag

Function Documentation

◆ pcr_bridge()

◆ pcr_check_name()

◆ pcr_default_init()

◆ pcr_destroy()

◆ pcr_enable_process_metrics()

◆ pcr_enable_scrape_metrics()

◆ pcr_get()

◆ pcr_init()

◆ pcr_must_register_metric()

◆ pcr_new()

◆ pcr_register_collector()

◆ pcr_register_metric()

◆ pcr_validate_metric_name()

Variable Documentation

◆ PROM_COLLECTOR_REGISTRY