Counters Module

Andrei Pelinescu-Onciul

iptelorg GmbH

Table of Contents

1. Admin Guide
1. Overview
2. Parameters
2.1. script_counter
2.2. script_cnt_grp_name
3. Functions
3.1. cnt_inc([group.]name)
3.2. cnt_add([group.]name, number)
3.3. cnt_reset([group.]name)
4. RPC Commands
4.1. cnt.get
4.2. cnt.reset
4.3. cnt.list_groups
4.4. cnt.grps_list
4.5. cnt.list_vars
4.6. cnt.var_list
4.7. cnt.get_vars
4.8. cnt.grp_get_all
4.9. cnt.help

List of Examples

1.1. Create a new script_counter
1.2. Set script_cnt_grp_name in the config file
1.3. cnt_inc usage
1.4. cnt_add usage
1.5. cnt_reset usage
1.6. cnt.get grp counter_name usage
1.7. cnt.reset grp name usage
1.8. cnt.list_groups usage
1.9. cnt.list_vars group usage
1.10. cnt.get_vars group usage
1.11. cnt.help grp name usage

Chapter 1. Admin Guide

1. Overview

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

2. Parameters

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

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 1.2.  Set script_cnt_grp_name in the config file

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

3. Functions

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 1.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");
...
}

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 1.4. cnt_add usage

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

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 1.5. cnt_reset usage

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

4. RPC Commands

4.1.  cnt.get

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

Prototype: cnt.get group counter_name

Example 1.6. cnt.get grp counter_name usage

 $ kamcmd cnt.get script foo

4.2.  cnt.reset

Resets the counter identified by group.counter_name.

Prototype: cnt.reset group counter_name

Example 1.7. cnt.reset grp name usage

 $ kamcmd cnt.reset script foo

4.3.  cnt.list_groups

Lists all the declared counter groups.

Prototype: cnt.list_groups

Example 1.8. cnt.list_groups usage

 $ kamcmd cnt.list_groups

4.4.  cnt.grps_list

Alias to cnt.list_groups.

4.5.  cnt.list_vars

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

Prototype: cnt.list_vars group

Example 1.9. cnt.list_vars group usage

 $ kamcmd cnt.list_vars tmx

4.6.  cnt.var_list

Alias to cnt.list_vars.

4.7.  cnt.get_vars

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

Prototype: cnt.get_vars group

Example 1.10. cnt.get_vars group usage

 $ kamcmd cnt.get_vars script

4.8.  cnt.grp_get_all

Alias to cnt.get_vars.

4.9.  cnt.help

Displays the counter description.

Prototype: cnt.help group counter_name

Example 1.11. cnt.help grp name usage

 $ kamcmd cnt.help script foo