res_prometheus.c File Reference

Core Prometheus metrics API. More...

#include "asterisk.h"
#include "asterisk/module.h"
#include "asterisk/vector.h"
#include "asterisk/http.h"
#include "asterisk/config_options.h"
#include "asterisk/ast_version.h"
#include "asterisk/buildinfo.h"
#include "asterisk/res_prometheus.h"
#include "prometheus/prometheus_internal.h"

Include dependency graph for res_prometheus.c:

Go to the source code of this file.

Macros
#define	AST_MODULE_SELF_SYM   __internal_res_prometheus_self
#define	CORE_LAST_RELOAD_HELP   "Time since last Asterisk reload in seconds."
#define	CORE_METRICS_SCRAPE_TIME_HELP   "Total time taken to collect metrics, in milliseconds"
#define	CORE_PROPERTIES_HELP   "Asterisk instance properties. The value of this will always be 1."
#define	CORE_UPTIME_HELP   "Asterisk instance uptime in seconds."
#define	METRIC_CORE_PROPS_ARRAY_INDEX   0

Functions
struct ast_module *	__internal_res_prometheus_self (void)
static void	__reg_module (void)
static void	__unreg_module (void)
static	AO2_GLOBAL_OBJ_STATIC (global_config)
	The module configuration container. More...
	AST_VECTOR (struct prometheus_metric *)
	The actual module config. More...
	CONFIG_INFO_STANDARD (cfg_info, global_config, module_config_alloc,.files=ACO_FILES(&prometheus_conf),.pre_apply_config=prometheus_config_pre_apply,.post_apply_config=prometheus_config_post_apply,)
	Register information about the configs being processed by this module. More...
static void	get_core_uptime_cb (struct prometheus_metric *metric)
static void	get_last_reload_cb (struct prometheus_metric *metric)
static int	http_callback (struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers)
static int	load_module (void)
static void *	module_config_alloc (void)
	Module config constructor. More...
static void	module_config_dtor (void *obj)
	Configuration object destructor. More...
int	prometheus_callback_register (struct prometheus_callback *callback)
void	prometheus_callback_unregister (struct prometheus_callback *callback)
	Remove a registered callback. More...
static void	prometheus_config_post_apply (void)
	Post-apply callback for the config framework. More...
static int	prometheus_config_pre_apply (void)
	Pre-apply callback for the config framework. More...
struct prometheus_metric *	prometheus_counter_create (const char *name, const char *help)
	Create a malloc'd counter metric. More...
struct prometheus_metric *	prometheus_gauge_create (const char *name, const char *help)
	Create a malloc'd gauge metric. More...
void *	prometheus_general_config_alloc (void)
	Allocate a new configuration object. More...
static void	prometheus_general_config_dtor (void *obj)
struct prometheus_general_config *	prometheus_general_config_get (void)
	Retrieve the current configuration of the module. More...
void	prometheus_general_config_set (struct prometheus_general_config *config)
	Set the configuration for the module. More...
int64_t	prometheus_last_scrape_duration_get (void)
	Retrieve the amount of time it took to perform the last scrape. More...
struct timeval	prometheus_last_scrape_time_get (void)
	Retrieve the timestamp when the last scrape occurred. More...
static int	prometheus_metric_cmp (struct prometheus_metric *left, struct prometheus_metric *right)
static struct prometheus_metric *	prometheus_metric_create (const char *name, const char *help)
void	prometheus_metric_free (struct prometheus_metric *metric)
	Destroy a metric and all its children. More...
static void	prometheus_metric_full_to_string (struct prometheus_metric *metric, struct ast_str **output)
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. More...
static const char *	prometheus_metric_type_to_string (enum prometheus_metric_type type)
int	prometheus_metric_unregister (struct prometheus_metric *metric)
	Remove a registered metric. More...
void	prometheus_metrics_provider_register (const struct prometheus_metrics_provider *provider)
	Register a metrics provider. More...
struct ast_str *	prometheus_scrape_to_string (void)
	Get the raw output of what a scrape would produce. More...
static int	reload_module (void)
static void	scrape_metrics (struct ast_str **response)
static int	unload_module (void)

Variables
static struct ast_module_info	__mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Asterisk Prometheus Module" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_EXTENDED, .load = load_module, .unload = unload_module, .reload = reload_module, .load_pri = AST_MODPRI_DEFAULT, #ifdef 1 .requires = "res_pjsip", #endif }
static const struct ast_module_info *	ast_module_info = &__mod_info
static struct prometheus_metric	core_metrics []
	Core metrics to scrape. More...
