Asterisk - The Open Source Telephony Project GIT-master-85241bd
statsd.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2013, Digium, Inc.
5 *
6 * David M. Lee, II <dlee@digium.com>
7 *
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
13 *
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
17 */
18
19#ifndef _ASTERISK_STATSD_H
20#define _ASTERISK_STATSD_H
21
22/*!
23 * \brief Support for publishing to a statsd server.
24 *
25 * \author David M. Lee, II <dlee@digium.com>
26 * \since 12
27 */
28
30
31/*! An instantaneous measurement of a value. */
32#define AST_STATSD_GAUGE "g"
33/*!
34 * Embarrassingly, gauge was misspelled for quite some time.
35 * \deprecated You should spell gauge correctly.
36 */
37#define AST_STATSD_GUAGE AST_STATSD_GAUGE
38/*! A change in a value. */
39#define AST_STATSD_COUNTER "c"
40/*! Measure of milliseconds. */
41#define AST_STATSD_TIMER "ms"
42/*! Distribution of values over time. */
43#define AST_STATSD_HISTOGRAM "h"
44/*!
45 * Meters are non-standard and poorly supported by StatsD servers
46 * \deprecated You should switch to counter or stateful counters for a similar effect.
47 */
48#define AST_STATSD_METER "m"
49
50
51/*!
52 * \brief Send a stat to the configured statsd server.
53 *
54 * This function uses a character argument for value instead of
55 * an intmax_t argument. This is designed to be simpler to use for
56 * updating a current value rather than resetting it.
57 *
58 * \param metric_name String (UTF-8) name of the metric.
59 * \param metric_type Type of metric to send.
60 * \param value Value to send.
61 * \param sample_rate Percentage of samples to send.
62 * \since 13
63 */
64AST_OPTIONAL_API(void, ast_statsd_log_string, (const char *metric_name,
65 const char *metric_type, const char *value, double sample_rate), {});
66
67/*!
68 * \brief Send a stat to the configured statsd server.
69 * \since 13.7.0
70 *
71 * This is the most flexible function for sending a message to the statsd
72 * server. In addition to allowing the string value and sample rate to be specified,
73 * the metric_name can be formed as a printf style string with variable
74 * arguments.
75 *
76 * \param metric_name Format string (UTF-8) specifying the name of the metric.
77 * \param metric_type Type of metric to send.
78 * \param value Value to send.
79 * \param sample_rate Percentage of samples to send.
80 *
81 * Example Usage:
82 * \code
83 * ast_statsd_log_string_va(AST_STATSD_GAUGE, "+1", 1.0, "endpoints.states.%s", state_name);
84 * \endcode
85 */
86AST_OPTIONAL_API_ATTR(void, format(printf, 1, 5), ast_statsd_log_string_va,
87 (const char *metric_name, const char *metric_type, const char *value, double sample_rate, ...), {});
88
89/*!
90 * \brief Send a stat to the configured statsd server.
91 *
92 * The is nearly the most flexible function for sending a message to the statsd
93 * server, but also the least easy to use. See ast_statsd_log() or
94 * ast_statsd_log_sample() for a slightly more convenient interface.
95 *
96 * \param metric_name String (UTF-8) name of the metric.
97 * \param metric_type Type of metric to send.
98 * \param value Value to send.
99 * \param sample_rate Percentage of samples to send.
100 * \since 12
101 */
102AST_OPTIONAL_API(void, ast_statsd_log_full, (const char *metric_name,
103 const char *metric_type, intmax_t value, double sample_rate), {});
104
105/*!
106 * \brief Send a stat to the configured statsd server.
107 * \since 13.7.0
108 *
109 * This is the most flexible function for sending a message to the statsd
110 * server. In addition to allowing the value and sample rate to be specified,
111 * the metric_name can be formed as a printf style string with variable
112 * arguments.
113 *
114 * \param metric_name Format string (UTF-8) specifying the name of the metric.
115 * \param metric_type Type of metric to send.
116 * \param value Value to send.
117 * \param sample_rate Percentage of samples to send.
118 *
119 * Example Usage:
120 * \code
121 * ast_statsd_log_full_va(AST_STATSD_TIMER, rtt, 1.0, "endpoint.%s.rtt", endpoint_name);
122 * \endcode
123 */
124AST_OPTIONAL_API_ATTR(void, format(printf, 1, 5), ast_statsd_log_full_va,
125 (const char *metric_name, const char *metric_type, intmax_t value, double sample_rate, ...), {});
126
127/*!
128 * \brief Send a stat to the configured statsd server.
129 * \param metric_name String (UTF-8) name of the metric.
130 * \param metric_type Type of metric to send.
131 * \param value Value to send.
132 * \since 12
133 */
134AST_OPTIONAL_API(void, ast_statsd_log, (const char *metric_name,
135 const char *metric_type, intmax_t value), {});
136
137/*!
138 * \brief Send a random sampling of a stat to the configured statsd server.
139 *
140 * The type of sampled metrics is always \ref AST_STATSD_COUNTER. The given
141 * \a sample_rate should be a percentage between 0.0 and 1.0. If it's <= 0.0,
142 * then no samples will be sent. If it's >= 1.0, then all samples will be sent.
143 *
144 * \param metric_name String (UTF-8) name of the metric.
145 * \param value Value to send.
146 * \param sample_rate Percentage of samples to send.
147 * \since 12
148 */
149AST_OPTIONAL_API(void, ast_statsd_log_sample, (const char *metric_name,
150 intmax_t value, double sample_rate), {});
151
152
153#endif /* _ASTERISK_STATSD_H */
Optional API function macros.
#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)
Declare an optional API function with compiler attributes.
Definition: optional_api.h:233
#define AST_OPTIONAL_API(result, name, proto, stub)
Declare an optional API function.
Definition: optional_api.h:230
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
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.
Definition: res_statsd.c:241
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.
Definition: res_statsd.c:117
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
void ast_statsd_log(const char *metric_name, const char *metric_type, intmax_t value)
Send a stat to the configured statsd server.
Definition: res_statsd.c:232
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.
Definition: res_statsd.c:174
int value
Definition: syslog.c:37