Browse code

counters: doc update

- document the new format used by the script_counter modparam and
by the script functions.
- document the new cnt.help rpc.

Andrei Pelinescu-Onciul authored on 09/08/2010 15:41:25
Showing 4 changed files
... ...
@@ -17,9 +17,9 @@ Andrei Pelinescu-Onciul
17 17
 
18 18
    1.3. Functions
19 19
 
20
-        1.3.1. cnt_inc(name)
21
-        1.3.2. cnt_add(name, number)
22
-        1.3.3. cnt_reset(name)
20
+        1.3.1. cnt_inc([group.]name)
21
+        1.3.2. cnt_add([group.]name, number)
22
+        1.3.3. cnt_reset([group.]name)
23 23
 
24 24
    1.4. counters RPC Functions
25 25
 
... ...
@@ -28,6 +28,7 @@ Andrei Pelinescu-Onciul
28 28
         1.4.3. cnt.grps_list
29 29
         1.4.4. cnt.var_list group
30 30
         1.4.5. cnt.grp_get_all
31
+        1.4.6. cnt.help group counter_name
31 32
 
32 33
 1.1. Overview
33 34
 
... ...
@@ -41,17 +42,25 @@ Andrei Pelinescu-Onciul
41 42
 
42 43
 1.2.1. script_counter
43 44
 
44
-   Define a new counter that can be used from the script. The default
45
-   group name for the counter is "script" (it can be changed using the
46
-   script_cnt_grp_name module parameter).
45
+   Define a new counter that can be used from the script. The declaration
46
+   might include a group in front of the counter name, separated with '.'.
47
+   It might also include a counter description string (help message),
48
+   separated from the name with a ' ' or ':'. If the group is missing, the
49
+   group defined in the script_cnt_grp_name module parameter will be used
50
+   (the default is "script"). If the description is missing, the default
51
+   is "custom script counter". The format of the declaration is:
52
+   [group.]name[( |:)description].
47 53
 
48 54
    Example 1.  Create a new script_counter
49
-modparam("counters", "script_counter", "foo")
55
+modparam("counters", "script_counter", "foo")  # script.foo
56
+modparam("counters", "script_counter", "test.bar")  # test.bar
57
+modparam("counters", "script_counter", "baz example counter")  # script.baz
58
+modparam("counters", "script_counter", "test.x:another example") # test.x
50 59
 
51 60
 1.2.2. script_cnt_grp_name
52 61
 
53
-   Group name that will be used for all the counters defined via the
54
-   script_counter module parameter.
62
+   Group name that will be used for the counters defined via the
63
+   script_counter module parameter which do not have a specified group.
55 64
 
56 65
    Default: "script".
57 66
 
... ...
@@ -63,38 +72,44 @@ modparam("counters", "script_cnt_grp_name", "my_counters")
63 72
    Revision History
64 73
    Revision $Revision$ $Date$
65 74
 
66
-1.3.1.  cnt_inc(name)
75
+1.3.1.  cnt_inc([group.]name)
67 76
 
68
-   Increments the counter name. The counter must be defined using the
69
-   script_counter module parameter.
77
+   Increments the counter group.name. The counter must be defined using
78
+   the script_counter module parameter. If the group name is missing, the
79
+   group specified by the script_cnt_grp_name modparam will be used.
70 80
 
71 81
    Example 3. cnt_inc usage
72 82
 ...
73 83
 modparam("counters", "script_counter", "reqs")
84
+modparam("counters", "script_counter", "out.reqs  forwarded requests")
74 85
 ...
75 86
 route {
76 87
         cnt_inc("reqs");
88
+        if (forward(uri:host, uri:port))
89
+                cnt_inc("out.reqs");
77 90
 ...
78 91
 }
79 92
 
80
-1.3.2.  cnt_add(name, number)
93
+1.3.2.  cnt_add([group.]name, number)
81 94
 
82
-   Adds number the counter name. The counter must be defined using the
83
-   script_counter module parameter.
95
+   Adds number the counter group.name. The counter must be defined using
96
+   the script_counter module parameter. If the group name is missing, the
97
+   group specified by the script_cnt_grp_name modparam will be used.
84 98
 
85 99
    Example 4. cnt_add usage
86 100
 ...
87
-modparam("counters", "script_counter", "reqs10")
101
+modparam("counters", "script_counter", "reqs10  reqs times 10")
88 102
 ...
89 103
 route {
90 104
         cnt_add("reqs10", 10);
91 105
 ...
92 106
 }
93 107
 
94
-1.3.3.  cnt_reset(name)
108
+1.3.3.  cnt_reset([group.]name)
95 109
 
96
-   Resets the counter name. The counter must be defined using the
97
-   script_counter module parameter.
110
+   Resets the counter group.name. The counter must be defined using the
111
+   script_counter module parameter. If the group name is missing, the
112
+   group specified by the script_cnt_grp_name modparam will be used.
98 113
 
99 114
    Example 5. cnt_reset usage
100 115
 ...
