statsd.h File Reference

#include "asterisk/optional_api.h"

Include dependency graph for statsd.h:

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

Go to the source code of this file.

Macros
#define	AST_STATSD_COUNTER   "c"
#define	AST_STATSD_GAUGE   "g"
	Support for publishing to a statsd server. More...
#define	AST_STATSD_GUAGE   AST_STATSD_GAUGE
#define	AST_STATSD_HISTOGRAM   "h"
#define	AST_STATSD_METER   "m"
#define	AST_STATSD_TIMER   "ms"

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

Macro Definition Documentation

AST_STATSD_COUNTER

#define AST_STATSD_COUNTER   "c"

A change in a value.

Definition at line 39 of file statsd.h.

Referenced by ast_statsd_log_sample().

AST_STATSD_GAUGE

#define AST_STATSD_GAUGE   "g"

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

An instantaneous measurement of a value.

Definition at line 32 of file statsd.h.

Referenced by ast_res_pjsip_find_or_create_contact_status(), ast_sip_initialize_sorcery_location(), handle_endpoint_update(), load_module(), 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(), update_client_state_status(), update_endpoint_state(), and updates().

AST_STATSD_GUAGE

#define AST_STATSD_GUAGE   AST_STATSD_GAUGE

Embarrassingly, gauge was misspelled for quite some time.

Deprecated:

You should spell gauge correctly.

Definition at line 37 of file statsd.h.

AST_STATSD_HISTOGRAM

#define AST_STATSD_HISTOGRAM   "h"

Distribution of values over time.

Definition at line 43 of file statsd.h.

AST_STATSD_METER

#define AST_STATSD_METER   "m"

Events over time. Sorta like increment-only counters.

Definition at line 45 of file statsd.h.

Referenced by statsmaker().

AST_STATSD_TIMER

#define AST_STATSD_TIMER   "ms"

Measure of milliseconds.

Definition at line 41 of file statsd.h.

Referenced by sip_options_contact_status_notify_task(), and updates().

Function Documentation

ast_statsd_log()

void 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_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_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_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_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_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);
}