res_prometheus.h File Reference

Asterisk Prometheus Metrics. More...

#include "asterisk/lock.h"
#include "asterisk/linkedlists.h"
#include "asterisk/stringfields.h"

Include dependency graph for res_prometheus.h:

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

Go to the source code of this file.

Data Structures
struct	prometheus_callback
	Defines a callback that will be invoked when the HTTP route is called. More...
struct	prometheus_general_config
	Prometheus general configuration. More...
struct	prometheus_label
	A label that further defines a metric. More...
struct	prometheus_metric
	An actual, honest to god, metric. More...
struct	prometheus_metrics_provider
	A function table for a metrics provider. More...

Macros
#define	PROMETHEUS_MAX_LABEL_LENGTH   128
	How long a label value can be.
#define	PROMETHEUS_MAX_LABELS   8
	How many labels a single metric can have.
#define	PROMETHEUS_MAX_NAME_LENGTH   64
	How long a label name can be.
#define	PROMETHEUS_MAX_VALUE_LENGTH   32
	How large of a value we can store.
#define	PROMETHEUS_METRIC_SET_LABEL(metric, label, n, v)
	Convenience macro for setting a label / value in a metric.
#define	PROMETHEUS_METRIC_STATIC_INITIALIZATION(mtype, n, h, cb)
	Convenience macro for initializing a metric on the stack.

Enumerations
enum	prometheus_metric_allocation_strategy { PROMETHEUS_METRIC_ALLOCD = 0 , PROMETHEUS_METRIC_MALLOCD }
	How the metric was allocated. More...
enum	prometheus_metric_type { PROMETHEUS_METRIC_COUNTER = 0 , PROMETHEUS_METRIC_GAUGE }
	Prometheus metric type. More...

Functions
int	prometheus_callback_register (struct prometheus_callback *callback)
void	prometheus_callback_unregister (struct prometheus_callback *callback)
	Remove a registered callback.
struct prometheus_metric *	prometheus_counter_create (const char *name, const char *help)
	Create a malloc'd counter metric.
struct prometheus_metric *	prometheus_gauge_create (const char *name, const char *help)
	Create a malloc'd gauge metric.
void *	prometheus_general_config_alloc (void)
	Allocate a new configuration object.
struct prometheus_general_config *	prometheus_general_config_get (void)
	Retrieve the current configuration of the module.
void	prometheus_general_config_set (struct prometheus_general_config *config)
	Set the configuration for the module.
void	prometheus_metric_free (struct prometheus_metric *metric)
	Destroy a metric and all its children.
int	prometheus_metric_register (struct prometheus_metric *metric)
int	prometheus_metric_registered_count (void)
void	prometheus_metric_to_string (struct prometheus_metric *metric, struct ast_str **output)
	Convert a metric (and its children) into Prometheus compatible text.
int	prometheus_metric_unregister (struct prometheus_metric *metric)
	Remove a registered metric.
void	prometheus_metrics_provider_register (const struct prometheus_metrics_provider *provider)
	Register a metrics provider.

Detailed Description

Asterisk Prometheus Metrics.

This module provides the base APIs and functionality for exposing a metrics route in Asterisk's HTTP server suitable for consumption by a Prometheus server. It does not provide any metrics itself.

Definition in file res_prometheus.h.

Macro Definition Documentation

PROMETHEUS_MAX_LABEL_LENGTH

#define PROMETHEUS_MAX_LABEL_LENGTH   128

How long a label value can be.

Definition at line 49 of file res_prometheus.h.

PROMETHEUS_MAX_LABELS

#define PROMETHEUS_MAX_LABELS   8

How many labels a single metric can have.

Definition at line 39 of file res_prometheus.h.

PROMETHEUS_MAX_NAME_LENGTH

#define PROMETHEUS_MAX_NAME_LENGTH   64

How long a label name can be.

Definition at line 44 of file res_prometheus.h.

PROMETHEUS_MAX_VALUE_LENGTH

#define PROMETHEUS_MAX_VALUE_LENGTH   32

How large of a value we can store.

Definition at line 54 of file res_prometheus.h.

PROMETHEUS_METRIC_SET_LABEL

#define PROMETHEUS_METRIC_SET_LABEL	(		metric,
			label,
			n,
			v
	)

Value:

    do { \
    ast_assert((label) < PROMETHEUS_MAX_LABELS); \
    ast_copy_string((metric)->labels[(label)].name, (n), sizeof((metric)->labels[(label)].name)); \
    ast_copy_string((metric)->labels[(label)].value, (v), sizeof((metric)->labels[(label)].value)); \
} while (0)

