res_statsd.c File Reference

#include "asterisk.h"
#include "asterisk/config_options.h"
#include "asterisk/module.h"
#include "asterisk/netsock2.h"
#include "asterisk/statsd.h"

Include dependency graph for res_statsd.c:

Go to the source code of this file.

Data Structures
struct	conf
	All configuration options for statsd client. More...
struct	conf_global_options
	Global configuration options for statsd client. More...

Macros
#define	AST_API_MODULE
	Support for publishing to a StatsD server. More...
#define	DEFAULT_STATSD_PORT   8125
#define	MAX_PREFIX   40

Functions
static void	__init_statsd_buf (void)
static void	__reg_module (void)
static void	__unreg_module (void)
static	AO2_GLOBAL_OBJ_STATIC (confs)
	Locking container for safe configuration access. More...
struct ast_module *	AST_MODULE_SELF_SYM (void)
void AST_OPTIONAL_API_NAME()	ast_statsd_log (const char *metric_name, const char *metric_type, intmax_t value)
	Send a stat to the configured statsd server. More...
void AST_OPTIONAL_API_NAME()	ast_statsd_log_full (const char *metric_name, const char *metric_type, intmax_t value, double sample_rate)
	Send a stat to the configured statsd server. More...
void AST_OPTIONAL_API_NAME()	ast_statsd_log_full_va (const char *metric_name, const char *metric_type, intmax_t value, double sample_rate,...)
	Send a stat to the configured statsd server. More...
void AST_OPTIONAL_API_NAME()	ast_statsd_log_sample (const char *metric_name, intmax_t value, double sample_rate)
	Send a random sampling of a stat to the configured statsd server. More...
void AST_OPTIONAL_API_NAME()	ast_statsd_log_string (const char *metric_name, const char *metric_type, const char *value, double sample_rate)
	Send a stat to the configured statsd server. More...
void AST_OPTIONAL_API_NAME()	ast_statsd_log_string_va (const char *metric_name, const char *metric_type, const char *value, double sample_rate,...)
	Send a stat to the configured statsd server. More...
static void *	conf_alloc (void)
	Creates the statis http conf object. More...
static void	conf_destructor (void *obj)
	Disposes of the statsd conf object. More...
static void	conf_server (const struct conf *cfg, struct ast_sockaddr *addr)
	CONFIG_INFO_STANDARD (cfg_info, confs, conf_alloc,.files=ACO_FILES(&conf_file))
static char	is_enabled (void)
	Helper function to check if module is enabled. More...
static int	load_module (void)
static int	reload_module (void)
static int	statsd_init (void)
static void	statsd_shutdown (void)
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 = "StatsD client support" , .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_REALTIME_DRIVER + 5, }
static const struct ast_module_info *	ast_module_info = &__mod_info
static struct aco_file	conf_file
	The conf file that's processed for the module. More...
static struct aco_type	global_option
	Mapping of the statsd conf struct's globals to the general context in the config file. More...
static struct aco_type *	global_options [] = ACO_TYPES(&global_option)
static int	socket_fd = -1
static struct ast_threadstorage	statsd_buf = { .once = PTHREAD_ONCE_INIT , .key_init = __init_statsd_buf , .custom_init = NULL , }

Macro Definition Documentation

AST_API_MODULE

#define AST_API_MODULE

Support for publishing to a StatsD server.

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

Since

12

Definition at line 72 of file res_statsd.c.

DEFAULT_STATSD_PORT

#define DEFAULT_STATSD_PORT   8125

Definition at line 75 of file res_statsd.c.

Referenced by conf_server().

MAX_PREFIX

#define MAX_PREFIX   40

Definition at line 77 of file res_statsd.c.

Function Documentation

__init_statsd_buf()

static void __init_statsd_buf ( void  )

static

Definition at line 174 of file res_statsd.c.