static struct prometheus_metric	core_scrape_metric
	The scrape duration metric. More...
static struct aco_type	global_option
struct aco_type *	global_options [] = ACO_TYPES(&global_option)
struct aco_file	prometheus_conf
static struct ast_http_uri	prometheus_uri
static ast_mutex_t	scrape_lock = { PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP , NULL, {1, 0} }
	Lock that protects data structures during an HTTP scrape. More...

Detailed Description

Core Prometheus metrics API.

Author

Matt Jordan mjord.nosp@m.an@d.nosp@m.igium.nosp@m..com

Definition in file res_prometheus.c.

Macro Definition Documentation

AST_MODULE_SELF_SYM

#define AST_MODULE_SELF_SYM   __internal_res_prometheus_self

Definition at line 121 of file res_prometheus.c.

CORE_LAST_RELOAD_HELP

#define CORE_LAST_RELOAD_HELP   "Time since last Asterisk reload in seconds."

Definition at line 184 of file res_prometheus.c.

CORE_METRICS_SCRAPE_TIME_HELP

#define CORE_METRICS_SCRAPE_TIME_HELP   "Total time taken to collect metrics, in milliseconds"

Definition at line 186 of file res_prometheus.c.

CORE_PROPERTIES_HELP

#define CORE_PROPERTIES_HELP   "Asterisk instance properties. The value of this will always be 1."

Definition at line 180 of file res_prometheus.c.

CORE_UPTIME_HELP

#define CORE_UPTIME_HELP   "Asterisk instance uptime in seconds."

Definition at line 182 of file res_prometheus.c.

METRIC_CORE_PROPS_ARRAY_INDEX

#define METRIC_CORE_PROPS_ARRAY_INDEX   0

Definition at line 220 of file res_prometheus.c.

Referenced by prometheus_config_post_apply().

Function Documentation

__internal_res_prometheus_self()

struct ast_module* __internal_res_prometheus_self

(

void

)

Definition at line 1008 of file res_prometheus.c.

__reg_module()

static void __reg_module ( void  )

static

Definition at line 1008 of file res_prometheus.c.

__unreg_module()

static void __unreg_module ( void  )

static

Definition at line 1008 of file res_prometheus.c.

AO2_GLOBAL_OBJ_STATIC()

static AO2_GLOBAL_OBJ_STATIC ( global_config  )

static

The module configuration container.

AST_VECTOR()

AST_VECTOR

(

struct prometheus_metric *

)

The actual module config.

General settings

Definition at line 138 of file res_prometheus.c.

                     {
   /*! \brief General settings */
   struct prometheus_general_config *general;
};

CONFIG_INFO_STANDARD()

CONFIG_INFO_STANDARD	(	cfg_info	,
		global_config	,
		module_config_alloc	,
		.	files = ACO_FILES(&prometheus_conf),
		.	pre_apply_config = prometheus_config_pre_apply,
		.	post_apply_config = prometheus_config_post_apply
	)

Register information about the configs being processed by this module.

get_core_uptime_cb()

static void get_core_uptime_cb ( struct prometheus_metric *  metric )

static

Definition at line 188 of file res_prometheus.c.

References ast_startuptime, ast_tvdiff_sec(), ast_tvnow(), and prometheus_metric::value.

{
   struct timeval now = ast_tvnow();
   int64_t duration = ast_tvdiff_sec(now, ast_startuptime);

   snprintf(metric->value, sizeof(metric->value), "%" PRIu64, duration);
}

get_last_reload_cb()

static void get_last_reload_cb ( struct prometheus_metric *  metric )

static

Definition at line 196 of file res_prometheus.c.

References ast_lastreloadtime, ast_tvdiff_sec(), ast_tvnow(), and prometheus_metric::value.

{
   struct timeval now = ast_tvnow();
   int64_t duration = ast_tvdiff_sec(now, ast_lastreloadtime);

   snprintf(metric->value, sizeof(metric->value), "%" PRIu64, duration);
}

http_callback()

static int http_callback ( struct ast_tcptls_session_instance *  ser, const struct ast_http_uri *  urih, const char *  uri, enum ast_http_method  method, struct ast_variable *  get_params, struct ast_variable *  headers  )

static

Definition at line 593 of file res_prometheus.c.

