mirror of https://gerrit.osmocom.org/libosmocore
[doc] Add Doxygen API documentation for stats.c and stats_statsd.c
Change-Id: I8e49505f5c19beac90290fdba8821714e8eecd97
This commit is contained in:
parent
17bbaa324b
commit
eb5b6ce444
|
@ -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 */
|
||||
/*! @} */
|
||||
|
|
102
src/stats.c
102
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 */
|
||||
|
||||
/*! @} */
|
||||
|
|
|
@ -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 */
|
||||
|
||||
/* @} */
|
||||
|
|
Loading…
Reference in New Issue