counters: added docs

modules/counters/README

@@ -0,0 +1,148 @@
+1. Counters Module
+
+Andrei Pelinescu-Onciul
+
+   iptelorg GmbH
+
+   Copyright © 2010 iptelorg GmbH
+   Revision History
+   Revision $Revision$ $Date$
+     __________________________________________________________________
+
+   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(name)
+        1.3.2. cnt_add(name, number)
+        1.3.3. cnt_reset(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.1. Overview
+
+   This module exports counters/statistics manipulating script functions
+   and RPCs.
+
+1.2. Parameters
+
+   Revision History
+   Revision $Revision$ $Date$
+
+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).
+
+   Example 1.  Create a new script_counter
+modparam("counters", "script_counter", "foo")
+
+1.2.2. script_cnt_grp_name
+
+   Group name that will be used for all the counters defined via the
+   script_counter module parameter.
+
+   Default: "script".
+
+   Example 2.  Set script_cnt_grp_name in the config file
+modparam("counters", "script_cnt_grp_name", "my_counters")
+
+1.3. Functions
+
+   Revision History
+   Revision $Revision$ $Date$
+
+1.3.1.  cnt_inc(name)
+
+   Increments the counter name. The counter must be defined using the
+   script_counter module parameter.
+
+   Example 3. cnt_inc usage
+...
+modparam("counters", "script_counter", "reqs")
+...
+route {
+        cnt_inc("reqs");
+...
+}
+
+1.3.2.  cnt_add(name, number)
+
+   Adds number the counter name. The counter must be defined using the
+   script_counter module parameter.
+
+   Example 4. cnt_add usage
+...
+modparam("counters", "script_counter", "reqs10")
+...
+route {
+        cnt_add("reqs10", 10);
+...
+}
+
+1.3.3.  cnt_reset(name)
+
+   Resets the counter name. The counter must be defined using the
+   script_counter module parameter.
+
+   Example 5. cnt_reset usage
+...
+modparam("counters", "script_counter", "reqs")
+...
+route {
+        if (...)
+                cnt_reset("reqs");
+...
+}
+
+1.4. counters RPC Functions
+
+   Revision History
+   Revision $Revision$ $Date$
+
+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

modules/counters/doc/Makefile

@@ -0,0 +1,4 @@
+docs = counters.xml
+
+docbook_dir=../../../docbook
+include $(docbook_dir)/Makefile.module

modules/counters/doc/counters.xml

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!ENTITY % local.common.attrib
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
+	 <!-- Include general documentation entities -->
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+	 %docentities;
+	]
+>
+
+<section id="counters" xmlns:xi="http://www.w3.org/2001/XInclude">
+	<sectioninfo>
+	<authorgroup>
+		<author>
+		<firstname>Andrei</firstname>
+		<surname>Pelinescu-Onciul</surname>
+		<affiliation><orgname>iptelorg GmbH</orgname></affiliation>
+		<address>
+			<email>[email protected]</email>
+		</address>
+		</author>
+	</authorgroup>
+	<copyright>
+		<year>2010</year>
+		<holder>iptelorg GmbH</holder>
+	</copyright>
+	<revhistory>
+		<revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+		</revision>
+	</revhistory>
+	</sectioninfo>
+
+	<title>Counters Module</title>
+
+	<section id="cnts.overview">
+	<title>Overview</title>
+	<para>
+		This module exports counters/statistics manipulating script functions
+		and RPCs.
+	</para>
+	</section>
+
+	<xi:include href="params.xml"/>
+	<xi:include href="functions.xml"/>
+	<xi:include href="rpc.xml"/>
+
+</section>
+

