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.
#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_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.
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.
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.
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.
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.
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.

Macro Definition Documentation

AST_STATSD_COUNTER

#define AST_STATSD_COUNTER   "c"

A change in a value.

Definition at line 39 of file statsd.h.

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.

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"

Meters are non-standard and poorly supported by StatsD servers

Deprecated:

You should switch to counter or stateful counters for a similar effect.

Definition at line 48 of file statsd.h.

AST_STATSD_TIMER

#define AST_STATSD_TIMER   "ms"

Measure of milliseconds.

Definition at line 41 of file statsd.h.

Function Documentation

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 251 of file res_statsd.c.

{
    char char_value[30];
    snprintf(char_value, sizeof(char_value), "%jd", value);
 
    ast_statsd_log_string(metric_name, metric_type, char_value, 1.0);
}

References ast_statsd_log_string(), and value.

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

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.
metric_type	Type of metric to send.
value	Value to send.
sample_rate	Percentage of samples to send.

Since

12

Definition at line 193 of file res_statsd.c.

{
    char char_value[30];
    snprintf(char_value, sizeof(char_value), "%jd", value);
 
    ast_statsd_log_string(metric_name, metric_type, char_value, sample_rate);
 
}

References ast_statsd_log_string(), and value.

Referenced by ast_statsd_log_full_va().

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 228 of file res_statsd.c.

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

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

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

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 260 of file res_statsd.c.

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

References AST_STATSD_COUNTER, ast_statsd_log_string(), and value.

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.
metric_type	Type of metric to send.
value	Value to send.
sample_rate	Percentage of samples to send.

Since

13

Definition at line 136 of file res_statsd.c.

{
    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);
    }
 
    if (!cfg->global->meter_support && strcmp(metric_type, AST_STATSD_METER)) {
        ast_str_append(&msg, 0, "%s_meter:%s|%s", metric_name, value, AST_STATSD_COUNTER);
    } else {
        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);
}

References conf_global_options::add_newline, ao2_cleanup, ao2_global_obj_ref, ast_debug, ast_free, ast_random_double, ast_sendto(), AST_STATSD_COUNTER, AST_STATSD_METER, ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_strlen(), ast_strlen_zero(), conf_server(), conf::global, len(), conf_global_options::meter_support, 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().

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 205 of file res_statsd.c.

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

References AST_DYNSTR_BUILD_FAILED, ast_statsd_log_string(), ast_str_buffer(), ast_str_set_va(), ast_str_thread_get(), 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().