Convenience macro for setting a label / value in a metric.

When creating nested metrics, it's helpful to set their label after they have been declared but before they have been registered. This macro acts as a convenience function to set the labels properly on a declared metric.

Note

Setting labels after registration will lead to a "bad time"

Example Usage:

PROMETHEUS_METRIC_SET_LABEL(
   test_gauge_child_two, 0, "key_one", "value_two");
PROMETHEUS_METRIC_SET_LABEL(
   test_gauge_child_two, 1, "key_two", "value_two");

Parameters

metric	The metric to set the label on
label	Position of the label to set
n	Name of the label
v	Value of the label

Definition at line 317 of file res_prometheus.h.

                                                            { \
    ast_assert((label) < PROMETHEUS_MAX_LABELS); \
    ast_copy_string((metric)->labels[(label)].name, (n), sizeof((metric)->labels[(label)].name)); \
    ast_copy_string((metric)->labels[(label)].value, (v), sizeof((metric)->labels[(label)].value)); \
} while (0)

PROMETHEUS_METRIC_STATIC_INITIALIZATION

#define PROMETHEUS_METRIC_STATIC_INITIALIZATION	(		mtype,
			n,
			h,
			cb
	)

Convenience macro for initializing a metric on the stack.

When initializing a metric on the stack, various fields have to be provided to initialize the metric correctly. This macro can be used to simplify the process.

Example Usage:

struct prometheus_metric test_counter_one =
   PROMETHEUS_METRIC_STATIC_INITIALIZATION(
       PROMETHEUS_METRIC_COUNTER,
       "test_counter_one",
       "A test counter",
       NULL);
struct prometheus_metric test_counter_two =
       PROMETHEUS_METRIC_STATIC_INITIALIZATION(
       PROMETHEUS_METRIC_COUNTER,
       "test_counter_two",
       "A test counter",
       metric_values_get_counter_value_cb);

Parameters

mtype	The metric type. See prometheus_metric_type
n	Name of the metric
h	Help text for the metric
cb	Callback function. Optional; may be NULL

Definition at line 285 of file res_prometheus.h.

                                                                 { \
    .type = (mtype), \
    .allocation_strategy = PROMETHEUS_METRIC_ALLOCD, \
    .lock = AST_MUTEX_INIT_VALUE, \
    .name = (n), \
    .help = (h), \
    .children = AST_LIST_HEAD_NOLOCK_INIT_VALUE, \
    .get_metric_value = (cb), \
}

Enumeration Type Documentation

prometheus_metric_allocation_strategy

enum prometheus_metric_allocation_strategy

How the metric was allocated.

Note

Clearly, you don't want to get this wrong.

Enumerator
PROMETHEUS_METRIC_ALLOCD	The metric was allocated on the stack.
PROMETHEUS_METRIC_MALLOCD	The metric was allocated on the heap.

Definition at line 142 of file res_prometheus.h.

                                           {
    /*!
     * \brief The metric was allocated on the stack
     */
    PROMETHEUS_METRIC_ALLOCD = 0,
    /*!
     * \brief The metric was allocated on the heap
     */
    PROMETHEUS_METRIC_MALLOCD,
};

prometheus_metric_type

enum prometheus_metric_type

Prometheus metric type.

Note

Clearly, at some point, we should support summaries and histograms. As an initial implementation, counters / gauges give us quite a bit of functionality.

Enumerator
PROMETHEUS_METRIC_COUNTER	A metric whose value always goes up.
PROMETHEUS_METRIC_GAUGE	A metric whose value can bounce around like a jackrabbit.

Definition at line 126 of file res_prometheus.h.

                            {
    /*!
     * \brief A metric whose value always goes up
     */
    PROMETHEUS_METRIC_COUNTER = 0,
    /*!
     * \brief A metric whose value can bounce around like a jackrabbit
     */
    PROMETHEUS_METRIC_GAUGE,
};

Function Documentation

prometheus_callback_register()

int prometheus_callback_register

(

struct prometheus_callback *

callback

)

Register a metric callback

Parameters

callback

The callback to register

Return values

0	success
-1	error

Definition at line 594 of file res_prometheus.c.

{
    SCOPED_MUTEX(lock, &scrape_lock);
 
    if (!callback || !callback->callback_fn || ast_strlen_zero(callback->name)) {
        return -1;
    }
 
    AST_VECTOR_APPEND(&callbacks, callback);
 
    return 0;
}

References ast_strlen_zero(), AST_VECTOR_APPEND, callback(), callbacks, lock, SCOPED_MUTEX, and scrape_lock.

