Example of how to use the Stasis message bus

In order to get people familiar with the Stasis message bus, it would
be useful to have something of a tutorial. Since I'm not clever enough
to think of some cool integration we could do with Twitter, I settled
for something that might actually be useful.

This patch adds a res_statsd.so module, which implements a basic
statsd[1] client. Statsd is a very simple statistics gathering server,
which can publish its results to a backend graphing engine, like
Graphite[2]. There are several different Statsd server
implementations[3], so you can pick what works best for your
environment.

The actual example of how to use the Stasis message bus is in
res_chan_stats.so. This module demonstrates how to use subscriptions
and the message router by monitoring messages and posting channels
stats to the statsd server.

A wiki page walking through res_chan_stats.so is forthcoming.

 [1]: https://github.com/etsy/statsd/
 [2]: http://graphite.readthedocs.org/en/latest/
 [3]: http://joemiller.me/2011/09/21/list-of-statsd-server-implementations/

Review: https://reviewboard.asterisk.org/r/2460/


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@386624 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 90 insertions, 0 deletions

diff --git a/include/asterisk/statsd.h b/include/asterisk/statsd.h
new file mode 100644
index 000000000..8e5e2f987
--- /dev/null
+++ b/include/asterisk/statsd.h
@@ -0,0 +1,85 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2013, Digium, Inc.
+ *
+ * David M. Lee, II <dlee@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _ASTERISK_STATSD_H
+#define _ASTERISK_STATSD_H
+
+/*!
+ * \brief Support for publishing to a statsd server.
+ *
+ * \author David M. Lee, II <dlee@digium.com>
+ * \since 12
+ */
+
+#include "asterisk/optional_api.h"
+
+/*! An instantaneous measurement of a value. */
+#define AST_STATSD_GUAGE "g"
+/*! A change in a value. */
+#define AST_STATSD_COUNTER "c"
+/*! Measure of milliseconds. */
+#define AST_STATSD_TIMER "ms"
+/*! Distribution of values over time. */
+#define AST_STATSD_HISTOGRAM "h"
+/*! Events over time. Sorta like increment-only counters. */
+#define AST_STATSD_METER "m"
+
+/*!
+ * \brief Send a stat to the configured statsd server.
+ *
+ * The is 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.
+ *
+ * \param metric_name String (UTF-8) name of the metric.
+ * \param type_str Type of metric to send.
+ * \param value Value to send.
+ * \param sample_rate Percentage of samples to send.
+ * \since 12
+ */
+AST_OPTIONAL_API(void, ast_statsd_log_full, (const char *metric_name,
+	const char *metric_type, intmax_t value, double sample_rate), {});
+
+/*!
+ * \brief Send a stat to the configured statsd server.
+ * \param metric_name String (UTF-8) name of the metric.
+ * \param metric_type Type of metric to send.
+ * \param value Value to send.
+ * \since 12
+ */
+AST_OPTIONAL_API(void, ast_statsd_log, (const char *metric_name,
+	const char *metric_type, intmax_t value), {});
+
+/*!
+ * \brief Send a random sampling of a stat to the configured statsd server.
+ *
+ * The type of sampled metrics is always \ref AST_STATSD_COUNTER. The given
+ * \a 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.
+ *
+ * \param metric_name String (UTF-8) name of the metric.
+ * \param value Value to send.
+ * \param sample_rate Percentage of samples to send.
+ * \since 12
+ */
+AST_OPTIONAL_API(void, ast_statsd_log_sample, (const char *metric_name,
+		intmax_t value, double sample_rate), {});
+
+
+#endif /* _ASTERISK_STATSD_H */
+
diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index f93f563ac..9452dd5fb 100644
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -458,6 +458,11 @@ char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
 
 long int ast_random(void);
 
+/*!
+ * \brief Returns a random number between 0.0 and 1.0, inclusive.
+ * \since 12
+ */
+#define ast_random_double() (((double)ast_random()) / RAND_MAX)
 
 /*!
  * \brief free() wrapper