1. Counters Module

Andrei Pelinescu-Onciul

iptelorg GmbH

1.1. Overview
1.2. Parameters
1.2.1. script_counter
1.2.2. script_cnt_grp_name
1.3. Functions
1.3.1. cnt_inc([group.]name)
1.3.2. cnt_add([group.]name, number)
1.3.3. cnt_reset([group.]name)
1.4. counters RPC Functions
1.4.1. cnt.get group counter_name
1.4.2. cnt.reset group counter_name
1.4.3. cnt.grps_list
1.4.4. cnt.var_list group
1.4.5. cnt.grp_get_all
1.4.6. cnt.help group counter_name

1.1. Overview

This module exports counters/statistics manipulating script functions and RPCs.

1.2. Parameters

1.2.1. script_counter

Define a new counter that can be used from the script. The declaration might include a group in front of the counter name, separated with '.'. It might also include a counter description string (help message), separated from the name with a ' ' or ':'. If the group is missing, the group defined in the script_cnt_grp_name module parameter will be used (the default is "script"). If the description is missing, the default is "custom script counter". The format of the declaration is: [group.]name[( |:)description].

Example 1.  Create a new script_counter

modparam("counters", "script_counter", "foo")  # script.foo
modparam("counters", "script_counter", "test.bar")  # test.bar
modparam("counters", "script_counter", "baz example counter")  # script.baz
modparam("counters", "script_counter", "test.x:another example") # test.x

1.2.2. script_cnt_grp_name

Group name that will be used for the counters defined via the script_counter module parameter which do not have a specified group.

Default: "script".

Example 2.  Set script_cnt_grp_name in the config file

modparam("counters", "script_cnt_grp_name", "my_counters")

1.3. Functions

1.3.1.  cnt_inc([group.]name)

Increments the counter group.name. The counter must be defined using the script_counter module parameter. If the group name is missing, the group specified by the script_cnt_grp_name modparam will be used.

Example 3. cnt_inc usage

...
modparam("counters", "script_counter", "reqs")
modparam("counters", "script_counter", "out.reqs  forwarded requests")
...
route {
	cnt_inc("reqs");
	if (forward(uri:host, uri:port))
		cnt_inc("out.reqs");
...
}

1.3.2.  cnt_add([group.]name, number)

Adds number the counter group.name. The counter must be defined using the script_counter module parameter. If the group name is missing, the group specified by the script_cnt_grp_name modparam will be used.

Example 4. cnt_add usage

...
modparam("counters", "script_counter", "reqs10  reqs times 10")
...
route {
	cnt_add("reqs10", 10);
...
}

1.3.3.  cnt_reset([group.]name)

Resets the counter group.name. The counter must be defined using the script_counter module parameter. If the group name is missing, the group specified by the script_cnt_grp_name modparam will be used.

Example 5. cnt_reset usage

...
modparam("counters", "script_counter", "reqs")
...
route {
	if (...)
		cnt_reset("reqs");
...
}

1.4. counters RPC Functions

1.4.1.  cnt.get group counter_name

Get the value of the counter identified by group.counter_name.

Example 6. cnt.get grp counter_name usage

 $ sercmd cnt.get script foo

1.4.2.  cnt.reset group counter_name

Resets the counter identified by group.counter_name.

Example 7. cnt.reset grp name usage

 $ sercmd cnt.reset script foo

1.4.3.  cnt.grps_list

Lists all the declared counter groups.

Example 8. cnt.grps_list usage

 $ sercmd cnt.grps_list

1.4.4.  cnt.var_list group

Lists all the names of all the counters belonging to the specified group.

Example 9. cnt.var_list group usage

 $ sercmd cnt.var_list script

1.4.5.  cnt.grp_get_all

Lists all the counter names and their values in the specified group.

Example 10. cnt.var_list group usage

 $ sercmd cnt.grp_get_all script

1.4.6.  cnt.help group counter_name

Displays the counter description.

Example 11. cnt.help grp name usage

 $ sercmd cnt.help script foo