Documentation -> Development Manual 3.4 -> Statistics API

This page has been visited 777 times. (:title OpenSIPS Development - Statistics API:)

(:allVersions Development-Manual-API-Statistics 3.4:)

(: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:)

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.

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