git.sip-router.org Git - sip-router/blob - src/modules/counters/README

   1 Counters Module
   2
   3 Andrei Pelinescu-Onciul
   4
   5    iptelorg GmbH
   6
   7    Copyright © 2010 iptelorg GmbH
   8      __________________________________________________________________
   9
  10    Table of Contents
  11
  12    1. Admin Guide
  13
  14         1. Overview
  15         2. Parameters
  16
  17               2.1. script_counter
  18               2.2. script_cnt_grp_name
  19
  20         3. Functions
  21
  22               3.1. cnt_inc([group.]name)
  23               3.2. cnt_add([group.]name, number)
  24               3.3. cnt_reset([group.]name)
  25
  26         4. RPC Commands
  27
  28               4.1. cnt.get
  29               4.2. cnt.reset
  30               4.3. cnt.list_groups
  31               4.4. cnt.grps_list
  32               4.5. cnt.list_vars
  33               4.6. cnt.var_list
  34               4.7. cnt.get_vars
  35               4.8. cnt.grp_get_all
  36               4.9. cnt.help
  37
  38    List of Examples
  39
  40    1.1. Create a new script_counter
  41    1.2. Set script_cnt_grp_name in the config file
  42    1.3. cnt_inc usage
  43    1.4. cnt_add usage
  44    1.5. cnt_reset usage
  45    1.6. cnt.get grp counter_name usage
  46    1.7. cnt.reset grp name usage
  47    1.8. cnt.list_groups usage
  48    1.9. cnt.list_vars group usage
  49    1.10. cnt.get_vars group usage
  50    1.11. cnt.help grp name usage
  51
  52 Chapter 1. Admin Guide
  53
  54    Table of Contents
  55
  56    1. Overview
  57    2. Parameters
  58
  59         2.1. script_counter
  60         2.2. script_cnt_grp_name
  61
  62    3. Functions
  63
  64         3.1. cnt_inc([group.]name)
  65         3.2. cnt_add([group.]name, number)
  66         3.3. cnt_reset([group.]name)
  67
  68    4. RPC Commands
  69
  70         4.1. cnt.get
  71         4.2. cnt.reset
  72         4.3. cnt.list_groups
  73         4.4. cnt.grps_list
  74         4.5. cnt.list_vars
  75         4.6. cnt.var_list
  76         4.7. cnt.get_vars
  77         4.8. cnt.grp_get_all
  78         4.9. cnt.help
  79
  80 1. Overview
  81
  82    This module exports counters/statistics manipulating script functions
  83    and RPCs.
  84
  85 2. Parameters
  86
  87    2.1. script_counter
  88    2.2. script_cnt_grp_name
  89
  90 2.1. script_counter
  91
  92    Define a new counter that can be used from the script. The declaration
  93    might include a group in front of the counter name, separated with '.'.
  94    It might also include a counter description string (help message),
  95    separated from the name with a ' ' or ':'. If the group is missing, the
  96    group defined in the script_cnt_grp_name module parameter will be used
  97    (the default is "script"). If the description is missing, the default
  98    is "custom script counter". The format of the declaration is:
  99    [group.]name[( |:)description].
 100
 101    Example 1.1.  Create a new script_counter
 102 modparam("counters", "script_counter", "foo")  # script.foo
 103 modparam("counters", "script_counter", "test.bar")  # test.bar
 104 modparam("counters", "script_counter", "baz example counter")  # script.baz
 105 modparam("counters", "script_counter", "test.x:another example") # test.x
 106
 107 2.2. script_cnt_grp_name
 108
 109    Group name that will be used for the counters defined via the
 110    script_counter module parameter which do not have a specified group.
 111
 112    Default: "script".
 113
 114    Example 1.2.  Set script_cnt_grp_name in the config file
 115 modparam("counters", "script_cnt_grp_name", "my_counters")
 116
 117 3. Functions
 118
 119    3.1. cnt_inc([group.]name)
 120    3.2. cnt_add([group.]name, number)
 121    3.3. cnt_reset([group.]name)
 122
 123 3.1.  cnt_inc([group.]name)
 124
 125    Increments the counter group.name. The counter must be defined using
 126    the script_counter module parameter. If the group name is missing, the
 127    group specified by the script_cnt_grp_name modparam will be used.
 128
 129    Example 1.3. cnt_inc usage
 130 ...
 131 modparam("counters", "script_counter", "reqs")
 132 modparam("counters", "script_counter", "out.reqs  forwarded requests")
 133 ...
 134 route {
 135         cnt_inc("reqs");
 136         if (forward(uri:host, uri:port))
 137                 cnt_inc("out.reqs");
 138 ...
 139 }
 140
 141 3.2.  cnt_add([group.]name, number)
 142
 143    Adds number the counter group.name. The counter must be defined using
 144    the script_counter module parameter. If the group name is missing, the
 145    group specified by the script_cnt_grp_name modparam will be used.
 146
 147    Example 1.4. cnt_add usage
 148 ...
 149 modparam("counters", "script_counter", "reqs10  reqs times 10")
 150 ...
 151 route {
 152         cnt_add("reqs10", 10);
 153 ...
 154 }
 155
 156 3.3.  cnt_reset([group.]name)
 157
 158    Resets the counter group.name. The counter must be defined using the
 159    script_counter module parameter. If the group name is missing, the
 160    group specified by the script_cnt_grp_name modparam will be used.
 161
 162    Example 1.5. cnt_reset usage
 163 ...
 164 modparam("counters", "script_counter", "reqs")
 165 ...
 166 route {
 167         if (...)
 168                 cnt_reset("reqs");
 169 ...
 170 }
 171
 172 4. RPC Commands
 173
 174    4.1. cnt.get
 175    4.2. cnt.reset
 176    4.3. cnt.list_groups
 177    4.4. cnt.grps_list
 178    4.5. cnt.list_vars
 179    4.6. cnt.var_list
 180    4.7. cnt.get_vars
 181    4.8. cnt.grp_get_all
 182    4.9. cnt.help
 183
 184 4.1.  cnt.get
 185
 186    Get the value of the counter identified by group.counter_name.
 187
 188    Prototype: cnt.get group counter_name
 189
 190    Example 1.6. cnt.get grp counter_name usage
 191  $ kamcmd cnt.get script foo
 192
 193 4.2.  cnt.reset
 194
 195    Resets the counter identified by group.counter_name.
 196
 197    Prototype: cnt.reset group counter_name
 198
 199    Example 1.7. cnt.reset grp name usage
 200  $ kamcmd cnt.reset script foo
 201
 202 4.3.  cnt.list_groups
 203
 204    Lists all the declared counter groups.
 205
 206    Prototype: cnt.list_groups
 207
 208    Example 1.8. cnt.list_groups usage
 209  $ kamcmd cnt.list_groups
 210
 211 4.4.  cnt.grps_list
 212
 213    Alias to cnt.list_groups.
 214
 215 4.5.  cnt.list_vars
 216
 217    Lists all the names of all the counters belonging to the specified
 218    group.
 219
 220    Prototype: cnt.list_vars group
 221
 222    Example 1.9. cnt.list_vars group usage
 223  $ kamcmd cnt.list_vars tmx
 224
 225 4.6.  cnt.var_list
 226
 227    Alias to cnt.list_vars.
 228
 229 4.7.  cnt.get_vars
 230
 231    Lists all the counter names and their values in the specified group.
 232
 233    Prototype: cnt.get_vars group
 234
 235    Example 1.10. cnt.get_vars group usage
 236  $ kamcmd cnt.get_vars script
 237
 238 4.8.  cnt.grp_get_all
 239
 240    Alias to cnt.get_vars.
 241
 242 4.9.  cnt.help
 243
 244    Displays the counter description.
 245
 246    Prototype: cnt.help group counter_name
 247
 248    Example 1.11. cnt.help grp name usage
 249  $ kamcmd cnt.help script foo