References ao2_cleanup, ao2_global_obj_ref, ao2_ref, ast_debug, ast_free, ast_http_get_auth(), ast_http_send(), ast_mutex_lock, ast_mutex_unlock, ast_str_append(), ast_str_create, ast_strlen_zero, ast_tvdiff_ms(), ast_tvnow(), NULL, ast_http_auth::password, prometheus_metric_to_string(), RAII_VAR, scrape_lock, scrape_metrics(), ast_http_auth::userid, and prometheus_metric::value.

{
   RAII_VAR(struct module_config *, mod_cfg, ao2_global_obj_ref(global_config), ao2_cleanup);
   struct ast_str *response = NULL;
   struct timeval start;
   struct timeval end;

   /* If there is no module config or we're not enabled, we can't handle requests */
   if (!mod_cfg || !mod_cfg->general->enabled) {
      goto err503;
   }

   if (!ast_strlen_zero(mod_cfg->general->auth_username)) {
      struct ast_http_auth *http_auth;

      http_auth = ast_http_get_auth(headers);
      if (!http_auth) {
         goto err401;
      }

      if (strcmp(http_auth->userid, mod_cfg->general->auth_username)) {
         ast_debug(5, "Invalid username provided for auth request: %s\n", http_auth->userid);
         ao2_ref(http_auth, -1);
         goto err401;
      }

      if (strcmp(http_auth->password, mod_cfg->general->auth_password)) {
         ast_debug(5, "Invalid password provided for auth request: %s\n", http_auth->password);
         ao2_ref(http_auth, -1);
         goto err401;
      }

      ao2_ref(http_auth, -1);
   }

   response = ast_str_create(512);
   if (!response) {
      goto err500;
   }

   start = ast_tvnow();

   ast_mutex_lock(&scrape_lock);

   last_scrape = start;
   scrape_metrics(&response);

   if (mod_cfg->general->core_metrics_enabled) {
      int64_t duration;

      end = ast_tvnow();
      duration = ast_tvdiff_ms(end, start);
      snprintf(core_scrape_metric.value,
         sizeof(core_scrape_metric.value),
         "%" PRIu64,
         duration);
      prometheus_metric_to_string(&core_scrape_metric, &response);
   }
   ast_mutex_unlock(&scrape_lock);

   ast_http_send(ser, method, 200, "OK", NULL, response, 0, 0);

   return 0;

err401:
   {
      struct ast_str *auth_challenge_headers;

      auth_challenge_headers = ast_str_create(128);
      if (!auth_challenge_headers) {
         goto err500;
      }
      ast_str_append(&auth_challenge_headers, 0,
         "WWW-Authenticate: Basic realm=\"%s\"\r\n",
         mod_cfg->general->auth_realm);
      /* ast_http_send takes ownership of the ast_str */
      ast_http_send(ser, method, 401, "Unauthorized", auth_challenge_headers, NULL, 0, 1);
   }
   ast_free(response);
   return 0;
err503:
   ast_http_send(ser, method, 503, "Service Unavailable", NULL, NULL, 0, 1);
   ast_free(response);
   return 0;
err500:
   ast_http_send(ser, method, 500, "Server Error", NULL, NULL, 0, 1);
   ast_free(response);
   return 0;
}

load_module()

static int load_module ( void  )

static

Definition at line 945 of file res_prometheus.c.

References ACO_EXACT, aco_info_destroy(), aco_info_init(), aco_option_register, aco_process_config(), ACO_PROCESS_ERROR, ast_http_uri_link(), ast_http_uri_unlink(), AST_MODFLAG_GLOBAL_SYMBOLS, AST_MODFLAG_LOAD_ORDER, AST_MODPRI_DEFAULT, AST_MODULE_INFO(), AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, AST_MODULE_SUPPORT_EXTENDED, AST_VECTOR_FREE, AST_VECTOR_INIT, ASTERISK_GPL_KEY, bridge_metrics_init(), channel_metrics_init(), cleanup(), cli_init(), enabled, endpoint_metrics_init(), FLDSET, HAVE_PJPROJECT, lock, OPT_BOOL_T, OPT_STRINGFIELD_T, pjsip_outbound_registration_metrics_init(), providers, reload(), reload_module(), SCOPED_MUTEX, scrape_lock, STRFLDSET, and unload_module().