{

__reg_module()

static void __reg_module ( void  )

static

Definition at line 427 of file res_statsd.c.

__unreg_module()

static void __unreg_module ( void  )

static

Definition at line 427 of file res_statsd.c.

AO2_GLOBAL_OBJ_STATIC()

static AO2_GLOBAL_OBJ_STATIC ( confs  )

static

Locking container for safe configuration access.

AST_MODULE_SELF_SYM()

struct ast_module* AST_MODULE_SELF_SYM

(

void

)

Definition at line 427 of file res_statsd.c.

ast_statsd_log()

void AST_OPTIONAL_API_NAME() ast_statsd_log	(	const char *	metric_name,
		const char *	metric_type,
		intmax_t	value
	)

Send a stat to the configured statsd server.

Parameters

metric_name	String (UTF-8) name of the metric.
metric_type	Type of metric to send.
value	Value to send.

Since

12

Definition at line 222 of file res_statsd.c.

References ast_statsd_log_string(), and value.

Referenced by load_module(), statsmaker(), and updates().

{
   char char_value[30];
   snprintf(char_value, sizeof(char_value), "%jd", value);

   ast_statsd_log_string(metric_name, metric_type, char_value, 1.0);
}

ast_statsd_log_full()

void AST_OPTIONAL_API_NAME() ast_statsd_log_full	(	const char *	metric_name,
		const char *	metric_type,
		intmax_t	value,
		double	sample_rate
	)

Send a stat to the configured statsd server.

The is nearly the most flexible function for sending a message to the statsd server, but also the least easy to use. See ast_statsd_log() or ast_statsd_log_sample() for a slightly more convenient interface.

Parameters

metric_name	String (UTF-8) name of the metric.
type_str	Type of metric to send.
value	Value to send.
sample_rate	Percentage of samples to send.

Since

12

Definition at line 164 of file res_statsd.c.

References ast_statsd_log_string(), and value.

Referenced by ast_statsd_log_full_va().

{
   char char_value[30];
   snprintf(char_value, sizeof(char_value), "%jd", value);

   ast_statsd_log_string(metric_name, metric_type, char_value, sample_rate);

}

ast_statsd_log_full_va()

void AST_OPTIONAL_API_NAME() ast_statsd_log_full_va	(	const char *	metric_name,
		const char *	metric_type,
		intmax_t	value,
		double	sample_rate,
			...
	)

Send a stat to the configured statsd server.

Since

13.7.0

This is the most flexible function for sending a message to the statsd server. In addition to allowing the value and sample rate to be specified, the metric_name can be formed as a printf style string with variable arguments.

Parameters

metric_name	Format string (UTF-8) specifying the name of the metric.
metric_type	Type of metric to send.
value	Value to send.
sample_rate	Percentage of samples to send.

Example Usage:

ast_statsd_log_full_va(AST_STATSD_TIMER, rtt, 1.0, "endpoint.%s.rtt", endpoint_name);

Definition at line 199 of file res_statsd.c.

References AST_DYNSTR_BUILD_FAILED, ast_statsd_log_full(), ast_str_buffer(), ast_str_set_va(), ast_str_thread_get(), buf, statsd_buf, and value.

Referenced by ast_sip_initialize_sorcery_location(), handle_endpoint_update(), and sip_options_contact_status_notify_task().

{
   struct ast_str *buf;
   va_list ap;
   int res;

   buf = ast_str_thread_get(&statsd_buf, 128);
   if (!buf) {
      return;
   }

   va_start(ap, sample_rate);
   res = ast_str_set_va(&buf, 0, metric_name, ap);
   va_end(ap);

   if (res == AST_DYNSTR_BUILD_FAILED) {
      return;
   }

   ast_statsd_log_full(ast_str_buffer(buf), metric_type, value, sample_rate);
}

ast_statsd_log_sample()

void AST_OPTIONAL_API_NAME() ast_statsd_log_sample	(	const char *	metric_name,
		intmax_t	value,
		double	sample_rate
	)

Send a random sampling of a stat to the configured statsd server.

The type of sampled metrics is always AST_STATSD_COUNTER. The given sample_rate should be a percentage between 0.0 and 1.0. If it's <= 0.0, then no samples will be sent. If it's >= 1.0, then all samples will be sent.

Parameters

metric_name	String (UTF-8) name of the metric.
value	Value to send.
sample_rate	Percentage of samples to send.

Since

12

Definition at line 231 of file res_statsd.c.

References AST_STATSD_COUNTER, ast_statsd_log_string(), and value.

{
   char char_value[30];
   snprintf(char_value, sizeof(char_value), "%jd", value);

   ast_statsd_log_string(metric_name, AST_STATSD_COUNTER, char_value,
      sample_rate);
}

ast_statsd_log_string()

void AST_OPTIONAL_API_NAME() ast_statsd_log_string	(	const char *	metric_name,
		const char *	metric_type,
		const char *	value,
		double	sample_rate
	)

Send a stat to the configured statsd server.

This function uses a character argument for value instead of an intmax_t argument. This is designed to be simpler to use for updating a current value rather than resetting it.

Parameters

metric_name	String (UTF-8) name of the metric.
type_str	Type of metric to send.
value	Value to send.
sample_rate	Percentage of samples to send.

Since

13

Definition at line 111 of file res_statsd.c.

References conf_global_options::add_newline, ao2_cleanup, ao2_global_obj_ref, ast_debug, ast_free, ast_random_double, ast_sendto(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_strlen(), ast_strlen_zero, conf_server(), conf::global, len(), conf_global_options::prefix, socket_fd, and value.

Referenced by ast_statsd_log(), ast_statsd_log_full(), ast_statsd_log_sample(), ast_statsd_log_string_va(), handle_endpoint_update(), sip_outbound_registration_client_state_destroy(), sip_outbound_registration_state_alloc(), statsd_exec(), update_endpoint_state(), and updates().

{
   struct conf *cfg;
   struct ast_str *msg;
   size_t len;
   struct ast_sockaddr statsd_server;

   if (socket_fd == -1) {
      return;
   }

   /* Rates <= 0.0 never get logged.
    * Rates >= 1.0 always get logged.
    * All others leave it to chance.
    */
   if (sample_rate <= 0.0 ||
      (sample_rate < 1.0 && sample_rate < ast_random_double())) {
      return;
   }

   cfg = ao2_global_obj_ref(confs);
   conf_server(cfg, &statsd_server);

   msg = ast_str_create(40);
   if (!msg) {
      ao2_cleanup(cfg);
      return;
   }

   if (!ast_strlen_zero(cfg->global->prefix)) {
      ast_str_append(&msg, 0, "%s.", cfg->global->prefix);
   }

   ast_str_append(&msg, 0, "%s:%s|%s", metric_name, value, metric_type);

   if (sample_rate < 1.0) {
      ast_str_append(&msg, 0, "|@%.2f", sample_rate);
   }

   if (cfg->global->add_newline) {
      ast_str_append(&msg, 0, "\n");
   }

   len = ast_str_strlen(msg);

   ast_debug(6, "Sending statistic %s to StatsD server\n", ast_str_buffer(msg));
   ast_sendto(socket_fd, ast_str_buffer(msg), len, 0, &statsd_server);

   ao2_cleanup(cfg);
   ast_free(msg);
}

ast_statsd_log_string_va()

void AST_OPTIONAL_API_NAME() ast_statsd_log_string_va	(	const char *	metric_name,
		const char *	metric_type,
		const char *	value,
		double	sample_rate,
			...
	)

Send a stat to the configured statsd server.

Since

13.7.0

This is the most flexible function for sending a message to the statsd server. In addition to allowing the string value and sample rate to be specified, the metric_name can be formed as a printf style string with variable arguments.

Parameters

metric_name	Format string (UTF-8) specifying the name of the metric.
metric_type	Type of metric to send.
value	Value to send.
sample_rate	Percentage of samples to send.

Example Usage:

ast_statsd_log_string_va(AST_STATSD_GAUGE, "+1", 1.0, "endpoints.states.%s", state_name);

Definition at line 176 of file res_statsd.c.

References AST_DYNSTR_BUILD_FAILED, ast_statsd_log_string(), ast_str_buffer(), ast_str_set_va(), ast_str_thread_get(), buf, statsd_buf, and value.

Referenced by ast_res_pjsip_find_or_create_contact_status(), sip_options_contact_status_notify_task(), sip_options_remove_contact_status(), sip_options_set_contact_status(), sip_outbound_registration_client_state_destroy(), sip_outbound_registration_state_alloc(), and update_client_state_status().

{
   struct ast_str *buf;
   va_list ap;
   int res;

   buf = ast_str_thread_get(&statsd_buf, 128);
   if (!buf) {
      return;
   }

   va_start(ap, sample_rate);
   res = ast_str_set_va(&buf, 0, metric_name, ap);
   va_end(ap);

   if (res == AST_DYNSTR_BUILD_FAILED) {
      return;
   }

   ast_statsd_log_string(ast_str_buffer(buf), metric_type, value, sample_rate);
}

conf_alloc()

static void* conf_alloc ( void  )

static

Creates the statis http conf object.

Definition at line 261 of file res_statsd.c.

References ao2_alloc, ao2_ref, conf_destructor(), conf::global, and NULL.

Referenced by load_module().

{
    struct conf *cfg;

    if (!(cfg = ao2_alloc(sizeof(*cfg), conf_destructor))) {
        return NULL;
    }

    if (!(cfg->global = ao2_alloc(sizeof(*cfg->global), NULL))) {
        ao2_ref(cfg, -1);
        return NULL;
    }
    return cfg;
}

conf_destructor()

static void conf_destructor ( void *  obj )

static

Disposes of the statsd conf object.

Definition at line 254 of file res_statsd.c.

References ao2_cleanup, and conf::global.

Referenced by conf_alloc().

{
    struct conf *cfg = obj;
    ao2_cleanup(cfg->global);
}

conf_server()

static void conf_server ( const struct conf *  cfg, struct ast_sockaddr *  addr  )

static

Definition at line 103 of file res_statsd.c.

References ast_sockaddr_port, ast_sockaddr_set_port, DEFAULT_STATSD_PORT, conf::global, and conf_global_options::statsd_server.

Referenced by ast_statsd_log_string(), and statsd_init().

{
   *addr = cfg->global->statsd_server;
   if (ast_sockaddr_port(addr) == 0) {
      ast_sockaddr_set_port(addr, DEFAULT_STATSD_PORT);
   }
}

CONFIG_INFO_STANDARD()

CONFIG_INFO_STANDARD	(	cfg_info	,
		confs	,
		conf_alloc	,
		.	files = ACO_FILES(&conf_file)
	)

is_enabled()

static char is_enabled ( void  )

static

Helper function to check if module is enabled.

Definition at line 288 of file res_statsd.c.

References ao2_cleanup, ao2_global_obj_ref, and RAII_VAR.

Referenced by load_module(), reload_module(), and statsd_init().

{
   RAII_VAR(struct conf *, cfg, ao2_global_obj_ref(confs), ao2_cleanup);
   return cfg->global->enabled;
}

load_module()

static int load_module ( void  )

static

Definition at line 340 of file res_statsd.c.

References ACO_EXACT, aco_info_destroy(), aco_info_init(), aco_option_register, aco_process_config(), ACO_PROCESS_ERROR, aco_set_defaults(), conf_global_options::add_newline, ao2_global_obj_replace_unref, ao2_ref, ast_log, AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, CHARFLDSET, conf_alloc(), conf_global_options::enabled, FLDSET, conf::global, is_enabled(), LOG_ERROR, LOG_NOTICE, OPT_BOOL_T, OPT_CHAR_ARRAY_T, OPT_SOCKADDR_T, conf_global_options::prefix, statsd_init(), conf_global_options::statsd_server, and unload_module().

Referenced by reload_module().

{
   if (aco_info_init(&cfg_info)) {
      aco_info_destroy(&cfg_info);
      return AST_MODULE_LOAD_DECLINE;
   }

   aco_option_register(&cfg_info, "enabled", ACO_EXACT, global_options,
      "no", OPT_BOOL_T, 1,
      FLDSET(struct conf_global_options, enabled));

   aco_option_register(&cfg_info, "add_newline", ACO_EXACT, global_options,
      "no", OPT_BOOL_T, 1,
      FLDSET(struct conf_global_options, add_newline));

   aco_option_register(&cfg_info, "server", ACO_EXACT, global_options,
      "127.0.0.1", OPT_SOCKADDR_T, 0,
      FLDSET(struct conf_global_options, statsd_server));

   aco_option_register(&cfg_info, "prefix", ACO_EXACT, global_options,
      "", OPT_CHAR_ARRAY_T, 0,
      CHARFLDSET(struct conf_global_options, prefix));

   if (aco_process_config(&cfg_info, 0) == ACO_PROCESS_ERROR) {
      struct conf *cfg;

      ast_log(LOG_NOTICE, "Could not load statsd config; using defaults\n");
      cfg = conf_alloc();
      if (!cfg) {
         aco_info_destroy(&cfg_info);
         return AST_MODULE_LOAD_DECLINE;
      }

      if (aco_set_defaults(&global_option, "general", cfg->global)) {
         ast_log(LOG_ERROR, "Failed to initialize statsd defaults.\n");
         ao2_ref(cfg, -1);
         aco_info_destroy(&cfg_info);
         return AST_MODULE_LOAD_DECLINE;
      }

      ao2_global_obj_replace_unref(confs, cfg);
      ao2_ref(cfg, -1);
   }

   if (!is_enabled()) {
      return AST_MODULE_LOAD_SUCCESS;
   }

   if (statsd_init()) {
      unload_module();
      return AST_MODULE_LOAD_DECLINE;
   }

   return AST_MODULE_LOAD_SUCCESS;
}

reload_module()

static int reload_module ( void  )

static

Definition at line 396 of file res_statsd.c.

References aco_process_config(), ACO_PROCESS_ERROR, ACO_PROCESS_OK, ACO_PROCESS_UNCHANGED, AST_MODFLAG_GLOBAL_SYMBOLS, AST_MODFLAG_LOAD_ORDER, AST_MODPRI_REALTIME_DRIVER, AST_MODULE_INFO(), AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, AST_MODULE_SUPPORT_EXTENDED, ASTERISK_GPL_KEY, is_enabled(), load_module(), reload(), statsd_init(), statsd_shutdown(), and unload_module().

{
   switch (aco_process_config(&cfg_info, 1)) {
   case ACO_PROCESS_OK:
      break;
   case ACO_PROCESS_UNCHANGED:
      return AST_MODULE_LOAD_SUCCESS;
   case ACO_PROCESS_ERROR:
   default:
      return AST_MODULE_LOAD_DECLINE;
   }

   if (is_enabled()) {
      if (statsd_init()) {
         return AST_MODULE_LOAD_DECLINE;
      }
   } else {
      statsd_shutdown();
   }
   return AST_MODULE_LOAD_SUCCESS;
}

statsd_init()

static int statsd_init ( void  )

static

Definition at line 294 of file res_statsd.c.

References ao2_cleanup, ao2_global_obj_ref, ast_assert, ast_debug, AST_SOCKADDR_STR_DEFAULT, ast_sockaddr_stringify_fmt(), AST_YESNO, conf_server(), is_enabled(), RAII_VAR, and socket_fd.

Referenced by load_module(), and reload_module().

{
   RAII_VAR(struct conf *, cfg, ao2_global_obj_ref(confs), ao2_cleanup);
   char *server;
   struct ast_sockaddr statsd_server;

   ast_assert(is_enabled());

   ast_debug(3, "Configuring StatsD client.\n");

   if (socket_fd == -1) {
      ast_debug(3, "Creating StatsD socket.\n");
      socket_fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
      if (socket_fd == -1) {
         perror("Error creating StatsD socket");
         return -1;
      }
   }

   conf_server(cfg, &statsd_server);
   server = ast_sockaddr_stringify_fmt(&statsd_server,
      AST_SOCKADDR_STR_DEFAULT);
   ast_debug(3, "  StatsD server = %s.\n", server);
   ast_debug(3, "  add newline = %s\n", AST_YESNO(cfg->global->add_newline));
   ast_debug(3, "  prefix = %s\n", cfg->global->prefix);

   return 0;
}

statsd_shutdown()

static void statsd_shutdown ( void  )

static

Definition at line 323 of file res_statsd.c.

References ast_debug, and socket_fd.

Referenced by reload_module(), and unload_module().

{
   ast_debug(3, "Shutting down StatsD client.\n");
   if (socket_fd != -1) {
      close(socket_fd);
      socket_fd = -1;
   }
}

unload_module()

static int unload_module ( void  )

static

Definition at line 332 of file res_statsd.c.

References aco_info_destroy(), ao2_global_obj_release, and statsd_shutdown().

Referenced by load_module(), and reload_module().

{
   statsd_shutdown();
   aco_info_destroy(&cfg_info);
   ao2_global_obj_release(confs);
   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 = "StatsD client support" , .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_REALTIME_DRIVER + 5, }

static

Definition at line 427 of file res_statsd.c.

ast_module_info

const struct ast_module_info* ast_module_info = &__mod_info

static

Definition at line 427 of file res_statsd.c.

conf_file

struct aco_file conf_file

static

The conf file that's processed for the module.

Definition at line 277 of file res_statsd.c.

global_option

struct aco_type global_option

static

Mapping of the statsd conf struct's globals to the general context in the config file.

Definition at line 243 of file res_statsd.c.

global_options

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

static

Definition at line 251 of file res_statsd.c.

socket_fd

int socket_fd = -1

static

Socket for sending statd messages

Definition at line 80 of file res_statsd.c.

Referenced by ast_statsd_log_string(), statsd_init(), and statsd_shutdown().

statsd_buf

struct ast_threadstorage statsd_buf = { .once = PTHREAD_ONCE_INIT , .key_init = __init_statsd_buf , .custom_init = NULL , }

static

Definition at line 174 of file res_statsd.c.

Referenced by ast_statsd_log_full_va(), and ast_statsd_log_string_va().