[sr-dev] git:andrei/counters: counters: doc update

Module: sip-router Branch: andrei/counters Commit: 0c5cadddd86c31ce8021811ad4806c02200e21ce URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=0c5cadd… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; 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>