... ...
@@ -146,3 +161,10 @@ route {
146 161
 
147 162
    Example 10. cnt.var_list group usage
148 163
  $ sercmd cnt.grp_get_all script
164
+
165
+1.4.6.  cnt.help group counter_name
166
+
167
+   Displays the counter description.
168
+
169
+   Example 11. cnt.help grp name usage
170
+ $ sercmd cnt.help script foo
... ...
@@ -23,21 +23,26 @@
23 23
 
24 24
 	<section id="cnt_inc">
25 25
 	<title>
26
-		<function>cnt_inc(name)</function>
26
+		<function>cnt_inc([group.]name)</function>
27 27
 	</title>
28 28
 	<para>
29
-		Increments the counter <emphasis>name</emphasis>. The counter
29
+		Increments the counter <emphasis>group.name</emphasis>. The counter
30 30
 		must be defined using the <varname>script_counter</varname>
31 31
 		module parameter.
32
+		If the group name is missing, the group specified by the
33
+		<varname>script_cnt_grp_name</varname>  modparam will be used.
32 34
 	</para>
33 35
 	<example>
34 36
 		<title><function>cnt_inc</function> usage</title>
35 37
 		<programlisting>
36 38
 ...
37 39
 modparam("counters", "script_counter", "reqs")
40
+modparam("counters", "script_counter", "out.reqs  forwarded requests")
38 41
 ...
39 42
 route {
40 43
 	cnt_inc("reqs");
44
+	if (forward(uri:host, uri:port))
45
+		cnt_inc("out.reqs");
41 46
 ...
42 47
 }
43 48
 		</programlisting>
... ...
@@ -46,18 +51,21 @@ route {
46 51
 
47 52
 	<section id="cnt_add">
48 53
 	<title>
49
-		<function>cnt_add(name, number)</function>
54
+		<function>cnt_add([group.]name, number)</function>
50 55
 	</title>
51 56
 	<para>
52
-		Adds <emphasis>number</emphasis> the counter <emphasis>name</emphasis>.
57
+		Adds <emphasis>number</emphasis> the counter
58
+		<emphasis>group.name</emphasis>.
53 59
 		The counter must be defined using the
54 60
 		<varname>script_counter</varname> module parameter.
61
+		If the group name is missing, the group specified by the
62
+		<varname>script_cnt_grp_name</varname>  modparam will be used.
55 63
 	</para>
56 64
 	<example>
57 65
 		<title><function>cnt_add</function> usage</title>
58 66
 		<programlisting>
59 67
 ...
60
-modparam("counters", "script_counter", "reqs10")
68
+modparam("counters", "script_counter", "reqs10  reqs times 10")
61 69
 ...
62 70
 route {
63 71
 	cnt_add("reqs10", 10);
... ...
@@ -69,12 +77,14 @@ route {
69 77
 
70 78
 	<section id="cnt_reset">
71 79
 	<title>
72
-		<function>cnt_reset(name)</function>
80
+		<function>cnt_reset([group.]name)</function>
73 81
 	</title>
74 82
 	<para>
75
-		Resets the counter <emphasis>name</emphasis>. The counter
83
+		Resets the counter <emphasis>group.name</emphasis>. The counter
76 84
 		must be defined using the <varname>script_counter</varname>
77 85
 		module parameter.
86
+		If the group name is missing, the group specified by the
87
+		<varname>script_cnt_grp_name</varname>  modparam will be used.
78 88
 	</para>
79 89
 	<example>
80 90
 		<title><function>cnt_reset</function> usage</title>
... ...
@@ -22,16 +22,26 @@
22 22
 		<title><varname>script_counter</varname></title>
23 23
 		<para>
24 24
 			Define a new counter that can be used from the script.
25
-			The default group name for the counter is "script"
26
-			(it can be changed using the
27
-			<varname>script_cnt_grp_name</varname> module parameter).
25
+			The declaration might include a group in front of the counter
26
+			name, separated with '.'. It might also include a counter
27
+			description string (help message), separated from the name
28
+			with a ' ' or  ':'.
29
+			If the group is missing, the group defined in the
30
+			<varname>script_cnt_grp_name</varname> module parameter will
31
+			be used (the default is "script").
32
+			If the description is missing, the default is
33
+			"custom script counter".
34
+			The format of the declaration is: [group.]name[( |:)description].
28 35
 		</para>
29 36
 		<example>
30 37
 			<title>
31 38
 				Create a new <varname>script_counter</varname>
32 39
 			</title>
33 40
 			<programlisting>
34
-modparam("counters", "script_counter", "foo")
41
+modparam("counters", "script_counter", "foo")  # script.foo
42
+modparam("counters", "script_counter", "test.bar")  # test.bar
43
+modparam("counters", "script_counter", "baz example counter")  # script.baz
44
+modparam("counters", "script_counter", "test.x:another example") # test.x
35 45
 			</programlisting>
36 46
 		</example>
37 47
 	</section>
... ...
@@ -39,8 +49,9 @@ modparam("counters", "script_counter", "foo")
39 49
 	<section id="scrip_cnt_grp_name">
40 50
 		<title><varname>script_cnt_grp_name</varname></title>
41 51
 		<para>
42
-			Group name that will be used for all the counters defined
43
-			via the <varname>script_counter</varname> module parameter.
52
+			Group name that will be used for the counters defined
53
+			via the <varname>script_counter</varname> module parameter which
54
+			do not have a specified group.
44 55
 		</para>
45 56
 		<para>
46 57
 			Default: "script".
... ...
@@ -85,5 +85,18 @@
85 85
 		</example>
86 86
 	</section>
87 87
 
88
+	<section id="cnt.help">
89
+		<title> <function>cnt.help group counter_name</function></title>
90
+		<para>
91
+			Displays the counter description.
92
+		</para>
93
+		<example>
94
+			<title><function>cnt.help grp name</function> usage</title>
95
+			<programlisting>
96
+ $ &sercmd; cnt.help script foo
97
+			</programlisting>
98
+		</example>
99
+	</section>
100
+
88 101
 
89 102
 </section>