1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="HTML Tidy for Linux/x86 (vers 1st August 2004), see www.w3.org">
<title>Variables</title>
<meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
<link rel="HOME" title="The Cacti Manual" href="index.html">
<link rel="UP" title="Reference" href="reference.html">
<link rel="PREVIOUS" title="Reference" href="reference.html">
<link rel="NEXT" title="Host Variables" href="host_variables.html">
<link rel="STYLESHEET" type="text/css" href="manual.css">
</head>
<body class="CHAPTER" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="NAVHEADER">
<table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<th colspan="3" align="center">The Cacti Manual</th>
</tr>
<tr>
<td width="10%" align="left" valign="bottom"><a href="reference.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom"></td>
<td width="10%" align="right" valign="bottom"><a href="host_variables.html" accesskey="N">Next</a></td>
</tr>
</table>
<hr align="left" width="100%">
</div>
<div class="CHAPTER">
<h1><a name="VARIABLES" id="VARIABLES"></a>Chapter 15. Variables</h1>
<div class="TOC">
<dl>
<dt><b>Table of Contents</b></dt>
<dt><a href="variables.html#GRAPH_VARIABLES">Graph Variables</a></dt>
<dt><a href="host_variables.html">Host Variables</a></dt>
</dl>
</div>
<div class="SECT1">
<h1 class="SECT1"><a name="GRAPH_VARIABLES" id="GRAPH_VARIABLES">Graph Variables</a></h1>
<p>The following variables can be used in the <span class="GUILABEL">Text Format</span> and <span class="GUILABEL">Value</span> graph item fields. Below is a description of each of these variables.</p>
<div class="SECT2">
<h2 class="SECT2"><a name="VARIABLE_DATE_TIME" id="VARIABLE_DATE_TIME">Date/Time</a></h2>
<pre class="SCREEN">
<kbd class="USERINPUT">|date_time|</kbd>
</pre>
<p>This variable will place the date and time of the last poller run on the graph. It can be used to replicate <span class="APPLICATION">MRTG</span>'s "graph last updated" feature.</p>
</div>
<div class="SECT2">
<h2 class="SECT2"><a name="VARIABLE_DATA_QUERY" id="VARIABLE_DATA_QUERY">Data Query Fields</a></h2>
<pre class="SCREEN">
<kbd class="USERINPUT">|query_field_name|</kbd>
</pre>
<p>You can place the value of any data query field on the by including this variable. Make sure to substitute "field_name" with the actual data query field name.</p>
<div class="EXAMPLE">
<a name="AEN1989" id="AEN1989"></a>
<p><b>Example 15-1. Print the IP Address on a traffic graph</b></p>
<p><kbd class="USERINPUT">|query_ifIP|</kbd></p>
</div>
<div class="EXAMPLE">
<a name="AEN1993" id="AEN1993"></a>
<p><b>Example 15-2. Print the mount point on net-snmp disk graph</b></p>
<p><kbd class="USERINPUT">|query_dskPath|</kbd></p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2"><a name="VARIABLE_NTH_PERCENTILE" id="VARIABLE_NTH_PERCENTILE">Nth Percentile</a></h2>
<pre class="SCREEN">
<kbd class="USERINPUT">|[0-9]:(bits|bytes):[0-9]:(current|total|max|total_peak|all_max_current|all_max_peak|aggregate_max|aggregate_sum|aggregate):[0-9]|</kbd>
</pre>
<p>Nth percentile is often used by hosting providers to bill customers based on their peak traffic usage while ignoring their top (100 - Nth) percent. This way if a customer has a fairly consistent traffic pattern and decides to download a huge file one day, the large spike will be ignored. Common Nth percentile is 95, which would cut off the top 5% of the traffic.</p>
<p>In Cacti, Nth percentile works just like any other graph variable. To use this variable you must give it five arguments:</p>
<div class="TABLE">
<a name="AEN2003" id="AEN2003"></a>
<p><b>Table 15-1. Nth Percentile Argument Description</b></p>
<table border="1" frame="border" rules="all" class="CALSTABLE">
<col width="1*">
<col width="3*">
<thead>
<tr>
<th align="center">Name</th>
<th align="center">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="FUNCTION">[0-9]</code></td>
<td>The first argument is a number between 1 and 99. This number represents the Nth percentile that you would like to calculate.</td>
</tr>
<tr>
<td><code class="FUNCTION">(bits|bytes)</code></td>
<td>Choose whether you want to represent your Nth percentile in bits or bytes. The only valid values for this field are 'bits' and 'bytes'.</td>
</tr>
<tr>
<td><code class="FUNCTION">[0-9]</code></td>
<td>This field determines the power of 10 divisor that will be applied to your Nth percentile number. Enter '0' to leave the number alone, '3' for kilo or '6' for mega, etc.</td>
</tr>
<tr>
<td><code class="FUNCTION">( current | total | max | total_peak | all_max_current | all_max_peak | aggregate_max | aggregate_sum | aggregate )</code></td>
<td>Nth Percentile Type - Refer to Nth Types</td>
</tr>
<tr>
<td><code class="FUNCTION">[0-9]</code></td>
<td>Enter the number of digits to use for floating point precision when printing out the final number. The default value for this field is two decimal places.</td>
</tr>
</tbody>
</table>
</div>
<div class="TABLE">
<a name="AEN2033" id="AEN2033"></a>
<p><b>Table 15-2. Nth Percentile Types</b></p>
<table border="1" frame="border" rules="all" class="CALSTABLE">
<col width="1*">
<col width="3*">
<thead>
<tr>
<th align="center">Type</th>
<th align="center">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="FUNCTION">current</code></td>
<td>Calculates the Nth percentile based off the selected data source on the graph item wich the variable is used. This type requires a selected Data Source Item in the graph item in which it is defined.</td>
</tr>
<tr>
<td><code class="FUNCTION">total</code></td>
<td>Calculates the Nth percentile based off the selected data source on the graph item wich the variable is used. But unlike current, this function totals the Nth percentile results of all same named data source names on the graph. Example, all traffic_in would have their Nth percentile calculated and then totaled. This type requires a selected Data Source Item in the graph item in which it is defined.</td>
</tr>
<tr>
<td><code class="FUNCTION">max</code></td>
<td>Calculates the Nth percentile based off the selected data source on the graph item which the variable is used, but it is important to note that it selects the higher of the values for each row in data source and then uses the resulting set to calculate the Nth percentile. Example, you have selected a interface data source for traffic_in, this will evaluate traffic_out and traffic_in for that selected data source (rrdtool file) and select the higher of the two values for each row of data. The resulting max values are used to calculate the Nth percentile value. This type requires a selected Data Source Item in the graph item in which it is defined.</td>
</tr>
<tr>
<td><code class="FUNCTION">total_peak</code></td>
<td>Calculates the Nth percentile based on the max for each data source defined on the graph. Example, the max is taken for each data source defined on the graph, but it's the max of traffic_in or traffic_out for that data source (rrdtool file). The resulting max values are summed and returned.</td>
</tr>
<tr>
<td><code class="FUNCTION">all_max_current</code></td>
<td>Calculates the Nth percentile based off the selected data source on the graph item which the variable is used, but it only selects the highest (max) value of all the data source items on the graph. Example, there are 3 data sources defined on the graph, the selected data source is traffic_in, all data sources for traffic_in will be compared against each other and the highest Nth value of all graph items will be selected as the result. This type requires a selected Data Source Item in the graph item in which it is defined.</td>
</tr>
<tr>
<td><code class="FUNCTION">all_max_peak</code></td>
<td>Calculates the Nth percentile by selecting the highest (max) calculated max Nth percentile value for each data source (rrdtool file) selected on the graph. Example, 3 data sources are defined on the graph, for each data source, the max Nth percentile is calculated, and out of the resulting set of values, the highest value is selected and returned.</td>
</tr>
<tr>
<td><code class="FUNCTION">aggregate_max</code></td>
<td>Calculates the Nth percentile by selecting the highest value for each summed value of like data sources and selecting the maximum value of that set to calculate the Nth percentile value. Example, you have a graph with 5 traffic_in and 18 traffic_out data sources. The traffic_in rows are summed together, then the traffic_out rows are summed together, then for each row, the higher of the 2 values is selected. The Nth percentile is calculated from the resulting maximum values.</td>
</tr>
<tr>
<td><code class="FUNCTION">aggregate_sum</code></td>
<td>Calculates the Nth percentile by summing all data sources on the graph row for row and calculates the Nth value on the resulting summed data. Example, you have a graph with 4 traffic_in and 3 traffic_out data sources defined. All the defined traffic_in and traffic_out are summed together and then the Nth percentile value is calculated from that set.</td>
</tr>
<tr>
<td><code class="FUNCTION">aggregate</code></td>
<td>Calculates the Nth percentile by summing like data source names row for row from each data source defined on the graph and then returning the highest Nth percent value calculated for like data source names. Example, you have a graph with 3 traffic_out and 5 traffic_in data sources defined. The traffic_in and traffic_out are summed then the Nth value is calculated and the higher of the 2 values is returned as the variable.</td>
</tr>
</tbody>
</table>
</div>
<div class="NOTE">
<blockquote class="NOTE">
<p><b>Concerning aggregate Nth percentile functions and rra definitions:</b> All data sources used in a graph MUST have the same rra definitions. If the number of rows do not match when calculations are attempted, the results may produce errors and invalid results. Please also be aware the aggregate functions take more memory and processor power when used. Recommended minimum of 64 megs memory limit for php when querying large ranges or graphs with a large ammount of aggregated data sources.</p>
</blockquote>
</div>
<div class="EXAMPLE">
<a name="AEN2082" id="AEN2082"></a>
<p><b>Example 15-3. Output in the following format, for 95th percentile: 42.58 mbit</b></p>
<p><kbd class="USERINPUT">|95:bits:6:max:2|</kbd></p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2"><a name="VARIABLE_BANDWIDTH_SUMMATION" id="VARIABLE_BANDWIDTH_SUMMATION">Bandwidth Summation</a></h2>
<pre class="SCREEN">
<kbd class="USERINPUT">|sum:([0-9]|auto):(current|total):([0-9]):([0-9]+|auto)|</kbd>
</pre>
<p>Bandwidth summation is useful for summing up all values in an RRD file for a given time range. This is typically useful on traffic graphs where you can see a total of all traffic that has gone through an interface in a given time period.</p>
<p>In Cacti, bandwidth summation works just like any other graph variable. To use this variable you must give it three arguments:</p>
<div class="TABLE">
<a name="AEN2092" id="AEN2092"></a>
<p><b>Table 15-3. Bandwidth Summation Argument Description</b></p>
<table border="1" frame="border" rules="all" class="CALSTABLE">
<col width="1*">
<col width="3*">
<thead>
<tr>
<th align="center">Name</th>
<th align="center">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="FUNCTION">([0-9]|auto)</code></td>
<td>This field determines the power of 10 divisor that will be applied to your number. Enter '0' to leave the number alone, '3' for kilo or '6' for mega, etc. You can also enter 'auto' for this field to have Cacti automatically scale the number and insert the appropriate label.</td>
</tr>
<tr>
<td><code class="FUNCTION">(current|total)</code></td>
<td>You can choose to calculate the summation based on the current data source or a total of all data sources used on the graph. The only valid values for this field are 'current' and 'total'.</td>
</tr>
<tr>
<td><code class="FUNCTION">[0-9]</code></td>
<td>Enter the number of digits to use for floating point precision when printing out the final number. The default value for this field is two decimal places.</td>
</tr>
<tr>
<td><code class="FUNCTION">([0-9]+|auto)</code></td>
<td>Enter the number of seconds in the past to perform the summation calculation for. For instance '86400' for 24 hours, '172800' for 48 hours, etc. You can also enter 'auto' for this field to have Cacti use the graph timespan.</td>
</tr>
</tbody>
</table>
</div>
<div class="EXAMPLE">
<a name="AEN2118" id="AEN2118"></a>
<p><b>Example 15-4. Output in the following format: 36.47 GB</b></p>
<p><kbd class="USERINPUT">|sum:auto:current:2:auto|</kbd></p>
</div>
</div>
</div>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td width="33%" align="left" valign="top"><a href="reference.html" accesskey="P">Prev</a></td>
<td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
<td width="33%" align="right" valign="top"><a href="host_variables.html" accesskey="N">Next</a></td>
</tr>
<tr>
<td width="33%" align="left" valign="top">Reference</td>
<td width="34%" align="center" valign="top"><a href="reference.html" accesskey="U">Up</a></td>
<td width="33%" align="right" valign="top">Host Variables</td>
</tr>
</table>
</div>
</body>
</html>
|