{
   SCOPED_MUTEX(lock, &scrape_lock);

   if (AST_VECTOR_INIT(&metrics, 64)) {
      goto cleanup;
   }

   if (AST_VECTOR_INIT(&callbacks, 8)) {
      goto cleanup;
   }

   if (AST_VECTOR_INIT(&providers, 8)) {
      goto cleanup;
   }

   if (aco_info_init(&cfg_info)) {
      goto cleanup;
   }
   aco_option_register(&cfg_info, "enabled", ACO_EXACT, global_options, "no", OPT_BOOL_T, 1, FLDSET(struct prometheus_general_config, enabled));
   aco_option_register(&cfg_info, "core_metrics_enabled", ACO_EXACT, global_options, "yes", OPT_BOOL_T, 1, FLDSET(struct prometheus_general_config, core_metrics_enabled));
   aco_option_register(&cfg_info, "uri", ACO_EXACT, global_options, "", OPT_STRINGFIELD_T, 1, STRFLDSET(struct prometheus_general_config, uri));
   aco_option_register(&cfg_info, "auth_username", ACO_EXACT, global_options, "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct prometheus_general_config, auth_username));
   aco_option_register(&cfg_info, "auth_password", ACO_EXACT, global_options, "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct prometheus_general_config, auth_password));
   aco_option_register(&cfg_info, "auth_realm", ACO_EXACT, global_options, "Asterisk Prometheus Metrics", OPT_STRINGFIELD_T, 0, STRFLDSET(struct prometheus_general_config, auth_realm));
   if (aco_process_config(&cfg_info, 0) == ACO_PROCESS_ERROR) {
      goto cleanup;
   }

   if (cli_init()
      || channel_metrics_init()
      || endpoint_metrics_init()
      || bridge_metrics_init()
      || pjsip_outbound_registration_metrics_init()) {
      goto cleanup;
   }

   if (ast_http_uri_link(&prometheus_uri)) {
      goto cleanup;
   }

   return AST_MODULE_LOAD_SUCCESS;

cleanup:
   ast_http_uri_unlink(&prometheus_uri);
   aco_info_destroy(&cfg_info);
   AST_VECTOR_FREE(&metrics);
   AST_VECTOR_FREE(&callbacks);
   AST_VECTOR_FREE(&providers);

   return AST_MODULE_LOAD_DECLINE;
}

module_config_alloc()

static void * module_config_alloc ( void  )

static

Module config constructor.

Definition at line 773 of file res_prometheus.c.

References ao2_alloc, ao2_ref, config, module_config::general, module_config_dtor(), NULL, and prometheus_general_config_alloc().

{
   struct module_config *config;

   config = ao2_alloc(sizeof(*config), module_config_dtor);
   if (!config) {
      return NULL;
   }

   config->general = prometheus_general_config_alloc();
   if (!config->general) {
      ao2_ref(config, -1);
      config = NULL;
   }

   return config;
}

module_config_dtor()

static void module_config_dtor ( void *  obj )

static

Configuration object destructor.

Definition at line 763 of file res_prometheus.c.

References ao2_ref, config, and module_config::general.

Referenced by module_config_alloc().

{
   struct module_config *config = obj;

   if (config->general) {
      ao2_ref(config->general, -1);
   }
}

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 535 of file res_prometheus.c.

References ast_strlen_zero, AST_VECTOR_APPEND, prometheus_callback::callback_fn, lock, prometheus_callback::name, SCOPED_MUTEX, and scrape_lock.

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

{
   SCOPED_MUTEX(lock, &scrape_lock);

   if (!callback || !callback->callback_fn || ast_strlen_zero(callback->name)) {
      return -1;
   }

   AST_VECTOR_APPEND(&callbacks, callback);

   return 0;
}

prometheus_callback_unregister()

void prometheus_callback_unregister

(

struct prometheus_callback *

callback

)

Remove a registered callback.

Parameters

callback

The callback to unregister

Definition at line 548 of file res_prometheus.c.

References AST_VECTOR_GET, AST_VECTOR_REMOVE, AST_VECTOR_SIZE, 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().

{
   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;
      }
   }
}

prometheus_config_post_apply()

static void prometheus_config_post_apply ( void  )

static

Post-apply callback for the config framework.

This sets any run-time information derived from the configuration

Definition at line 827 of file res_prometheus.c.

References ao2_cleanup, ao2_global_obj_ref, ARRAY_LEN, ast_build_date, ast_build_hostname, ast_build_kernel, ast_build_os, ast_eid_default, ast_eid_to_str(), ast_get_build_opts(), ast_get_version(), METRIC_CORE_PROPS_ARRAY_INDEX, prometheus_metric_register(), PROMETHEUS_METRIC_SET_LABEL, prometheus_metric_unregister(), RAII_VAR, ast_http_uri::uri, and value.

