!!!!!Documentation -> [[Documentation.Development-Manual-3-1|Development Manual 3.1]] -> Statistics API
This page has been visited {$PageCount} times.
(:title OpenSIPS Development - Statistics API:)
----
(:allVersions Development-Manual-API-Statistics 3.1:)

\\

|| %color=#185662%[+'''Statistics API'''+]%% ||

----

(:toc-float Table of Content:)

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''' :

(:source lang=C -link -getcode :)
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;
(:sourceend:)
\\
For example, the core stats exported by OpenSIPS are defined in the following array :

(:source lang=C -link -getcode :)
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}
};
(:sourceend:)
\\

>>tip<<
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

(:source lang=C -link -getcode :)
/*
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;
(:sourceend:)
\\
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<<
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 :

(:source lang=C -link -getcode :)
/*
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)
(:sourceend:)

>>important<<
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 ).
>><<

\\

>>tip<<
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:
>><<