Referenced by AST_TEST_DEFINE(), bridge_metrics_init(), channel_metrics_init(), and endpoint_metrics_init().

prometheus_callback_unregister()

void prometheus_callback_unregister

(

struct prometheus_callback *

callback

)

Remove a registered callback.

Parameters

callback

The callback to unregister

Definition at line 607 of file res_prometheus.c.

{
    SCOPED_MUTEX(lock, &scrape_lock);
    int i;
 
    for (i = 0; i < AST_VECTOR_SIZE(&callbacks); i++) {
        struct prometheus_callback *entry = AST_VECTOR_GET(&callbacks, i);
 
        if (!strcmp(callback->name, entry->name)) {
            AST_VECTOR_REMOVE(&callbacks, i, 1);
            return;
        }
    }
}

References AST_VECTOR_GET, AST_VECTOR_REMOVE, AST_VECTOR_SIZE, callback(), callbacks, lock, prometheus_callback::name, SCOPED_MUTEX, and scrape_lock.

Referenced by AST_TEST_DEFINE(), bridge_metrics_unload_cb(), channel_metrics_unload_cb(), and endpoint_metrics_unload_cb().

prometheus_counter_create()

struct prometheus_metric * prometheus_counter_create	(	const char *	name,
		const char *	help
	)

Create a malloc'd counter metric.

Note

The metric must be registered after creation

Parameters

name	The name of the metric
help	Help text for the metric

Return values

prometheus_metric	on success
NULL	on error

Definition at line 511 of file res_prometheus.c.

{
    struct prometheus_metric *metric;
 
    metric = prometheus_metric_create(name, help);
    if (!metric) {
        return NULL;
    }
    metric->type = PROMETHEUS_METRIC_COUNTER;
 
    return metric;
}

References prometheus_metric::help, name, NULL, PROMETHEUS_METRIC_COUNTER, prometheus_metric_create(), and prometheus_metric::type.

Referenced by AST_TEST_DEFINE(), and AST_TEST_DEFINE().

prometheus_gauge_create()

struct prometheus_metric * prometheus_gauge_create	(	const char *	name,
		const char *	help
	)

Create a malloc'd gauge metric.

Note

The metric must be registered after creation

Parameters

name	The name of the metric
help	Help text for the metric

Return values

prometheus_metric	on success
NULL	on error

Definition at line 498 of file res_prometheus.c.

{
    struct prometheus_metric *metric;
 
    metric = prometheus_metric_create(name, help);
    if (!metric) {
        return NULL;
    }
    metric->type = PROMETHEUS_METRIC_GAUGE;
 
    return metric;
}

References prometheus_metric::help, name, NULL, prometheus_metric_create(), PROMETHEUS_METRIC_GAUGE, and prometheus_metric::type.

Referenced by AST_TEST_DEFINE(), and AST_TEST_DEFINE().

prometheus_general_config_alloc()

void * prometheus_general_config_alloc

(

void

)

Allocate a new configuration object.

The returned object is an AO2 ref counted object

Return values

NULL	on error
config	on success

Definition at line 792 of file res_prometheus.c.

{
    struct prometheus_general_config *config;
 
    config = ao2_alloc(sizeof(*config), prometheus_general_config_dtor);
    if (!config || ast_string_field_init(config, 32)) {
        return NULL;
    }
 
    return config;
}

References ao2_alloc, ast_string_field_init, config, NULL, and prometheus_general_config_dtor().

Referenced by config_alloc(), and module_config_alloc().

prometheus_general_config_get()

struct prometheus_general_config * prometheus_general_config_get

(

void

)

Retrieve the current configuration of the module.

config is an AO2 ref counted object

Note

This should primarily be done for testing purposes.

Return values

NULL	on error
config	on success

Definition at line 804 of file res_prometheus.c.

{
    RAII_VAR(struct module_config *, mod_cfg, ao2_global_obj_ref(global_config), ao2_cleanup);
 
    if (!mod_cfg) {
        return NULL;
    }
    ao2_bump(mod_cfg->general);
 
    return mod_cfg->general;
}

References ao2_bump, ao2_cleanup, ao2_global_obj_ref, NULL, and RAII_VAR.

Referenced by bridges_scrape_cb(), channels_scrape_cb(), prometheus_show_status(), reload_module(), and test_init_cb().

prometheus_general_config_set()

void prometheus_general_config_set

(

struct prometheus_general_config *

config

)

Set the configuration for the module.

This is not a ref-stealing function. The reference count to config will be incremented as a result of calling this method.

Note

This should primarily be done for testing purposes