Referenced by prometheus_general_config_set().

{
   RAII_VAR(struct module_config *, mod_cfg, ao2_global_obj_ref(global_config), ao2_cleanup);
   int i;

   /* We can get away with this as the lifetime of the URI
    * registered with the HTTP core is contained within
    * the lifetime of the module configuration
    */
   prometheus_uri.uri = mod_cfg->general->uri;

   /* Re-register the core metrics */
   for (i = 0; i < ARRAY_LEN(core_metrics); i++) {
      prometheus_metric_unregister(&core_metrics[i]);
   }
   if (mod_cfg->general->core_metrics_enabled) {
      char eid_str[32];
      ast_eid_to_str(eid_str, sizeof(eid_str), &ast_eid_default);

      PROMETHEUS_METRIC_SET_LABEL(&core_scrape_metric, 0, "eid", eid_str);

      PROMETHEUS_METRIC_SET_LABEL(&core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX],
         1, "version", ast_get_version());
      PROMETHEUS_METRIC_SET_LABEL(&core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX],
         2, "build_options", ast_get_build_opts());
      PROMETHEUS_METRIC_SET_LABEL(&core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX],
         3, "build_date", ast_build_date);
      PROMETHEUS_METRIC_SET_LABEL(&core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX],
         4, "build_os", ast_build_os);
      PROMETHEUS_METRIC_SET_LABEL(&core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX],
         5, "build_kernel", ast_build_kernel);
      PROMETHEUS_METRIC_SET_LABEL(&core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX],
         6, "build_host", ast_build_hostname);
      snprintf(core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX].value,
         sizeof(core_metrics[METRIC_CORE_PROPS_ARRAY_INDEX].value),
         "%d", 1);

      for (i = 0; i < ARRAY_LEN(core_metrics); i++) {
         PROMETHEUS_METRIC_SET_LABEL(&core_metrics[i], 0, "eid", eid_str);
         prometheus_metric_register(&core_metrics[i]);
      }
   }
}

prometheus_config_pre_apply()

static int prometheus_config_pre_apply ( void  )

static

Pre-apply callback for the config framework.

This validates that required fields exist and are populated.

Definition at line 804 of file res_prometheus.c.

References aco_pending_config(), ast_log, AST_LOG_ERROR, ast_strlen_zero, config, and module_config::general.

{
   struct module_config *config = aco_pending_config(&cfg_info);

   if (!config->general->enabled) {
      /* If we're not enabled, we don't care about anything else */
      return 0;
   }

   if (!ast_strlen_zero(config->general->auth_username)
      && ast_strlen_zero(config->general->auth_password)) {
      ast_log(AST_LOG_ERROR, "'auth_username' set without a corresponding 'auth_password'\n");
      return -1;
   }

   return 0;
}

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 452 of file res_prometheus.c.

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

Referenced by AST_TEST_DEFINE().

{
   struct prometheus_metric *metric;

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

   return metric;
}

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 439 of file res_prometheus.c.

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

Referenced by AST_TEST_DEFINE(), and registry_message_cb().

{
   struct prometheus_metric *metric;

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

   return metric;
}

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 726 of file res_prometheus.c.

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

Referenced by config_alloc(), and module_config_alloc().

{
   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;
}

prometheus_general_config_dtor()

static void prometheus_general_config_dtor ( void *  obj )

static

Definition at line 719 of file res_prometheus.c.

References ast_string_field_free_memory, and config.

Referenced by prometheus_general_config_alloc().

{
   struct prometheus_general_config *config = obj;

   ast_string_field_free_memory(config);
}

prometheus_general_config_get()

struct prometheus_general_config* prometheus_general_config_get

(

void

)

Retrieve the current configuration of the module.

Note

This should primarily be done for testing purposes.

config is an AO2 ref counted object

Return values

NULL	on error
config	on success

Definition at line 738 of file res_prometheus.c.

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

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

{
   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;
}

prometheus_general_config_set()

void prometheus_general_config_set

(

struct prometheus_general_config *

config

)

Set the configuration for the module.

Note

This should primarily be done for testing purposes

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

Definition at line 750 of file res_prometheus.c.

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

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

{
   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();
}

prometheus_last_scrape_duration_get()

int64_t prometheus_last_scrape_duration_get

(

void

)

Retrieve the amount of time it took to perform the last scrape.

Time returned is in milliseconds

Return values

The	scrape duration, in milliseconds

