prom_gauge.h File Reference

https://prometheus.io/docs/concepts/metric_types/#gauge More...

#include <stdlib.h>
#include "prom_metric.h"

Include dependency graph for prom_gauge.h:

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

Go to the source code of this file.

Typedefs
typedef prom_metric_t	prom_gauge_t
	Prometheus metric: gauge. More...

Functions
prom_gauge_t *	prom_gauge_new (const char *name, const char *help, size_t label_key_count, const char **label_keys)
	Construct a new metric of type gauge (or short: gauge). More...
int	prom_gauge_destroy (prom_gauge_t *self)
	Destroys the given gauge. More...
int	prom_gauge_inc (prom_gauge_t *self, const char **label_values)
	Increment the given gauge by 1. More...
int	prom_gauge_dec (prom_gauge_t *self, const char **label_values)
	Decrement the given gauge by 1. More...
int	prom_gauge_add (prom_gauge_t *self, double r_value, const char **label_values)
	Add the given value to the given gauge. More...
int	prom_gauge_sub (prom_gauge_t *self, double r_value, const char **label_values)
	Subtract the value to the given gauge. More...
int	prom_gauge_set (prom_gauge_t *self, double r_value, const char **label_values)
	Set the given gauge to the given value. More...

Detailed Description

https://prometheus.io/docs/concepts/metric_types/#gauge

Typedef Documentation

prom_gauge_t

typedef prom_metric_t prom_gauge_t

Prometheus metric: gauge.

References

• See https://prometheus.io/docs/concepts/metric_types/#gauge

Function Documentation

prom_gauge_add()

int prom_gauge_add	(	prom_gauge_t *	self,
		double	r_value,
		const char **	label_values
	)

Add the given value to the given gauge.

Parameters

self	Where to add the given value.
r_value	Value to add. MUST be >= 0.
label_values	The label values associated with the gauge sample being updated. The number of labels must match the value passed as label_key_count in the gauge's constructor. If no label values are necessary, pass NULL. Otherwise, it may be convenient to pass this value as a literal.

Returns

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

Example

// An example with labels prom_gauge_add(foo_gauge 22, (const char**) { "bar", "bang" });

// An example without labels prom_gauge_add(foo_gauge, 22, NULL);

prom_gauge_dec()

int prom_gauge_dec	(	prom_gauge_t *	self,
		const char **	label_values
	)

Decrement the given gauge by 1.

Parameters

self	Gauge to decrement.
label_values	The label values associated with the gauge sample being updated. The number of labels must match the value passed as label_key_count in the gauge's constructor. If no label values are necessary, pass NULL. Otherwise, it may be convenient to pass this value as a literal.

Returns

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

Example

// An example with labels prom_gauge_dec(foo_gauge, (const char**) { "bar", "bang" });

// An example without labels prom_gauge_dec(foo_gauge, NULL);

prom_gauge_destroy()

int prom_gauge_destroy

(

prom_gauge_t *

self

)

Destroys the given gauge.

Parameters

self	Gauge to destroy.

Returns

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

Note

No matter what gets returned, you should never use any metric passed to this function but set it to NULL .

prom_gauge_inc()

int prom_gauge_inc	(	prom_gauge_t *	self,
		const char **	label_values
	)

Increment the given gauge by 1.

Parameters

self	Gauge to increment.
label_values	The label values associated with the gauge sample being updated. The number of labels must match the value passed as label_key_count in the gauge's constructor. If no label values are necessary, pass NULL. Otherwise, it may be convenient to pass this value as a literal.

Returns

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

Example

// An example with labels prom_gauge_inc(foo_gauge, (const char**) { "bar", "bang" });

// An example without labels prom_gauge_inc(foo_gauge, NULL);

prom_gauge_new()

prom_gauge_t* prom_gauge_new	(	const char *	name,
		const char *	help,
		size_t	label_key_count,
		const char **	label_keys
	)

Construct a new metric of type gauge (or short: gauge).

Parameters

name	Name of the gauge.
help	Short gauge description.
label_key_count	The number of labels associated with the given gauge. Pass 0 if the gauge does not require labels.
label_keys	A collection of label keys. The number of keys MUST match the value passed as label_key_count. If no labels are required, pass NULL. Otherwise, it may be convenient to pass this value as a literal.

Returns

The new gauge on success, NULL otherwise.

// An example with labels prom_gauge_new("foo", "foo is a gauge with labels", 2, (const char**) { "one", "two" });

// An example without labels prom_gauge_new("foo", "foo is a gauge without labels", 0, NULL);

prom_gauge_set()

int prom_gauge_set	(	prom_gauge_t *	self,
		double	r_value,
		const char **	label_values
	)

Set the given gauge to the given value.

Parameters

self	Where to set the given value.
r_value	Value to set (which might be < 0).
label_values	The label values associated with the gauge sample being updated. The number of labels must match the value passed as label_key_count in the gauge's constructor. If no label values are necessary, pass NULL. Otherwise, it may be convenient to pass this value as a literal.

Returns

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

Example

// An example with labels prom_gauge_set(foo_gauge 22, (const char**) { "bar", "bang" });

// An example without labels prom_gauge_set(foo_gauge, 22, NULL);

prom_gauge_sub()

int prom_gauge_sub	(	prom_gauge_t *	self,
		double	r_value,
		const char **	label_values
	)

Subtract the value to the given gauge.

Parameters

self	Where to substract the given value.
r_value	Value to substract (which might be < 0).
label_values	The label values associated with the gauge sample being updated. The number of labels must match the value passed as label_key_count in the gauge's constructor. If no label values are necessary, pass NULL. Otherwise, it may be convenient to pass this value as a literal.

Returns

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

Example

// An example with labels prom_gauge_sub(foo_gauge 22, (const char**) { "bar", "bang" });

// An example without labels prom_gauge_sub(foo_gauge, 22, NULL);