openSIPS | Documentation / OpenSIPS Development

Documentation -> Development Manual -> Statistics API

This page has been visited 296 times.

Statistics API

OpenSIPS exposes a statistics API that can be used both from the core or the modules. The statistics are essentially counters that will be internally incremented/decremented by OpenSIPS and that can be fetched by the outside world ( via the MI interface ) for understanding the OpenSIPS load / health status / etc.
The advantages of using the OpenSIPS Statistics API instead of regular counters is :

easily fetched from the MI Interface
on supported architectures, the statistics do not use an explicit lock ( the consistency is ensured by employing assembly code ), thus you will get better performance

The most important structures used for extending statistics are exported by statistics.h :

typedef struct stat_export_ {
char* name; /* null terminated statistic name */
unsigned short flags; /* flags */
stat_var** stat_pointer; /* pointer to the variable's mem location *
* NOTE - it's in shm mem */
} stat_export_t;

For example, the core stats exported by OpenSIPS are defined in the following array :

stat_var* rcv_reqs;
stat_var* rcv_rpls;
stat_var* fwd_reqs;
stat_var* fwd_rpls;
stat_var* drp_reqs;
stat_var* drp_rpls;
stat_var* err_reqs;
stat_var* err_rpls;
stat_var* bad_URIs;
stat_var* unsupported_methods;
stat_var* bad_msg_hdr;

stat_export_t core_stats[] = {
{"rcv_requests" , 0, &rcv_reqs },
{"rcv_replies" , 0, &rcv_rpls },
{"fwd_requests" , 0, &fwd_reqs },
{"fwd_replies" , 0, &fwd_rpls },
{"drop_requests" , 0, &drp_reqs },
{"drop_replies" , 0, &drp_rpls },
{"err_requests" , 0, &err_reqs },
{"err_replies" , 0, &err_rpls },
{"bad_URIs_rcvd", 0, &bad_URIs },
{"unsupported_methods", 0, &unsupported_methods },
{"bad_msg_hdr", 0, &bad_msg_hdr },
{"timestamp", STAT_IS_FUNC, (stat_var**)get_ticks },
{0,0,0}
};

As note from the above structure, statistics can either be a simple counter ( eg. rcv_requests ), but it can also be a function. Statistics function might come in handy when the developer needs to do extra processing on the raw counters before providing the final output.

After defining your array of statistics that you want to export, one should use the following for exporting the stats to be accessible by all

/*
Parameters :
module - a string describing the module the current statistics belong to. Will be used when fetching the statistics via MI
stats - the statistics to be registered
Returns :
0 in case of success, negative in case of error
*/
int register_module_stats(char *module, stat_export_t *stats;

Note that register_module_stats will export the statistics, and also allocate them in SHM memory, for them to be accessible by all OpenSIPS processes.

Important to note here that all the above statistics related functions MUST be called in the context of the attendant process before forking is done.

At runtime, the developer has access to the following functions for operating on statistics :

/*
Parameters :
var : the statistics to be updated
n : the value ( if positive -> stat will be increment. negative -> stat will be decremented )
*/
void update_stat(stat_var* var, int n);

/*
Parameters :
var : the statistics to be reseted
*/
void reset_stat(stat_var* var);

/*
Parameters :
var : the statistics to be fetched
Returns :
statistic value
*/
unsigned long get_stat_val(stat_var* var)

All statistics related code should be guarded by #ifdef STATISTICS , since the statistics are not a mandatory part of the OpenSIPS core ( they can be disabled from within menuconfig ).

For fetching the mynewstat statistic exported by the mynewmod module, one can use the opensipsctl like this :
opensipsctl fifo get_statistics mynewmod mynewstat
For fetching all the statistics exported by the mynewmod module, you can use
opensipsctl fifo get_statistics mynewmod:

From openSIPS

Documentation: OpenSIPS Development - Statistics API

Documentation -> Development Manual -> Statistics API