Definition at line 701 of file res_prometheus.c.

References prometheus_metric::value.

Referenced by prometheus_show_status().

{
   int64_t duration;

   if (sscanf(core_scrape_metric.value, "%" PRIu64, &duration) != 1) {
      return -1;
   }

   return duration;
}

prometheus_last_scrape_time_get()

struct timeval prometheus_last_scrape_time_get

(

void

)

Retrieve the timestamp when the last scrape occurred.

Return values

The	time when the last scrape occurred

Definition at line 712 of file res_prometheus.c.

References lock, SCOPED_MUTEX, and scrape_lock.

Referenced by prometheus_show_status().

{
   SCOPED_MUTEX(lock, &scrape_lock);

   return last_scrape;
}

prometheus_metric_cmp()

static int prometheus_metric_cmp ( struct prometheus_metric *  left, struct prometheus_metric *  right  )

static

Definition at line 252 of file res_prometheus.c.

References ast_debug, prometheus_metric::labels, prometheus_label::name, prometheus_metric::name, PROMETHEUS_MAX_LABELS, and prometheus_label::value.

Referenced by prometheus_metric_register(), and prometheus_metric_unregister().

{
   int i;
   ast_debug(5, "Comparison: Names %s == %s\n", left->name, right->name);
   if (strcmp(left->name, right->name)) {
      return 0;
   }

   for (i = 0; i < PROMETHEUS_MAX_LABELS; i++) {
      ast_debug(5, "Comparison: Label %d Names %s == %s\n", i,
         left->labels[i].name, right->labels[i].name);
      if (strcmp(left->labels[i].name, right->labels[i].name)) {
         return 0;
      }

      ast_debug(5, "Comparison: Label %d Values %s == %s\n", i,
         left->labels[i].value, right->labels[i].value);
      if (strcmp(left->labels[i].value, right->labels[i].value)) {
         return 0;
      }
   }

   ast_debug(5, "Copmarison: %s (%p) is equal to %s (%p)\n",
      left->name, left, right->name, right);
   return 1;
}

prometheus_metric_create()

static struct prometheus_metric* prometheus_metric_create ( const char *  name, const char *  help  )

static

Definition at line 422 of file res_prometheus.c.

References prometheus_metric::allocation_strategy, ast_calloc, ast_copy_string(), ast_mutex_init, prometheus_metric::help, prometheus_metric::lock, prometheus_metric::name, NULL, and PROMETHEUS_METRIC_MALLOCD.

Referenced by prometheus_counter_create(), and prometheus_gauge_create().

{
   struct prometheus_metric *metric = NULL;

   metric = ast_calloc(1, sizeof(*metric));
   if (!metric) {
      return NULL;
   }
   metric->allocation_strategy = PROMETHEUS_METRIC_MALLOCD;
   ast_mutex_init(&metric->lock);

   ast_copy_string(metric->name, name, sizeof(metric->name));
   metric->help = help;

   return metric;
}

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 392 of file res_prometheus.c.

References prometheus_metric::allocation_strategy, ast_free, AST_LIST_REMOVE_HEAD, ast_mutex_destroy, prometheus_metric::children, prometheus_metric::lock, PROMETHEUS_METRIC_ALLOCD, and PROMETHEUS_METRIC_MALLOCD.

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

{
   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);
   }
}

prometheus_metric_full_to_string()

static void prometheus_metric_full_to_string ( struct prometheus_metric *  metric, struct ast_str **  output  )

static

Definition at line 485 of file res_prometheus.c.

References ast_str_append(), ast_strlen_zero, prometheus_metric::labels, prometheus_label::name, prometheus_metric::name, PROMETHEUS_MAX_LABELS, prometheus_label::value, and prometheus_metric::value.

Referenced by prometheus_metric_to_string().

{
   int i;
   int labels_exist = 0;

   ast_str_append(output, 0, "%s", metric->name);

   for (i = 0; i < PROMETHEUS_MAX_LABELS; i++) {
      if (!ast_strlen_zero(metric->labels[i].name)) {
         labels_exist = 1;
         if (i == 0) {
            ast_str_append(output, 0, "%s", "{");
         } else {
            ast_str_append(output, 0, "%s", ",");
         }
         ast_str_append(output, 0, "%s=\"%s\"",
            metric->labels[i].name,
            metric->labels[i].value);
      }
   }

   if (labels_exist) {
      ast_str_append(output, 0, "%s", "}");
   }

   /*
    * If no value exists, put in a 0. That ensures we don't anger Prometheus.
    */
   if (ast_strlen_zero(metric->value)) {
      ast_str_append(output, 0, " 0\n");
   } else {
      ast_str_append(output, 0, " %s\n", metric->value);
   }
}

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 287 of file res_prometheus.c.

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, lock, prometheus_metric::name, prometheus_metric_cmp(), SCOPED_MUTEX, and scrape_lock.

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

