modules: readme files regenerated - counters ...
[sip-router] / 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