prom_collector.h File Reference

A prom_collector is used to collect metrics. More...

#include <sys/types.h>
#include "prom_map.h"
#include "prom_metric.h"

Include dependency graph for prom_collector.h:

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

Go to the source code of this file.

Typedefs
typedef struct prom_collector	prom_collector_t
	A prom collector calls collect to prepare metrics and return them to the registry to which it is registered.
typedef prom_map_t *	prom_collect_fn(prom_collector_t *self)
	The function used to prepare and return all relevant metrics of the given collector ready for Prometheus exposition. More...
typedef void	prom_collector_free_data_fn(prom_collector_t *self)
	The function to use to cleanup and free custom data attached via prom_collector_data_set(). More...

Functions
prom_collector_t *	prom_collector_new (const char *name)
	Create a collector. More...
prom_collector_t *	ppc_new (const char *limits_path, const char *stat_path, pid_t pid, const char **label_keys, const char **label_vals)
	Create a prom collector which includes the default process metrics. More...
int	prom_collector_destroy (prom_collector_t *self)
	Destroy the given collector including all attached metrics. More...
int	prom_collector_destroy_generic (void *gen)
	Cast the given pointer to prom_collector_t and call prom_collector_destroy() with it. More...
void	prom_collector_free_generic (void *gen)
	Same as prom_collector_destroy_generic(), but drops any return codes.
int	prom_collector_add_metric (prom_collector_t *self, prom_metric_t *metric)
	Add the given metric to the given collector. More...
int	prom_collector_set_collect_fn (prom_collector_t *self, prom_collect_fn *fn)
	Set the function, which prepares (if needed) and returns all relevant metrics of the given collector ready for Prometheus exposition. More...
void *	prom_collector_data_set (prom_collector_t *self, void *data, prom_collector_free_data_fn *fn)
	Attach custom data to the given collector as well as the callback to use to clean it up. More...
void *	prom_collector_data_get (prom_collector_t *self)
	Get the pointer to the custom data attached to the given collector. More...
prom_map_t *	prom_collector_metrics_get (prom_collector_t *self)
	Get a map of all metrics of the given collector keyed by their names. More...

Detailed Description

A prom_collector is used to collect metrics.

Typedef Documentation

prom_collect_fn

typedef prom_map_t* prom_collect_fn(prom_collector_t *self)

The function used to prepare and return all relevant metrics of the given collector ready for Prometheus exposition.

If you use the default collector registry, this should not concern you. If you are using a custom collector, you may set this function on your collector to do additional work before returning the contained metrics.

Parameters

self	The collector with the relevant metrics.

Returns

The metrics to expose.

prom_collector_free_data_fn

typedef void prom_collector_free_data_fn(prom_collector_t *self)

The function to use to cleanup and free custom data attached via prom_collector_data_set().

Per default it gets called by prom_collector_destroy() right after the prom_collect_fn() has been set to NULL. The default implementation simply sets the pointer to the data to NULL, which may cause memory leaks.

Function Documentation

ppc_new()

prom_collector_t* ppc_new	(	const char *	limits_path,
		const char *	stat_path,
		pid_t	pid,
		const char **	label_keys,
		const char **	label_vals
	)

Create a prom collector which includes the default process metrics.

Parameters

limits_path	If NULL POSIX and OS specific will be used to determine limits. Otherwise, read the limits from the given file path - ususally used for testing, only.
stat_path	If NULL POSIX and OS specific will be used to determine the stats. Otherwise, read the stats from the given file path - ususally used for testing, only.
pid	If the given limits_path or stat_path is NULL, collect the data from the process with the given pid . If pid is < 1, the process id of the running process will be used.
label_keys	An arbitrary set of labels to assign to all metrics managed by the created collector. Use NULL for none.
label_vals	The values to use for the given label_keys. Same order as label_keys is required. Use NULL for none.

Returns

The new collector on success, NULL otherwise.

prom_collector_add_metric()

int prom_collector_add_metric	(	prom_collector_t *	self,
		prom_metric_t *	metric
	)

Add the given metric to the given collector.

It gets automatically destroyed when the given collector gets destroyed.

Parameters

self	Where to add the metric.
metric	Metric to add. NULL is allowed and gets silently ignored.

Returns

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

See also

prom_collector_destroy().

prom_collector_data_get()

void* prom_collector_data_get

(

prom_collector_t *

self

)

Get the pointer to the custom data attached to the given collector.

Parameters

self	The collector in question.

Returns

a pointer to custom data, which might be NULL.

prom_collector_data_set()

void* prom_collector_data_set	(	prom_collector_t *	self,
		void *	data,
		prom_collector_free_data_fn *	fn
	)

Attach custom data to the given collector as well as the callback to use to clean it up.

Parameters

self	Where to attach data and cleanup function.
data	A pointer to custom data to attach. It gets not used by the framework itself, just piggybacked to the collector as is.
fn	Function, which should be used to free/cleanup the given custom data. If not set or NULL, the default implementation will be used, which just sets the related pointer to NULL, which might cause memory leaks. It gets automagically called by prom_collector_destroy().

Returns

A pointer to the data currently attached to the collector or NULL if not yet set.

prom_collector_destroy()

int prom_collector_destroy

(

prom_collector_t *

self

)

Destroy the given collector including all attached metrics.

Parameters

self	collector to destroy.

Returns

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

Note

No matter what gets returned, you should never use any collector passed to this function but set it to NULL . Also remember, that per default all metrics of the given collector get freed via prom_gauge_destroy() or prom_counter_destroy() and should not be used anymore.

prom_collector_destroy_generic()

int prom_collector_destroy_generic

(

void *

gen

)

Cast the given pointer to prom_collector_t and call prom_collector_destroy() with it.

Parameters

gen	Collector to destroy.

Returns

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

prom_collector_metrics_get()

prom_map_t* prom_collector_metrics_get

(

prom_collector_t *

self

)

Get a map of all metrics of the given collector keyed by their names.

Per default this function will be used, if no collect function has been set.

Parameters

self	The collector in question.

See also

prom_collector_set_collect_fn()

prom_collector_new()

prom_collector_t* prom_collector_new

(

const char *

name

)

Create a collector.

Parameters

name	name of the collector.

Note

Name MUST NOT be default or process.

Returns

The new collector on success, NULL otherwise.

prom_collector_set_collect_fn()

int prom_collector_set_collect_fn	(	prom_collector_t *	self,
		prom_collect_fn *	fn
	)

Set the function, which prepares (if needed) and returns all relevant metrics of the given collector ready for Prometheus exposition.

Parameters

self	Collector containing the metrics.
fn	The function to repare and return the metrics.

Returns

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