{
   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;
}

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 280 of file res_prometheus.c.

References AST_VECTOR_SIZE, lock, SCOPED_MUTEX, and scrape_lock.

Referenced by AST_TEST_DEFINE().

{
   SCOPED_MUTEX(lock, &scrape_lock);

   return AST_VECTOR_SIZE(&metrics);
}

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 521 of file res_prometheus.c.

References AST_LIST_TRAVERSE, ast_str_append(), prometheus_metric::children, 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(), bridges_scrape_cb(), channels_scrape_cb(), endpoints_scrape_cb(), http_callback(), prometheus_metric_callback(), and scrape_metrics().

{
   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);
   }
}

prometheus_metric_type_to_string()

static const char* prometheus_metric_type_to_string ( enum prometheus_metric_type  type )

static

Definition at line 465 of file res_prometheus.c.

References ast_assert, PROMETHEUS_METRIC_COUNTER, and PROMETHEUS_METRIC_GAUGE.

Referenced by prometheus_metric_to_string().

{
   switch (type) {
   case PROMETHEUS_METRIC_COUNTER:
      return "counter";
   case PROMETHEUS_METRIC_GAUGE:
      return "gauge";
   default:
      ast_assert(0);
      return "unknown";
   }
}

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 334 of file res_prometheus.c.

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, lock, prometheus_metric::name, prometheus_metric_cmp(), prometheus_metric_free(), SCOPED_MUTEX, and scrape_lock.

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

{
   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;
}

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 871 of file res_prometheus.c.

References AST_VECTOR_APPEND, and providers.

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

{
   AST_VECTOR_APPEND(&providers, provider);
}

prometheus_scrape_to_string()

struct ast_str* prometheus_scrape_to_string

(

void

)

Get the raw output of what a scrape would produce.

It can be useful to dump what a scrape will look like. This function returns the raw string representation of the metrics.

Return values

NULL	on error
Malloc'd	ast_str on success

Definition at line 685 of file res_prometheus.c.

References ast_mutex_lock, ast_mutex_unlock, ast_str_create, NULL, scrape_lock, and scrape_metrics().

Referenced by prometheus_show_metrics().

{
   struct ast_str *response;

   response = ast_str_create(512);
   if (!response) {
      return NULL;
   }

   ast_mutex_lock(&scrape_lock);
   scrape_metrics(&response);
   ast_mutex_unlock(&scrape_lock);

   return response;
}

reload_module()

static int reload_module ( void  )

static

Definition at line 910 of file res_prometheus.c.

References aco_process_config(), ACO_PROCESS_ERROR, ao2_ref, ast_http_uri_link(), ast_http_uri_unlink(), ast_log, AST_LOG_WARNING, AST_VECTOR_GET, AST_VECTOR_SIZE, lock, prometheus_metrics_provider::name, prometheus_general_config_get(), provider, providers, prometheus_metrics_provider::reload_cb, SCOPED_MUTEX, and scrape_lock.

Referenced by load_module().

                               {
   SCOPED_MUTEX(lock, &scrape_lock);
   int i;
   struct prometheus_general_config *general_config;

   ast_http_uri_unlink(&prometheus_uri);
   if (aco_process_config(&cfg_info, 1) == ACO_PROCESS_ERROR) {
      return -1;
   }

   /* Our config should be all reloaded now */
   general_config = prometheus_general_config_get();
   for (i = 0; i < AST_VECTOR_SIZE(&providers); i++) {
      const struct prometheus_metrics_provider *provider = AST_VECTOR_GET(&providers, i);

      if (!provider->reload_cb) {
         continue;
      }

      if (provider->reload_cb(general_config)) {
         ast_log(AST_LOG_WARNING, "Failed to reload metrics provider %s\n", provider->name);
         ao2_ref(general_config, -1);
         return -1;
      }
   }
   ao2_ref(general_config, -1);

   if (ast_http_uri_link(&prometheus_uri)) {
      ast_log(AST_LOG_WARNING, "Failed to re-register Prometheus Metrics URI during reload\n");
      return -1;
   }

   return 0;
}

scrape_metrics()

