[sr-dev] git:andrei/counters: counters: doc update
Andrei Pelinescu-Onciul
andrei at iptel.org
Mon Aug 9 19:09:11 CEST 2010
Module: sip-router
Branch: andrei/counters
Commit: 0c5cadddd86c31ce8021811ad4806c02200e21ce
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=0c5cadddd86c31ce8021811ad4806c02200e21ce
Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date: Mon Aug 9 17:41:25 2010 +0200
counters: doc update
- document the new format used by the script_counter modparam and
by the script functions.
- document the new cnt.help rpc.
---
modules/counters/README | 60 ++++++++++++++++++++++++-----------
modules/counters/doc/functions.xml | 24 ++++++++++----
modules/counters/doc/params.xml | 23 ++++++++++---
modules/counters/doc/rpc.xml | 13 ++++++++
4 files changed, 88 insertions(+), 32 deletions(-)
diff --git a/modules/counters/README b/modules/counters/README
index 025f400..59b3fc6 100644
--- a/modules/counters/README
+++ b/modules/counters/README
@@ -17,9 +17,9 @@ Andrei Pelinescu-Onciul
1.3. Functions
- 1.3.1. cnt_inc(name)
- 1.3.2. cnt_add(name, number)
- 1.3.3. cnt_reset(name)
+ 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
@@ -28,6 +28,7 @@ Andrei Pelinescu-Onciul
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
@@ -41,17 +42,25 @@ Andrei Pelinescu-Onciul
1.2.1. script_counter
- Define a new counter that can be used from the script. The default
- group name for the counter is "script" (it can be changed using the
- script_cnt_grp_name module parameter).
+ 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")
+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 all the counters defined via the
- script_counter module parameter.
+ 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".
@@ -63,38 +72,44 @@ modparam("counters", "script_cnt_grp_name", "my_counters")
Revision History
Revision $Revision$ $Date$
-1.3.1. cnt_inc(name)
+1.3.1. cnt_inc([group.]name)
- Increments the counter name. The counter must be defined using the
- script_counter module parameter.
+ 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(name, number)
+1.3.2. cnt_add([group.]name, number)
- Adds number the counter name. The counter must be defined using the
- script_counter module parameter.
+ 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")
+modparam("counters", "script_counter", "reqs10 reqs times 10")
...
route {
cnt_add("reqs10", 10);
...
}
-1.3.3. cnt_reset(name)
+1.3.3. cnt_reset([group.]name)
- Resets the counter name. The counter must be defined using the
- script_counter module parameter.
+ 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
...
@@ -146,3 +161,10 @@ route {
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
diff --git a/modules/counters/doc/functions.xml b/modules/counters/doc/functions.xml
index 0138e68..a004872 100644
--- a/modules/counters/doc/functions.xml
+++ b/modules/counters/doc/functions.xml
@@ -23,21 +23,26 @@
<section id="cnt_inc">
<title>
- <function>cnt_inc(name)</function>
+ <function>cnt_inc([group.]name)</function>
</title>
<para>
- Increments the counter <emphasis>name</emphasis>. The counter
+ Increments the counter <emphasis>group.name</emphasis>. The counter
must be defined using the <varname>script_counter</varname>
module parameter.
+ If the group name is missing, the group specified by the
+ <varname>script_cnt_grp_name</varname> modparam will be used.
</para>
<example>
<title><function>cnt_inc</function> usage</title>
<programlisting>
...
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");
...
}
</programlisting>
@@ -46,18 +51,21 @@ route {
<section id="cnt_add">
<title>
- <function>cnt_add(name, number)</function>
+ <function>cnt_add([group.]name, number)</function>
</title>
<para>
- Adds <emphasis>number</emphasis> the counter <emphasis>name</emphasis>.
+ Adds <emphasis>number</emphasis> the counter
+ <emphasis>group.name</emphasis>.
The counter must be defined using the
<varname>script_counter</varname> module parameter.
+ If the group name is missing, the group specified by the
+ <varname>script_cnt_grp_name</varname> modparam will be used.
</para>
<example>
<title><function>cnt_add</function> usage</title>
<programlisting>
...
-modparam("counters", "script_counter", "reqs10")
+modparam("counters", "script_counter", "reqs10 reqs times 10")
...
route {
cnt_add("reqs10", 10);
@@ -69,12 +77,14 @@ route {
<section id="cnt_reset">
<title>
- <function>cnt_reset(name)</function>
+ <function>cnt_reset([group.]name)</function>
</title>
<para>
- Resets the counter <emphasis>name</emphasis>. The counter
+ Resets the counter <emphasis>group.name</emphasis>. The counter
must be defined using the <varname>script_counter</varname>
module parameter.
+ If the group name is missing, the group specified by the
+ <varname>script_cnt_grp_name</varname> modparam will be used.
</para>
<example>
<title><function>cnt_reset</function> usage</title>
diff --git a/modules/counters/doc/params.xml b/modules/counters/doc/params.xml
index 52c1ba9..e8b1510 100644
--- a/modules/counters/doc/params.xml
+++ b/modules/counters/doc/params.xml
@@ -22,16 +22,26 @@
<title><varname>script_counter</varname></title>
<para>
Define a new counter that can be used from the script.
- The default group name for the counter is "script"
- (it can be changed using the
- <varname>script_cnt_grp_name</varname> module parameter).
+ 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
+ <varname>script_cnt_grp_name</varname> 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].
</para>
<example>
<title>
Create a new <varname>script_counter</varname>
</title>
<programlisting>
-modparam("counters", "script_counter", "foo")
+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
</programlisting>
</example>
</section>
@@ -39,8 +49,9 @@ modparam("counters", "script_counter", "foo")
<section id="scrip_cnt_grp_name">
<title><varname>script_cnt_grp_name</varname></title>
<para>
- Group name that will be used for all the counters defined
- via the <varname>script_counter</varname> module parameter.
+ Group name that will be used for the counters defined
+ via the <varname>script_counter</varname> module parameter which
+ do not have a specified group.
</para>
<para>
Default: "script".
diff --git a/modules/counters/doc/rpc.xml b/modules/counters/doc/rpc.xml
index 9782ce0..a01e6bb 100644
--- a/modules/counters/doc/rpc.xml
+++ b/modules/counters/doc/rpc.xml
@@ -85,5 +85,18 @@
</example>
</section>
+ <section id="cnt.help">
+ <title> <function>cnt.help group counter_name</function></title>
+ <para>
+ Displays the counter description.
+ </para>
+ <example>
+ <title><function>cnt.help grp name</function> usage</title>
+ <programlisting>
+ $ &sercmd; cnt.help script foo
+ </programlisting>
+ </example>
+ </section>
+
</section>
More information about the sr-dev
mailing list