Browse code

counters: added docs

Andrei Pelinescu-Onciul authored on 08/08/2010 17:32:03
Showing 6 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,148 @@
0
+1. Counters Module
1
+
2
+Andrei Pelinescu-Onciul
3
+
4
+   iptelorg GmbH
5
+
6
+   Copyright � 2010 iptelorg GmbH
7
+   Revision History
8
+   Revision $Revision$ $Date$
9
+     __________________________________________________________________
10
+
11
+   1.1. Overview
12
+   1.2. Parameters
13
+
14
+        1.2.1. script_counter
15
+        1.2.2. script_cnt_grp_name
16
+
17
+   1.3. Functions
18
+
19
+        1.3.1. cnt_inc(name)
20
+        1.3.2. cnt_add(name, number)
21
+        1.3.3. cnt_reset(name)
22
+
23
+   1.4. counters RPC Functions
24
+
25
+        1.4.1. cnt.get group counter_name
26
+        1.4.2. cnt.reset group counter_name
27
+        1.4.3. cnt.grps_list
28
+        1.4.4. cnt.var_list group
29
+        1.4.5. cnt.grp_get_all
30
+
31
+1.1. Overview
32
+
33
+   This module exports counters/statistics manipulating script functions
34
+   and RPCs.
35
+
36
+1.2. Parameters
37
+
38
+   Revision History
39
+   Revision $Revision$ $Date$
40
+
41
+1.2.1. script_counter
42
+
43
+   Define a new counter that can be used from the script. The default
44
+   group name for the counter is "script" (it can be changed using the
45
+   script_cnt_grp_name module parameter).
46
+
47
+   Example 1.  Create a new script_counter
48
+modparam("counters", "script_counter", "foo")
49
+
50
+1.2.2. script_cnt_grp_name
51
+
52
+   Group name that will be used for all the counters defined via the
53
+   script_counter module parameter.
54
+
55
+   Default: "script".
56
+
57
+   Example 2.  Set script_cnt_grp_name in the config file
58
+modparam("counters", "script_cnt_grp_name", "my_counters")
59
+
60
+1.3. Functions
61
+
62
+   Revision History
63
+   Revision $Revision$ $Date$
64
+
65
+1.3.1.  cnt_inc(name)
66
+
67
+   Increments the counter name. The counter must be defined using the
68
+   script_counter module parameter.
69
+
70
+   Example 3. cnt_inc usage
71
+...
72
+modparam("counters", "script_counter", "reqs")
73
+...
74
+route {
75
+        cnt_inc("reqs");
76
+...
77
+}
78
+
79
+1.3.2.  cnt_add(name, number)
80
+
81
+   Adds number the counter name. The counter must be defined using the
82
+   script_counter module parameter.
83
+
84
+   Example 4. cnt_add usage
85
+...
86
+modparam("counters", "script_counter", "reqs10")
87
+...
88
+route {
89
+        cnt_add("reqs10", 10);
90
+...
91
+}
92
+
93
+1.3.3.  cnt_reset(name)
94
+
95
+   Resets the counter name. The counter must be defined using the
96
+   script_counter module parameter.
97
+
98
+   Example 5. cnt_reset usage
99
+...
100
+modparam("counters", "script_counter", "reqs")
101
+...
102
+route {
103
+        if (...)
104
+                cnt_reset("reqs");
105
+...
106
+}
107
+
108
+1.4. counters RPC Functions
109
+
110
+   Revision History
111
+   Revision $Revision$ $Date$
112
+
113
+1.4.1.  cnt.get group counter_name
114
+
115
+   Get the value of the counter identified by group.counter_name.
116
+
117
+   Example 6. cnt.get grp counter_name usage
118
+ $ sercmd cnt.get script foo
119
+
120
+1.4.2.  cnt.reset group counter_name
121
+
122
+   Resets the counter identified by group.counter_name.
123
+
124
+   Example 7. cnt.reset grp name usage
125
+ $ sercmd cnt.reset script foo
126
+
127
+1.4.3.  cnt.grps_list
128
+
129
+   Lists all the declared counter groups.
130
+
131
+   Example 8. cnt.grps_list usage
132
+ $ sercmd cnt.grps_list
133
+
134
+1.4.4.  cnt.var_list group
135
+
136
+   Lists all the names of all the counters belonging to the specified
137
+   group.
138
+
139
+   Example 9. cnt.var_list group usage
140
+ $ sercmd cnt.var_list script
141
+
142
+1.4.5.  cnt.grp_get_all
143
+
144
+   Lists all the counter names and their values in the specified group.
145
+
146
+   Example 10. cnt.var_list group usage
147
+ $ sercmd cnt.grp_get_all script
0 148
new file mode 100644
... ...
@@ -0,0 +1,4 @@
0
+docs = counters.xml
1
+
2
+docbook_dir=../../../docbook
3
+include $(docbook_dir)/Makefile.module
0 4
new file mode 100644
... ...
@@ -0,0 +1,51 @@
0
+<?xml version="1.0" encoding="UTF-8"?>
1
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
+	[ <!ENTITY % local.common.attrib
4
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
5
+	 <!-- Include general documentation entities -->
6
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7
+	 %docentities;
8
+	]
9
+>
10
+
11
+<section id="counters" xmlns:xi="http://www.w3.org/2001/XInclude">
12
+	<sectioninfo>
13
+	<authorgroup>
14
+		<author>
15
+		<firstname>Andrei</firstname>
16
+		<surname>Pelinescu-Onciul</surname>
17
+		<affiliation><orgname>iptelorg GmbH</orgname></affiliation>
18
+		<address>
19
+			<email>andrei@iptel.org</email>
20
+		</address>
21
+		</author>
22
+	</authorgroup>
23
+	<copyright>
24
+		<year>2010</year>
25
+		<holder>iptelorg GmbH</holder>
26
+	</copyright>
27
+	<revhistory>
28
+		<revision>
29
+		<revnumber>$Revision$</revnumber>
30
+		<date>$Date$</date>
31
+		</revision>
32
+	</revhistory>
33
+	</sectioninfo>
34
+
35
+	<title>Counters Module</title>
36
+
37
+	<section id="cnts.overview">
38
+	<title>Overview</title>
39
+	<para>
40
+		This module exports counters/statistics manipulating script functions
41
+		and RPCs.
42
+	</para>
43
+	</section>
44
+
45
+	<xi:include href="params.xml"/>
46
+	<xi:include href="functions.xml"/>
47
+	<xi:include href="rpc.xml"/>
48
+
49
+</section>
50
+
0 51
new file mode 100644
... ...
@@ -0,0 +1,94 @@
0
+<?xml version="1.0" encoding="UTF-8"?>
1
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
+	[ <!ENTITY % local.common.attrib
4
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
5
+	 <!-- Include general documentation entities -->
6
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7
+	 %docentities;
8
+	]
9
+>
10
+
11
+<section id="cnts.functions" xmlns:xi="http://www.w3.org/2001/XInclude">
12
+	 <sectioninfo>
13
+	<revhistory>
14
+		<revision>
15
+		<revnumber>$Revision$</revnumber>
16
+		<date>$Date$</date>
17
+		</revision>
18
+	</revhistory>
19
+	</sectioninfo>
20
+
21
+	<title>Functions</title>
22
+
23
+	<section id="cnt_inc">
24
+	<title>
25
+		<function>cnt_inc(name)</function>
26
+	</title>
27
+	<para>
28
+		Increments the counter <emphasis>name</emphasis>. The counter
29
+		must be defined using the <varname>script_counter</varname>
30
+		module parameter.
31
+	</para>
32
+	<example>
33
+		<title><function>cnt_inc</function> usage</title>
34
+		<programlisting>
35
+...
36
+modparam("counters", "script_counter", "reqs")
37
+...
38
+route {
39
+	cnt_inc("reqs");
40
+...
41
+}
42
+		</programlisting>
43
+	</example>
44
+	</section>
45
+
46
+	<section id="cnt_add">
47
+	<title>
48
+		<function>cnt_add(name, number)</function>
49
+	</title>
50
+	<para>
51
+		Adds <emphasis>number</emphasis> the counter <emphasis>name</emphasis>.
52
+		The counter must be defined using the
53
+		<varname>script_counter</varname> module parameter.
54
+	</para>
55
+	<example>
56
+		<title><function>cnt_add</function> usage</title>
57
+		<programlisting>
58
+...
59
+modparam("counters", "script_counter", "reqs10")
60
+...
61
+route {
62
+	cnt_add("reqs10", 10);
63
+...
64
+}
65
+		</programlisting>
66
+	</example>
67
+	</section>
68
+
69
+	<section id="cnt_reset">
70
+	<title>
71
+		<function>cnt_reset(name)</function>
72
+	</title>
73
+	<para>
74
+		Resets the counter <emphasis>name</emphasis>. The counter
75
+		must be defined using the <varname>script_counter</varname>
76
+		module parameter.
77
+	</para>
78
+	<example>
79
+		<title><function>cnt_reset</function> usage</title>
80
+		<programlisting>
81
+...
82
+modparam("counters", "script_counter", "reqs")
83
+...
84
+route {
85
+	if (...)
86
+		cnt_reset("reqs");
87
+...
88
+}
89
+		</programlisting>
90
+	</example>
91
+	</section>
92
+
93
+</section>
0 94
new file mode 100644
... ...
@@ -0,0 +1,58 @@
0
+<?xml version="1.0" encoding="UTF-8"?>
1
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
2
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
+	[ <!-- Include general documentation entities -->
4
+		<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
5
+		%docentities;
6
+	]
7
+>
8
+
9
+<section id="cnts.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
10
+	<sectioninfo>
11
+		<revhistory>
12
+			<revision>
13
+				<revnumber>$Revision$</revnumber>
14
+				<date>$Date$</date>
15
+			</revision>
16
+		</revhistory>
17
+	</sectioninfo>
18
+	<title>Parameters</title>
19
+
20
+	<section id="scrip_counter">
21
+		<title><varname>script_counter</varname></title>
22
+		<para>
23
+			Define a new counter that can be used from the script.
24
+			The default group name for the counter is "script"
25
+			(it can be changed using the
26
+			<varname>script_cnt_grp_name</varname> module parameter).
27
+		</para>
28
+		<example>
29
+			<title>
30
+				Create a new <varname>script_counter</varname>
31
+			</title>
32
+			<programlisting>
33
+modparam("counters", "script_counter", "foo")
34
+			</programlisting>
35
+		</example>
36
+	</section>
37
+
38
+	<section id="scrip_cnt_grp_name">
39
+		<title><varname>script_cnt_grp_name</varname></title>
40
+		<para>
41
+			Group name that will be used for all the counters defined
42
+			via the <varname>script_counter</varname> module parameter.
43
+		</para>
44
+		<para>
45
+			Default: "script".
46
+		</para>
47
+		<example>
48
+			<title>
49
+				Set <varname>script_cnt_grp_name</varname> in the config file
50
+			</title>
51
+			<programlisting>
52
+modparam("counters", "script_cnt_grp_name", "my_counters")
53
+			</programlisting>
54
+		</example>
55
+	</section>
56
+
57
+</section>
0 58
new file mode 100644
... ...
@@ -0,0 +1,89 @@
0
+<?xml version="1.0" encoding="UTF-8"?>
1
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
2
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3
+	[ <!-- Include general documentation entities -->
4
+		<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
5
+		%docentities;
6
+	]
7
+>
8
+
9
+<section id="cnts.rpcs" xmlns:xi="http://www.w3.org/2001/XInclude">
10
+	<sectioninfo>
11
+		<revhistory>
12
+			<revision>
13
+				<revnumber>$Revision$</revnumber>
14
+				<date>$Date$</date>
15
+			</revision>
16
+		</revhistory>
17
+	</sectioninfo>
18
+	<title>counters RPC Functions</title>
19
+
20
+	<section id="cnt.get">
21
+		<title> <function>cnt.get group counter_name</function></title>
22
+		<para>
23
+			Get the value of the counter identified by group.counter_name.
24
+		</para>
25
+		<example>
26
+			<title><function>cnt.get grp counter_name</function> usage</title>
27
+			<programlisting>
28
+ $ &sercmd; cnt.get script foo
29
+			</programlisting>
30
+		</example>
31
+	</section>
32
+
33
+	<section id="cnt.reset">
34
+		<title> <function>cnt.reset group counter_name</function></title>
35
+		<para>
36
+			Resets the counter identified by group.counter_name.
37
+		</para>
38
+		<example>
39
+			<title><function>cnt.reset grp name</function> usage</title>
40
+			<programlisting>
41
+ $ &sercmd; cnt.reset script foo
42
+			</programlisting>
43
+		</example>
44
+	</section>
45
+
46
+	<section id="cnt.grps_list">
47
+		<title> <function>cnt.grps_list</function></title>
48
+		<para>
49
+			Lists all the declared counter groups.
50
+		</para>
51
+		<example>
52
+			<title><function>cnt.grps_list</function> usage</title>
53
+			<programlisting>
54
+ $ &sercmd; cnt.grps_list
55
+			</programlisting>
56
+		</example>
57
+	</section>
58
+
59
+	<section id="cnt.var_list">
60
+		<title> <function>cnt.var_list group</function></title>
61
+		<para>
62
+			Lists all the names of all the counters belonging to the
63
+			specified group.
64
+		</para>
65
+		<example>
66
+			<title><function>cnt.var_list group</function> usage</title>
67
+			<programlisting>
68
+ $ &sercmd; cnt.var_list script
69
+			</programlisting>
70
+		</example>
71
+	</section>
72
+
73
+	<section id="cnt.grp_get_all">
74
+		<title> <function>cnt.grp_get_all</function></title>
75
+		<para>
76
+			Lists all the counter names and their values in the
77
+			specified group.
78
+		</para>
79
+		<example>
80
+			<title><function>cnt.var_list group</function> usage</title>
81
+			<programlisting>
82
+ $ &sercmd; cnt.grp_get_all script
83
+			</programlisting>
84
+		</example>
85
+	</section>
86
+
87
+
88
+</section>