modules/counters/doc/functions.xml

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!ENTITY % local.common.attrib
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
+	 <!-- Include general documentation entities -->
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+	 %docentities;
+	]
+>
+
+<section id="cnts.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
+	 <sectioninfo>
+	<revhistory>
+		<revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+		</revision>
+	</revhistory>
+	</sectioninfo>
+
+	<title>Functions</title>
+
+	<section id="cnt_inc">
+	<title>
+		<function>cnt_inc(name)</function>
+	</title>
+	<para>
+		Increments the counter <emphasis>name</emphasis>. The counter
+		must be defined using the <varname>script_counter</varname>
+		module parameter.
+	</para>
+	<example>
+		<title><function>cnt_inc</function> usage</title>
+		<programlisting>
+...
+modparam("counters", "script_counter", "reqs")
+...
+route {
+	cnt_inc("reqs");
+...
+}
+		</programlisting>
+	</example>
+	</section>
+
+	<section id="cnt_add">
+	<title>
+		<function>cnt_add(name, number)</function>
+	</title>
+	<para>
+		Adds <emphasis>number</emphasis> the counter <emphasis>name</emphasis>.
+		The counter must be defined using the
+		<varname>script_counter</varname> module parameter.
+	</para>
+	<example>
+		<title><function>cnt_add</function> usage</title>
+		<programlisting>
+...
+modparam("counters", "script_counter", "reqs10")
+...
+route {
+	cnt_add("reqs10", 10);
+...
+}
+		</programlisting>
+	</example>
+	</section>
+
+	<section id="cnt_reset">
+	<title>
+		<function>cnt_reset(name)</function>
+	</title>
+	<para>
+		Resets the counter <emphasis>name</emphasis>. The counter
+		must be defined using the <varname>script_counter</varname>
+		module parameter.
+	</para>
+	<example>
+		<title><function>cnt_reset</function> usage</title>
+		<programlisting>
+...
+modparam("counters", "script_counter", "reqs")
+...
+route {
+	if (...)
+		cnt_reset("reqs");
+...
+}
+		</programlisting>
+	</example>
+	</section>
+
+</section>

modules/counters/doc/params.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!-- Include general documentation entities -->
+		<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+		%docentities;
+	]
+>
+
+<section id="cnts.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
+	<sectioninfo>
+		<revhistory>
+			<revision>
+				<revnumber>$Revision$</revnumber>
+				<date>$Date$</date>
+			</revision>
+		</revhistory>
+	</sectioninfo>
+	<title>Parameters</title>
+
+	<section id="scrip_counter">
+		<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).
+		</para>
+		<example>
+			<title>
+				Create a new <varname>script_counter</varname>
+			</title>
+			<programlisting>
+modparam("counters", "script_counter", "foo")
+			</programlisting>
+		</example>
+	</section>
+
+	<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.
+		</para>
+		<para>
+			Default: "script".
+		</para>
+		<example>
+			<title>
+				Set <varname>script_cnt_grp_name</varname> in the config file
+			</title>
+			<programlisting>
+modparam("counters", "script_cnt_grp_name", "my_counters")
+			</programlisting>
+		</example>
+	</section>
+
+</section>

modules/counters/doc/rpc.xml

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+	[ <!-- Include general documentation entities -->
+		<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+		%docentities;
+	]
+>
+
+<section id="cnts.rpcs" xmlns:xi="http://www.w3.org/2001/XInclude">
+	<sectioninfo>
+		<revhistory>
+			<revision>
+				<revnumber>$Revision$</revnumber>
+				<date>$Date$</date>
+			</revision>
+		</revhistory>
+	</sectioninfo>
+	<title>counters RPC Functions</title>
+
+	<section id="cnt.get">
+		<title> <function>cnt.get group counter_name</function></title>
+		<para>
+			Get the value of the counter identified by group.counter_name.
+		</para>
+		<example>
+			<title><function>cnt.get grp counter_name</function> usage</title>
+			<programlisting>
+ $ &sercmd; cnt.get script foo
+			</programlisting>
+		</example>
+	</section>
+
+	<section id="cnt.reset">
+		<title> <function>cnt.reset group counter_name</function></title>
+		<para>
+			Resets the counter identified by group.counter_name.
+		</para>
+		<example>
+			<title><function>cnt.reset grp name</function> usage</title>
+			<programlisting>
+ $ &sercmd; cnt.reset script foo
+			</programlisting>
+		</example>
+	</section>
+
+	<section id="cnt.grps_list">
+		<title> <function>cnt.grps_list</function></title>
+		<para>
+			Lists all the declared counter groups.
+		</para>
+		<example>
+			<title><function>cnt.grps_list</function> usage</title>
+			<programlisting>
+ $ &sercmd; cnt.grps_list
+			</programlisting>
+		</example>
+	</section>
+
+	<section id="cnt.var_list">
+		<title> <function>cnt.var_list group</function></title>
+		<para>
+			Lists all the names of all the counters belonging to the
+			specified group.
+		</para>
+		<example>
+			<title><function>cnt.var_list group</function> usage</title>
+			<programlisting>
+ $ &sercmd; cnt.var_list script
+			</programlisting>
+		</example>
+	</section>
+
+	<section id="cnt.grp_get_all">
+		<title> <function>cnt.grp_get_all</function></title>
+		<para>
+			Lists all the counter names and their values in the
+			specified group.
+		</para>
+		<example>
+			<title><function>cnt.var_list group</function> usage</title>
+			<programlisting>
+ $ &sercmd; cnt.grp_get_all script
+			</programlisting>
+		</example>
+	</section>
+
+
+</section>