prom/include/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.
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().
Functions
prom_collector_t *	prom_collector_new (const char *name)
	Create a collector.
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.
int	prom_collector_destroy (prom_collector_t *self)
	Destroy the given collector including all attached metrics.
int	prom_collector_destroy_generic (void *gen)
	Cast the given pointer to prom_collector_t and call prom_collector_destroy() with it.
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.
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.
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.
void *	prom_collector_data_get (prom_collector_t *self)
	Get the pointer to the custom data attached to the given collector.
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.

---

Detailed Description

A prom_collector is used to collect metrics.

---

Typedef Documentation

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.

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

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.

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().

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.

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.

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.

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_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_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.

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.