diff options
| -rw-r--r-- | include/osmocom/core/stats.h | 54 | ||||
| -rw-r--r-- | src/stats.c | 102 | ||||
| -rw-r--r-- | src/stats_statsd.c | 11 |
3 files changed, 145 insertions, 22 deletions
diff --git a/include/osmocom/core/stats.h b/include/osmocom/core/stats.h index 161b34ce..f50796c4 100644 --- a/include/osmocom/core/stats.h +++ b/include/osmocom/core/stats.h @@ -1,4 +1,3 @@ -/*! \file stats.h */ /* * (C) 2015 by Sysmocom s.f.m.c. GmbH * @@ -21,6 +20,10 @@ */ #pragma once +/*! \defgroup stats Statistics reporting + * @{ + * \file stats.h */ + /* a bit of a crude way to disable building/using this on (bare iron) * embedded systems. We cannot use the autoconf-defined HAVE_... macros * here, as that only works at library compile time, not at application @@ -40,42 +43,50 @@ struct osmo_stat_item_desc; struct rate_ctr_group; struct rate_ctr_desc; +/*! Statistics Class definitions */ enum osmo_stats_class { - OSMO_STATS_CLASS_UNKNOWN, - OSMO_STATS_CLASS_GLOBAL, - OSMO_STATS_CLASS_PEER, - OSMO_STATS_CLASS_SUBSCRIBER, + OSMO_STATS_CLASS_UNKNOWN, /*!< unknown class */ + OSMO_STATS_CLASS_GLOBAL, /*!< global counter/stat_item */ + OSMO_STATS_CLASS_PEER, /*!< peer in a communications link */ + OSMO_STATS_CLASS_SUBSCRIBER, /*!< subscriber */ }; +/*! Statistics Reporter Type */ enum osmo_stats_reporter_type { - OSMO_STATS_REPORTER_LOG, - OSMO_STATS_REPORTER_STATSD, + OSMO_STATS_REPORTER_LOG, /*!< libosmocore logging */ + OSMO_STATS_REPORTER_STATSD, /*!< statsd backend */ }; +/*! One statistics reporter instance. */ struct osmo_stats_reporter { + /*! Type of the reporter (log, statsd) */ enum osmo_stats_reporter_type type; + /*! Human-readable name of this reporter */ char *name; unsigned int have_net_config : 1; /* config */ - int enabled; - char *name_prefix; - char *dest_addr_str; - char *bind_addr_str; - int dest_port; - int mtu; + int enabled; /*!< is this reporter enabled */ + char *name_prefix; /*!< prefix for counter names */ + char *dest_addr_str; /*!< destination IP address */ + char *bind_addr_str; /*!< local bind IP address */ + int dest_port; /*!< destination (UDP) port */ + int mtu; /*!< Maximum Transmission Unit */ + + /*! Maximum class/index to report. FIXME: More details! */ enum osmo_stats_class max_class; /* state */ - int running; - struct sockaddr dest_addr; - int dest_addr_len; - struct sockaddr bind_addr; - int bind_addr_len; - int fd; - struct msgb *buffer; - int agg_enabled; + + int running; /*!< is this reporter running */ + struct sockaddr dest_addr; /*!< destination address of socket */ + int dest_addr_len; /*!< length of \a dest_addr in bytes */ + struct sockaddr bind_addr; /*!< local bind address of socket */ + int bind_addr_len; /*!< length of \a bind_addr in bytes */ + int fd; /*!< file descriptor of socket */ + struct msgb *buffer; /*!< message buffer for log output */ + int agg_enabled; /*!< is aggregation enabled? */ int force_single_flush; struct llist_head list; @@ -131,3 +142,4 @@ int osmo_stats_reporter_udp_open(struct osmo_stats_reporter *srep); int osmo_stats_reporter_udp_close(struct osmo_stats_reporter *srep); #endif /* unix */ +/*! @} */ diff --git a/src/stats.c b/src/stats.c index d9df2325..ff31ff6c 100644 --- a/src/stats.c +++ b/src/stats.c @@ -22,6 +22,46 @@ * */ +/*! \addtogroup stats + * @{ + * + * This module implements periodic reporting of statistics / counters. + * It supports the notion of multiple \ref osmo_stats_reporter objects + * which independently of each other can report statistics at different + * configurable intervals to different destinations. + * + * In order to use this facility, you have to call \ref + * osmo_stats_init() once at application start-up and then create one or + * more \ref osmo_stats_reporter, either using the direct API functions + * or by using the optional VTY bindings: + * + * - reporting to any of the libosmocore log targets + * \ref osmo_stats_reporter_create_log() creates a new stats_reporter + * which reports to the libosmcoore \ref logging subsystem. + * + * - reporting to statsd (a front-end proxy for the Graphite/Carbon + * metrics server + * \ref osmo_stats_reporter_create_statsd() creates a new stats_reporter + * which reports via UDP to statsd. + * + * You can either use the above API functions directly to create \ref + * osmo_stats_reporter instances, or you can use the VTY support + * contained in libosmovty. See the "stats" configuration node + * installed by osmo_stats_vty_Add_cmds(). + * + * An \ref osmo_stats_reporter reports statistics on all of the following + * libosmocore internal counter/statistics objects: + * - \ref osmo_counter + * - \ref rate_ctr + * - \ref osmo_stat_item + * + * You do not need to do anything in particular to expose a given + * counter or stat_item, they are all exported automatically via any + * \ref osmo_stats_reporter. If you have multiple \ref + * osmo_stats_reporter, they will each report all counters/stat_items. + * + * \file stats.c */ + #include "config.h" #if !defined(EMBEDDED) @@ -137,6 +177,8 @@ struct osmo_stats_reporter *osmo_stats_reporter_alloc(enum osmo_stats_reporter_t return srep; } +/*! Destroy a given stats_reporter. Takes care of first disabling it. + * \param[in] srep stats_reporter that shall be disabled + destroyed */ void osmo_stats_reporter_free(struct osmo_stats_reporter *srep) { osmo_stats_reporter_disable(srep); @@ -144,6 +186,8 @@ void osmo_stats_reporter_free(struct osmo_stats_reporter *srep) talloc_free(srep); } +/*! Initilize the stats reporting module; call this once in your program + * \param[in] ctx Talloc context from which stats related memory is allocated */ void osmo_stats_init(void *ctx) { osmo_stats_ctx = ctx; @@ -153,6 +197,10 @@ void osmo_stats_init(void *ctx) start_timer(); } +/*! Find a stats_reporter of given \a type and \a name. + * \param[in] type Type of stats_reporter to find + * \param[in] name Name of stats_reporter to find + * \returns stats_reporter matching \a type and \a name; NULL otherwise */ struct osmo_stats_reporter *osmo_stats_reporter_find(enum osmo_stats_reporter_type type, const char *name) { @@ -172,6 +220,10 @@ struct osmo_stats_reporter *osmo_stats_reporter_find(enum osmo_stats_reporter_ty #ifdef HAVE_SYS_SOCKET_H +/*! Set the remote (IP) address of a given stats_reporter. + * \param[in] srep stats_reporter whose remote address is to be set + * \param[in] addr String representation of remote IPv4 address + * \returns 0 on success; negative on error */ int osmo_stats_reporter_set_remote_addr(struct osmo_stats_reporter *srep, const char *addr) { int rc; @@ -197,6 +249,10 @@ int osmo_stats_reporter_set_remote_addr(struct osmo_stats_reporter *srep, const return update_srep_config(srep); } +/*! Set the remote (UDP) port of a given stats_reporter + * \param[in] srep stats_reporter whose remote address is to be set + * \param[in] port UDP port of remote statsd to which we report + * \returns 0 on success; negative on error */ int osmo_stats_reporter_set_remote_port(struct osmo_stats_reporter *srep, int port) { struct sockaddr_in *sock_addr = (struct sockaddr_in *)&srep->dest_addr; @@ -210,6 +266,10 @@ int osmo_stats_reporter_set_remote_port(struct osmo_stats_reporter *srep, int po return update_srep_config(srep); } +/*! Set the local (IP) address of a given stats_reporter. + * \param[in] srep stats_reporter whose remote address is to be set + * \param[in] addr String representation of local IP address + * \returns 0 on success; negative on error */ int osmo_stats_reporter_set_local_addr(struct osmo_stats_reporter *srep, const char *addr) { int rc; @@ -237,6 +297,10 @@ int osmo_stats_reporter_set_local_addr(struct osmo_stats_reporter *srep, const c return update_srep_config(srep); } +/*! Set the maximum transmission unit of a given stats_reporter. + * \param[in] srep stats_reporter whose remote address is to be set + * \param[in] mtu Maximum Transmission Unit of \a srep + * \returns 0 on success; negative on error */ int osmo_stats_reporter_set_mtu(struct osmo_stats_reporter *srep, int mtu) { if (!srep->have_net_config) @@ -262,6 +326,10 @@ int osmo_stats_reporter_set_max_class(struct osmo_stats_reporter *srep, return 0; } +/*! Set the reporting interval of a given stats_reporter (in seconds). + * \param[in] srep stats_reporter whose remote address is to be set + * \param[in] interval Reporting interval in seconds + * \returns 0 on success; negative on error */ int osmo_stats_set_interval(int interval) { if (interval <= 0) @@ -274,6 +342,10 @@ int osmo_stats_set_interval(int interval) return 0; } +/*! Set the name prefix of a given stats_reporter. + * \param[in] srep stats_reporter whose name prefix is to be set + * \param[in] prefix NAme perfix to pre-pend for any reported value + * \returns 0 on success; negative on error */ int osmo_stats_reporter_set_name_prefix(struct osmo_stats_reporter *srep, const char *prefix) { talloc_free(srep->name_prefix); @@ -283,6 +355,10 @@ int osmo_stats_reporter_set_name_prefix(struct osmo_stats_reporter *srep, const return update_srep_config(srep); } + +/*! Enable the given stats_reporter. + * \param[in] srep stats_reporter who is to be enabled + * \returns 0 on success; negative on error */ int osmo_stats_reporter_enable(struct osmo_stats_reporter *srep) { srep->enabled = 1; @@ -290,6 +366,9 @@ int osmo_stats_reporter_enable(struct osmo_stats_reporter *srep) return update_srep_config(srep); } +/*! Disable the given stats_reporter. + * \param[in] srep stats_reporter who is to be disabled + * \returns 0 on success; negative on error */ int osmo_stats_reporter_disable(struct osmo_stats_reporter *srep) { srep->enabled = 0; @@ -301,6 +380,9 @@ int osmo_stats_reporter_disable(struct osmo_stats_reporter *srep) #ifdef HAVE_SYS_SOCKET_H +/*! Open the UDP socket for given stats_reporter. + * \param[in] srep stats_reporter whose UDP socket is to be opened + * ]returns 0 on success; negative otherwise */ int osmo_stats_reporter_udp_open(struct osmo_stats_reporter *srep) { int sock; @@ -346,6 +428,9 @@ failed: return rc; } +/*! Closee the UDP socket for given stats_reporter. + * \param[in] srep stats_reporter whose UDP socket is to be closed + * ]returns 0 on success; negative otherwise */ int osmo_stats_reporter_udp_close(struct osmo_stats_reporter *srep) { int rc; @@ -361,6 +446,11 @@ int osmo_stats_reporter_udp_close(struct osmo_stats_reporter *srep) return rc == -1 ? -errno : 0; } +/*! Send given date to given stats_reporter. + * \param[in] srep stats_reporter whose UDP socket is to be opened + * \param[in] data string data to be sent + * \param[in] data_len Length of \a data in bytes + * \returns number of bytes on success; negative otherwise */ int osmo_stats_reporter_send(struct osmo_stats_reporter *srep, const char *data, int data_len) { @@ -379,6 +469,9 @@ int osmo_stats_reporter_send(struct osmo_stats_reporter *srep, const char *data, return rc; } +/*! Send current accumulated buffer to given stats_reporter. + * \param[in] srep stats_reporter whose UDP socket is to be opened + * \returns number of bytes on success; negative otherwise */ int osmo_stats_reporter_send_buffer(struct osmo_stats_reporter *srep) { int rc; @@ -397,6 +490,13 @@ int osmo_stats_reporter_send_buffer(struct osmo_stats_reporter *srep) /*** log reporter ***/ +/*! Create a stats_reporter that logs via libosmocore logging. + * A stats_reporter created via this function will simply print the statistics + * via the libosmocore logging framework, using DLSTATS subsystem and LOGL_INFO + * priority. The configuration of the libosmocore log targets define where this + * information will end up (ignored, text file, stderr, syslog, ...). + * \param[in] name Name of the to-be-created stats_reporter + * \returns stats_reporter on success; NULL on error */ struct osmo_stats_reporter *osmo_stats_reporter_create_log(const char *name) { struct osmo_stats_reporter *srep; @@ -626,3 +726,5 @@ int osmo_stats_report() } #endif /* !EMBEDDED */ + +/*! @} */ diff --git a/src/stats_statsd.c b/src/stats_statsd.c index 6e7be735..5145bf7a 100644 --- a/src/stats_statsd.c +++ b/src/stats_statsd.c @@ -1,4 +1,3 @@ -/*! \file stats_statsd.c */ /* * (C) 2015 by Sysmocom s.f.m.c. GmbH * @@ -22,6 +21,10 @@ * */ +/*! \addtogroup stats + * @{ + * \file stats_statsd.c */ + #include "config.h" #if !defined(EMBEDDED) @@ -46,6 +49,10 @@ static int osmo_stats_reporter_statsd_send_item(struct osmo_stats_reporter *srep const struct osmo_stat_item_group *statg, const struct osmo_stat_item_desc *desc, int64_t value); +/*! Create a stats_reporter reporting to statsd. This creates a stats_reporter + * instance which reports the related statistics data to statsd. + * \param[in] name Name of the to-be-created stats_reporter + * \returns stats_reporter on success; NULL on error */ struct osmo_stats_reporter *osmo_stats_reporter_create_statsd(const char *name) { struct osmo_stats_reporter *srep; @@ -172,3 +179,5 @@ static int osmo_stats_reporter_statsd_send_item(struct osmo_stats_reporter *srep desc->name, value, unit); } #endif /* !EMBEDDED */ + +/* @} */ |