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
|
<!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>Data Queries</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="Advanced Topics" href="advanced_topics.html">
<link rel="PREVIOUS" title="Making Your Scripts Work With Cacti" href="making_scripts_work_with_cacti.html">
<link rel="NEXT" title="SNMP Query XML Syntax" href="snmp_query_xml.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="making_scripts_work_with_cacti.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom"></td>
<td width="10%" align="right" valign="bottom"><a href="snmp_query_xml.html" accesskey="N">Next</a></td>
</tr>
</table>
<hr align="left" width="100%">
</div>
<div class="CHAPTER">
<h1><a name="DATA_QUERIES" id="DATA_QUERIES"></a>Chapter 10. Data Queries</h1>
<div class="TOC">
<dl>
<dt><b>Table of Contents</b></dt>
<dt><a href="data_queries.html#NEW_DATA_QUERY">Creating a Data Query</a></dt>
<dt><a href="snmp_query_xml.html">SNMP Query XML Syntax</a></dt>
<dt><a href="script_query_xml.html">Script Query XML Syntax</a></dt>
</dl>
</div>
<p>Data queries are not a replacement for data input methods in Cacti. Instead they provide an easy way to query, or list data based upon an index, making the data easier to graph. The most common use of a data query within Cacti is to retrieve a list of network interfaces via SNMP. If you want to graph the traffic of a network interface, first Cacti must retrieve a list of interfaces on the host. Second, Cacti can use that information to create the necessary graphs and data sources. Data queries are only concerned with the first step of the process, that is obtaining a list of network interfaces and not creating the graphs/data sources for them. While listing network interfaces is a common use for data queries, they also have other uses such as listing partitions, processors, or even cards in a router.</p>
<p>One requirement for any data query in Cacti, is that it has some unique value that defines each row in the list. This concept follows that of a 'primary key' in SQL, and makes sure that each row in the list can be uniquely referenced. Examples of these index values are 'ifIndex' for SNMP network interfaces or the device name for partitions.</p>
<p>There are two types of data queries that you will see referred to throughout Cacti. They are script queries and SNMP queries. Script and SNMP queries are virtually identical in their functionality and only differ in how they obtain their information. A script query will call an external command or script and an SNMP query will make an SNMP call to retrieve a list of data.</p>
<p>All data queries have two parts, the XML file and the definition within Cacti. An XML file must be created for each query, that defines where each piece of information is and how to retrieve it. This could be thought of as the actual query. The second part is a definition within Cacti, which tells Cacti where to find the XML file and associates the data query with one or more graph templates.</p>
<div class="SECT1">
<h1 class="SECT1"><a name="NEW_DATA_QUERY" id="NEW_DATA_QUERY">Creating a Data Query</a></h1>
<p>Once you have created the XML file that defines your data query, you must add the data query within Cacti. To do this you must click on <span class="GUILABEL">Data Queries</span> under the <span class="GUILABEL">Data Gathering</span> heading, and select <span class="GUILABEL">Add</span>. You will be prompted for some basic information about the data query, described in more detail below.</p>
<div class="TABLE">
<a name="AEN839" id="AEN839"></a>
<p><b>Table 10-1. Field Description: Data Queries</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>Name</td>
<td>Give the data query a name that you will use to identify it. This name will be used throughout Cacti when presented with a list of data queries.</td>
</tr>
<tr>
<td>Description</td>
<td>(Optional) Enter a more detailed description of the data query including the information it queries or additional requirements.</td>
</tr>
<tr>
<td>XML Path</td>
<td>Fill in the full path to the XML file that defines this query. You can optionally use the <path_cacti> variable that will be substituted with the full path to Cacti. On the next screen, Cacti will check to make sure that it can find the XML file.</td>
</tr>
<tr>
<td>Data Input Method</td>
<td>This is how you tell Cacti to handle the data it receives from the data query. Typically, you will select "Get SNMP Data (Indexed)" for an SNMP query and "Get Script Data (Indexed)" for a script query.</td>
</tr>
</tbody>
</table>
</div>
<p>When you are finished filling in all necessary fields, click the <span class="GUILABEL">Create</span> button to continue. You will be redirected back to the same page, but this time with some additional information to fill in. If you receive a red warning that says 'XML File Does Not Exist', correct the value specified in the 'XML Path' field.</p>
<div class="SECT2">
<h2 class="SECT2"><a name="DATA_QUERIES_ASSOCIATED_GRAPH_TEMPLATES" id="DATA_QUERIES_ASSOCIATED_GRAPH_TEMPLATES">Associated Graph Templates</a></h2>
<p>Every data query must have at least one graph template associated with it, and possibly more depending on the number of output fields specified in the XML file. This is where you get to choose what kind of graphs to generate from this query. For instance, the interface data query has multiple graph template associations, used to graph traffic, errors, or packets. To add a new graph template association, simply click <span class="GUILABEL">Add</span> at the right of the <span class="GUILABEL">Associated Graph Templates</span> box. You will be presented with a few fields to fill in:</p>
<div class="TABLE">
<a name="AEN868" id="AEN868"></a>
<p><b>Table 10-2. Field Description: Associated Graph Templates</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>Name</td>
<td>Give a name describing what kind of data you are trying to represent or graph. When the user creates a graph using this data query, they will see a list of graph template associations that they will have to choose from.</td>
</tr>
<tr>
<td>Graph Template</td>
<td>Choose the actual graph template that you want to make the association with.</td>
</tr>
</tbody>
</table>
</div>
<p>When you are finished filling in these fields, click the <span class="GUILABEL">Create</span> button. You will be redirected back to the same page with some additional information to fill in. Cacti will make a list of each data template referenced to in your selected graph template and display them under the <span class="GUILABEL">Associated Data Templates</span> box. For each data source item listed, you must selected the data query output field that corresponds with it. <b class="EMPHASIS">Do not forget to check the checkbox to the right of each selection, or your settings will not be saved.</b></p>
<p>The <span class="GUILABEL">Suggested Values</span> box gives you a way to control field values of data sources and graphs created using this data query. If you specify multiple suggested values for the same field, Cacti will evaluate them in order which you can control using the up or down arrow icons. For more information about valid field names and variables, read the section on suggested values.</p>
<p>When you are finished filling in all necessary fields on this form, click the <span class="GUILABEL">Save</span> button to return to the data queries edit screen. Repeat the steps under this heading as many times as necessary to represent all data in your XML file. When you are finished with this, you should be ready to start adding your data query to hosts.</p>
</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="making_scripts_work_with_cacti.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="snmp_query_xml.html" accesskey="N">Next</a></td>
</tr>
<tr>
<td width="33%" align="left" valign="top">Making Your Scripts Work With Cacti</td>
<td width="34%" align="center" valign="top"><a href="advanced_topics.html" accesskey="U">Up</a></td>
<td width="33%" align="right" valign="top">SNMP Query XML Syntax</td>
</tr>
</table>
</div>
</body>
</html>
|
