Asterisk - The Open Source Telephony Project GIT-master-f36a736
Macros | Functions
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.

◆ 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_statsd_log ( const char *  metric_name,
const char *  metric_type,
intmax_t  value 
)

Send a stat to the configured statsd server.

Parameters
metric_nameString (UTF-8) name of the metric.
metric_typeType of metric to send.
valueValue to send.
Since
12

Definition at line 232 of file res_statsd.c.

234{
235 char char_value[30];
236 snprintf(char_value, sizeof(char_value), "%jd", value);
237
238 ast_statsd_log_string(metric_name, metric_type, char_value, 1.0);
239}
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.
Definition: res_statsd.c:117
int value
Definition: syslog.c:37

References ast_statsd_log_string(), and value.

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

◆ 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_nameString (UTF-8) name of the metric.
metric_typeType of metric to send.
valueValue to send.
sample_ratePercentage of samples to send.
Since
12

Definition at line 174 of file res_statsd.c.

176{
177 char char_value[30];
178 snprintf(char_value, sizeof(char_value), "%jd", value);
179
180 ast_statsd_log_string(metric_name, metric_type, char_value, sample_rate);
181
182}

References ast_statsd_log_string(), and value.

Referenced by ast_statsd_log_full_va().

◆ 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_nameFormat string (UTF-8) specifying the name of the metric.
metric_typeType of metric to send.
valueValue to send.
sample_ratePercentage of samples to send.

Example Usage:

ast_statsd_log_full_va(AST_STATSD_TIMER, rtt, 1.0, "endpoint.%s.rtt", endpoint_name);
#define AST_STATSD_TIMER
Definition: statsd.h:41
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.
Definition: res_statsd.c:209

Definition at line 209 of file res_statsd.c.

211{
212 struct ast_str *buf;
213 va_list ap;
214 int res;
215
217 if (!buf) {
218 return;
219 }
220
221 va_start(ap, sample_rate);
222 res = ast_str_set_va(&buf, 0, metric_name, ap);
223 va_end(ap);
224
225 if (res == AST_DYNSTR_BUILD_FAILED) {
226 return;
227 }
228
229 ast_statsd_log_full(ast_str_buffer(buf), metric_type, value, sample_rate);
230}
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
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.
Definition: res_statsd.c:174
static struct ast_threadstorage statsd_buf
Definition: res_statsd.c:184
@ AST_DYNSTR_BUILD_FAILED
Definition: strings.h:943
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:1030
struct ast_str * ast_str_thread_get(struct ast_threadstorage *ts, size_t init_len)
Retrieve a thread locally stored dynamic string.
Definition: strings.h:909
Support for dynamic strings.
Definition: strings.h:623

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().

◆ 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_nameString (UTF-8) name of the metric.
valueValue to send.
sample_ratePercentage of samples to send.
Since
12

Definition at line 241 of file res_statsd.c.

243{
244 char char_value[30];
245 snprintf(char_value, sizeof(char_value), "%jd", value);
246
247 ast_statsd_log_string(metric_name, AST_STATSD_COUNTER, char_value,
248 sample_rate);
249}
#define AST_STATSD_COUNTER
Definition: statsd.h:39

References AST_STATSD_COUNTER, ast_statsd_log_string(), and value.

◆ 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_nameString (UTF-8) name of the metric.
metric_typeType of metric to send.
valueValue to send.
sample_ratePercentage of samples to send.
Since
13

Definition at line 117 of file res_statsd.c.

119{
120 struct conf *cfg;
121 struct ast_str *msg;
122 size_t len;
123 struct ast_sockaddr statsd_server;
124
125 if (socket_fd == -1) {
126 return;
127 }
128
129 /* Rates <= 0.0 never get logged.
130 * Rates >= 1.0 always get logged.
131 * All others leave it to chance.
132 */
133 if (sample_rate <= 0.0 ||
134 (sample_rate < 1.0 && sample_rate < ast_random_double())) {
135 return;
136 }
137
139 conf_server(cfg, &statsd_server);
140
141 msg = ast_str_create(40);
142 if (!msg) {
143 ao2_cleanup(cfg);
144 return;
145 }
146
147 if (!ast_strlen_zero(cfg->global->prefix)) {
148 ast_str_append(&msg, 0, "%s.", cfg->global->prefix);
149 }
150
151 if (!cfg->global->meter_support && strcmp(metric_type, AST_STATSD_METER)) {
152 ast_str_append(&msg, 0, "%s_meter:%s|%s", metric_name, value, AST_STATSD_COUNTER);
153 } else {
154 ast_str_append(&msg, 0, "%s:%s|%s", metric_name, value, metric_type);
155 }
156
157 if (sample_rate < 1.0) {
158 ast_str_append(&msg, 0, "|@%.2f", sample_rate);
159 }
160
161 if (cfg->global->add_newline) {
162 ast_str_append(&msg, 0, "\n");
163 }
164
165 len = ast_str_strlen(msg);
166
167 ast_debug(6, "Sending statistic %s to StatsD server\n", ast_str_buffer(msg));
168 ast_sendto(socket_fd, ast_str_buffer(msg), len, 0, &statsd_server);
169
170 ao2_cleanup(cfg);
171 ast_free(msg);
172}
#define ast_free(a)
Definition: astmm.h:180
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
#define ao2_global_obj_ref(holder)
Get a reference to the object stored in the global holder.
Definition: astobj2.h:918
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#define ast_debug(level,...)
Log a DEBUG message.
ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags, const struct ast_sockaddr *dest_addr)
Wrapper around sendto(2) that uses ast_sockaddr.
Definition: netsock2.c:614
static void conf_server(const struct conf *cfg, struct ast_sockaddr *addr)
Definition: res_statsd.c:109
static int socket_fd
Definition: res_statsd.c:84
#define AST_STATSD_METER
Definition: statsd.h:48
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
#define ast_str_create(init_len)
Create a malloc'ed dynamic length string.
Definition: strings.h:659
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:730
Socket address structure.
Definition: netsock2.h:97
char prefix[MAX_PREFIX+1]
Definition: res_statsd.c:95
All configuration options for http media cache.
struct conf_global_options * global
Definition: res_statsd.c:103
#define ast_random_double()
Returns a random number between 0.0 and 1.0, inclusive.
Definition: utils.h:624

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_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_nameFormat string (UTF-8) specifying the name of the metric.
metric_typeType of metric to send.
valueValue to send.
sample_ratePercentage of samples to send.

Example Usage:

ast_statsd_log_string_va(AST_STATSD_GAUGE, "+1", 1.0, "endpoints.states.%s", state_name);
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.
Definition: res_statsd.c:186
#define AST_STATSD_GAUGE
Support for publishing to a statsd server.
Definition: statsd.h:32

Definition at line 186 of file res_statsd.c.

188{
189 struct ast_str *buf;
190 va_list ap;
191 int res;
192
194 if (!buf) {
195 return;
196 }
197
198 va_start(ap, sample_rate);
199 res = ast_str_set_va(&buf, 0, metric_name, ap);
200 va_end(ap);
201
202 if (res == AST_DYNSTR_BUILD_FAILED) {
203 return;
204 }
205
206 ast_statsd_log_string(ast_str_buffer(buf), metric_type, value, sample_rate);
207}

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().