static void scrape_metrics ( struct ast_str **  response )

static

Definition at line 563 of file res_prometheus.c.

References ast_mutex_lock, ast_mutex_unlock, AST_VECTOR_GET, AST_VECTOR_SIZE, prometheus_callback::callback_fn, prometheus_metric::get_metric_value, prometheus_metric::lock, and prometheus_metric_to_string().

Referenced by http_callback(), and prometheus_scrape_to_string().

{
   int i;

   for (i = 0; i < AST_VECTOR_SIZE(&callbacks); i++) {
      struct prometheus_callback *callback = AST_VECTOR_GET(&callbacks, i);

      if (!callback) {
         continue;
      }

      callback->callback_fn(response);
   }

   for (i = 0; i < AST_VECTOR_SIZE(&metrics); i++) {
      struct prometheus_metric *metric = AST_VECTOR_GET(&metrics, i);

      if (!metric) {
         continue;
      }

      ast_mutex_lock(&metric->lock);
      if (metric->get_metric_value) {
         metric->get_metric_value(metric);
      }
      prometheus_metric_to_string(metric, response);
      ast_mutex_unlock(&metric->lock);
   }
}

unload_module()

static int unload_module ( void  )

static

Definition at line 876 of file res_prometheus.c.

References aco_info_destroy(), ao2_global_obj_release, ast_http_uri_unlink(), AST_VECTOR_FREE, AST_VECTOR_GET, AST_VECTOR_SIZE, lock, prometheus_metric_free(), provider, providers, SCOPED_MUTEX, scrape_lock, and prometheus_metrics_provider::unload_cb.

Referenced by load_module().

{
   SCOPED_MUTEX(lock, &scrape_lock);
   int i;

   ast_http_uri_unlink(&prometheus_uri);

   for (i = 0; i < AST_VECTOR_SIZE(&providers); i++) {
      const struct prometheus_metrics_provider *provider = AST_VECTOR_GET(&providers, i);

      if (!provider->unload_cb) {
         continue;
      }

      provider->unload_cb();
   }

   for (i = 0; i < AST_VECTOR_SIZE(&metrics); i++) {
      struct prometheus_metric *metric = AST_VECTOR_GET(&metrics, i);

      prometheus_metric_free(metric);
   }
   AST_VECTOR_FREE(&metrics);

   AST_VECTOR_FREE(&callbacks);

   AST_VECTOR_FREE(&providers);

   aco_info_destroy(&cfg_info);
   ao2_global_obj_release(global_config);

   return 0;
}

Variable Documentation

__mod_info

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Asterisk Prometheus Module" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_EXTENDED, .load = load_module, .unload = unload_module, .reload = reload_module, .load_pri = AST_MODPRI_DEFAULT, #ifdef 1 .requires = "res_pjsip", #endif }

static

Definition at line 1008 of file res_prometheus.c.

ast_module_info

const struct ast_module_info* ast_module_info = &__mod_info

static

Definition at line 1008 of file res_prometheus.c.

core_metrics

struct prometheus_metric core_metrics[]

static

Core metrics to scrape.

Definition at line 224 of file res_prometheus.c.

core_scrape_metric

struct prometheus_metric core_scrape_metric

static

The scrape duration metric.

This metric is special in that it should never be registered. Instead, the HTTP callback function that walks the metrics will always populate this metric explicitly if core metrics are enabled.

Definition at line 213 of file res_prometheus.c.

global_option

struct aco_type global_option

static

Definition at line 152 of file res_prometheus.c.

global_options

struct aco_type* global_options[] = ACO_TYPES(&global_option)

Definition at line 160 of file res_prometheus.c.

prometheus_conf

struct aco_file prometheus_conf

Initial value:

= {
   .filename = "prometheus.conf",
   .types = ACO_TYPES(&global_option),
}

Definition at line 162 of file res_prometheus.c.

prometheus_uri

struct ast_http_uri prometheus_uri

static

Definition at line 791 of file res_prometheus.c.

scrape_lock

ast_mutex_t scrape_lock = { PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP , NULL, {1, 0} }

static

Lock that protects data structures during an HTTP scrape.

Definition at line 136 of file res_prometheus.c.

Referenced by http_callback(), load_module(), prometheus_callback_register(), prometheus_callback_unregister(), prometheus_last_scrape_time_get(), prometheus_metric_register(), prometheus_metric_registered_count(), prometheus_metric_unregister(), prometheus_scrape_to_string(), reload_module(), and unload_module().