Definition at line 816 of file res_prometheus.c.

{
    RAII_VAR(struct module_config *, mod_cfg, ao2_global_obj_ref(global_config), ao2_cleanup);
 
    if (!mod_cfg) {
        return;
    }
    ao2_replace(mod_cfg->general, config);
    prometheus_config_post_apply();
}

References ao2_cleanup, ao2_global_obj_ref, ao2_replace, config, prometheus_config_post_apply(), and RAII_VAR.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), test_cleanup_cb(), and test_init_cb().

prometheus_metric_free()

void prometheus_metric_free

(

struct prometheus_metric *

metric

)

Destroy a metric and all its children.

Note

If you still want the children, make sure you remove the head of the children list first.

Parameters

metric

The metric to destroy

Definition at line 452 of file res_prometheus.c.

{
    struct prometheus_metric *child;
 
    if (!metric) {
        return;
    }
 
    while ((child = AST_LIST_REMOVE_HEAD(&metric->children, entry))) {
        prometheus_metric_free(child);
    }
    ast_mutex_destroy(&metric->lock);
 
    if (metric->allocation_strategy == PROMETHEUS_METRIC_ALLOCD) {
        return;
    } else if (metric->allocation_strategy == PROMETHEUS_METRIC_MALLOCD) {
        ast_free(metric);
    }
}

References prometheus_metric::allocation_strategy, ast_free, AST_LIST_REMOVE_HEAD, ast_mutex_destroy, prometheus_metric::children, prometheus_metric::entry, prometheus_metric::lock, PROMETHEUS_METRIC_ALLOCD, prometheus_metric_free(), and PROMETHEUS_METRIC_MALLOCD.

Referenced by AST_TEST_DEFINE(), prometheus_metric_free(), prometheus_metric_free_wrapper(), prometheus_metric_unregister(), and unload_module().

prometheus_metric_register()

int prometheus_metric_register

(

struct prometheus_metric *

metric

)

Register a metric for collection

Parameters

metric

The metric to register

Return values

0	success
-1	error

Definition at line 347 of file res_prometheus.c.

{
    SCOPED_MUTEX(lock, &scrape_lock);
    int i;
 
    if (!metric) {
        return -1;
    }
 
    for (i = 0; i < AST_VECTOR_SIZE(&metrics); i++) {
        struct prometheus_metric *existing = AST_VECTOR_GET(&metrics, i);
        struct prometheus_metric *child;
 
        if (prometheus_metric_cmp(existing, metric)) {
            ast_log(AST_LOG_NOTICE,
                "Refusing registration of existing Prometheus metric: %s\n",
                metric->name);
            return -1;
        }
 
        AST_LIST_TRAVERSE(&existing->children, child, entry) {
            if (prometheus_metric_cmp(child, metric)) {
                ast_log(AST_LOG_NOTICE,
                    "Refusing registration of existing Prometheus metric: %s\n",
                    metric->name);
                return -1;
            }
        }
 
        if (!strcmp(metric->name, existing->name)) {
            ast_debug(3, "Nesting metric '%s' as child (%p) under existing (%p)\n",
                metric->name, metric, existing);
            AST_LIST_INSERT_TAIL(&existing->children, metric, entry);
            return 0;
        }
    }
 
    ast_debug(3, "Tracking new root metric '%s'\n", metric->name);
    if (AST_VECTOR_APPEND(&metrics, metric)) {
        ast_log(AST_LOG_WARNING, "Failed to grow vector to make room for Prometheus metric: %s\n",
            metric->name);
        return -1;
    }
 
    return 0;
}

References ast_debug, AST_LIST_INSERT_TAIL, AST_LIST_TRAVERSE, ast_log, AST_LOG_NOTICE, AST_LOG_WARNING, AST_VECTOR_APPEND, AST_VECTOR_GET, AST_VECTOR_SIZE, prometheus_metric::children, prometheus_metric::entry, lock, metrics, prometheus_metric::name, prometheus_metric_cmp(), SCOPED_MUTEX, and scrape_lock.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), and prometheus_config_post_apply().

prometheus_metric_registered_count()

int prometheus_metric_registered_count

(

void

)

The current number of registered metrics

Return values

The	current number of registered metrics

Definition at line 340 of file res_prometheus.c.

{
    SCOPED_MUTEX(lock, &scrape_lock);
 
    return AST_VECTOR_SIZE(&metrics);
}

References AST_VECTOR_SIZE, lock, metrics, SCOPED_MUTEX, and scrape_lock.

Referenced by AST_TEST_DEFINE().

prometheus_metric_to_string()

void prometheus_metric_to_string	(	struct prometheus_metric *	metric,
		struct ast_str **	output
	)

Convert a metric (and its children) into Prometheus compatible text.

Parameters

	metric	The metric to convert to a string
[out]	output	The ast_str string to populate with the metric(s)

Definition at line 580 of file res_prometheus.c.

{
    struct prometheus_metric *child;
 
    ast_str_append(output, 0, "# HELP %s %s\n", metric->name, metric->help);
    ast_str_append(output, 0, "# TYPE %s %s\n", metric->name,
        prometheus_metric_type_to_string(metric->type));
    prometheus_metric_full_to_string(metric, output);
    AST_LIST_TRAVERSE(&metric->children, child, entry) {
        prometheus_metric_full_to_string(child, output);
    }
}

References AST_LIST_TRAVERSE, ast_str_append(), prometheus_metric::children, prometheus_metric::entry, prometheus_metric::help, prometheus_metric::name, prometheus_metric_full_to_string(), prometheus_metric_type_to_string(), and prometheus_metric::type.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), bridges_scrape_cb(), channels_scrape_cb(), endpoints_scrape_cb(), http_callback(), prometheus_metric_callback(), and scrape_metrics().

prometheus_metric_unregister()

int prometheus_metric_unregister

(

struct prometheus_metric *

metric

)

Remove a registered metric.

Parameters

metric

The metric to unregister

Note

Unregistering also destroys the metric, if found

Return values

0	The metric was found, unregistered, and disposed of
-1	The metric was not found

Definition at line 394 of file res_prometheus.c.

{
    if (!metric) {
        return -1;
    }
 
    {
        SCOPED_MUTEX(lock, &scrape_lock);
        int i;
 
        ast_debug(3, "Removing metric '%s'\n", metric->name);
        for (i = 0; i < AST_VECTOR_SIZE(&metrics); i++) {
            struct prometheus_metric *existing = AST_VECTOR_GET(&metrics, i);
 
            /*
             * If this is a complete match, remove the matching metric
             * and place its children back into the list
             */
            if (prometheus_metric_cmp(existing, metric)) {
                struct prometheus_metric *root;
 
                AST_VECTOR_REMOVE(&metrics, i, 1);
                root = AST_LIST_REMOVE_HEAD(&existing->children, entry);
                if (root) {
                    struct prometheus_metric *child;
                    AST_LIST_TRAVERSE_SAFE_BEGIN(&existing->children, child, entry) {
                        AST_LIST_REMOVE_CURRENT(entry);
                        AST_LIST_INSERT_TAIL(&root->children, child, entry);
                    }
                    AST_LIST_TRAVERSE_SAFE_END;
                    AST_VECTOR_INSERT_AT(&metrics, i, root);
                }
                prometheus_metric_free(existing);
                return 0;
            }
 
            /*
             * Name match, but labels don't match. Find the matching entry with
             * labels and remove it along with all of its children
             */
            if (!strcmp(existing->name, metric->name)) {
                struct prometheus_metric *child;
 
                AST_LIST_TRAVERSE_SAFE_BEGIN(&existing->children, child, entry) {
                    if (prometheus_metric_cmp(child, metric)) {
                        AST_LIST_REMOVE_CURRENT(entry);
                        prometheus_metric_free(child);
                        return 0;
                    }
                }
                AST_LIST_TRAVERSE_SAFE_END;
            }
        }
    }
 
    return -1;
}

References ast_debug, AST_LIST_INSERT_TAIL, AST_LIST_REMOVE_CURRENT, AST_LIST_REMOVE_HEAD, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_VECTOR_GET, AST_VECTOR_INSERT_AT, AST_VECTOR_REMOVE, AST_VECTOR_SIZE, prometheus_metric::children, prometheus_metric::entry, lock, metrics, prometheus_metric::name, prometheus_metric_cmp(), prometheus_metric_free(), SCOPED_MUTEX, and scrape_lock.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), prometheus_config_post_apply(), and prometheus_metric_free_wrapper().

prometheus_metrics_provider_register()

void prometheus_metrics_provider_register

(

const struct prometheus_metrics_provider *

provider

)

Register a metrics provider.

Parameters

provider

The provider function table to register

Definition at line 937 of file res_prometheus.c.

{
    AST_VECTOR_APPEND(&providers, provider);
}

References AST_VECTOR_APPEND, provider, and providers.

Referenced by bridge_metrics_init(), channel_metrics_init(), cli_init(), endpoint_metrics_init(), and pjsip_outbound_registration_metrics_init().