<< Previous Section | The Power of Data Acquisition [home] | Next Section >> |
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 interfacesand 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.
One requirment 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.
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.
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.
SNMP Query XML Syntax
<query> <name>Get SNMP Interfaces</name> <description>Queries a host for a list of monitorable interfaces</description> <oid_index>.1.3.6.1.2.1.2.2.1.1</oid_index> <fields> <ifIndex> <name>Index</name> <method>walk</method> <source>value</source> <direction>input</direction> <oid>.1.3.6.1.2.1.2.2.1.1</oid> </ifIndex> </fields> </query> |
query->name | (Optional) You can enter a "friendly name" for the SNMP query here. It will not be used by Cacti, and is for identification only. |
query->description | (Optional) You can enter a description for the SNMP query here. It will not be used by Cacti, and is for identification only. |
query->oid_index | Every SNMP query must have an OID that represents the index values for the query when walked. As described above, any data query in Cacti must contain a field that uniquely identifies each row returned by the query. In the example above, the oid_index points to the OID of ifIndex in the interface MIB. |
query->fields | Each field contained within the SNMP query must be defined under this tag. |
query->fields->ifIndex | Each defined field in the SNMP query must have a unique name given to it. Do not use spaces or any non-alphanumeric characters, this name must be identifiable within Cacti. |
query->fields->ifIndex->name | Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field. |
query->fields->ifIndex->method | Tell Cacti how you want it to gather SNMP information for this field. Valid values are 'walk' and 'get'. The 'get' method obtains a list of indexes and does an snmpget for each index of the OID specified for this field. The walk method simply does a walk of the OID specified for this field. Both methods will return the same values, even though the 'walk' method is typically more efficient. |
query->fields->ifIndex->source | When Cacti obtains a list for this field, you need to tell it how to derive its value for each row. Valid options here are 'value' and 'OID/REGEXP:(regexp_match)'. The 'value' option simply returns the result of the snmpget for each row. The 'OID/REGEXP:(regexp_match)' can be used when you need to use a POSIX-based regular expression to derive the value from the OID. The most common example of this is to retreive the IP address of an interface, and can be seen in the 'interface.xml' file. |
query->fields->ifIndex->direction | There are two types of fields when dealing with an SNMP query, 'input' and 'output'. Input values are the "known" values that you will use to derive the output values, this is where the "query" part of SNMP query comes in. When you create a graph based on an SNMP query, Cacti will prompt you to choose the input value to base the graph on. A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed. |
query->fields->ifIndex->oid | You must specify the actual OID that corresponds with the field. Each value for this field can be obtained by doing an snmpget on 'oid.(each)snmpindex'. |
Script Query XML Syntax
<query> <name>Get Unix Mounted Partitions</name> <description>Queries a list of mounted partitions on a unix-based host with the 'df' command.</description> <script_path>perl |path_cacti|/scripts/query_unix_partitions.pl</script_path> <arg_index>index</arg_index> <arg_query>query</arg_query> <arg_get>get</arg_get> <output_delimeter>:</output_delimeter> <fields> <dskDevice> <name>Device Name</name> <direction>input</direction> <query_name>device</query_name> </dskDevice> </fields> </query> |
query->name | (Optional) You can enter a "friendly name" for the script query here. It will not be used by Cacti, and is for identification only. |
query->description | (Optional) You can enter a description for the script query here. It will not be used by Cacti, and is for identification only. |
query->script_path | Enter the complete path to the script or executable that is going to handle your script query. When in doubt, specify the pull path to all binaries referenced in this path, the query may not execute otherwise. |
query->arg_index | Enter the argument that is to be passed to the script to retrieve a list of indexes. |
query->arg_query | Enter the argument that is to be passed to the script to retrieve a list of values given a field name. |
query->arg_get | Enter the argument that is to be passed to the script to retrieve a single value given a field name and index value. |
query->output_delimeter | Enter the one character delimiter that will be used to separate output values. This is only used when you "query" the script in which case it outputs 'index(delimiter)value'. |
query->fields | Each field contained within the script query must be defined under this tag. |
query->fields->dskDevice | Each defined field in the script query must have a unique name given to it. Do not use spaces or any non-alphanumeric characters, this name must be identifiable within Cacti. |
query->fields->dskDevice->name | Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field. |
query->fields->dskDevice->direction | There are two types of fields when dealing with an script query, 'input' and 'output'. Input values are the "known" values that you will use to derive the output values, this is where the "query" part of script query comes in. When you create a graph based on an script query, Cacti will prompt you to choose the input value to base the graph on. A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed. |
query->fields->dskDevice->query_name | Enter the name that Cacti must use when asking the script for information about this field. For instance, the following should return values: '(script_name) query (query_name)'. |
Creating a Data Query
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 "Data Queries" under the "Data Gathering" heading, and select "Add". You will be prompted for some basic information about the data query, described in more detail below.
Name | 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. |
Description | (Optional) Enter a more detailed description of the data query including the information it queries or additional requirements. |
XML Path | 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. |
Data Input Method | 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. |
When you are finished filling in all necessary fields, click the "Create" 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.
Under the 'Data Input Method' box, you need to specify mappings that tell Cacti where to send data it recieves from the data query. There are three data source fields that Cacti cares about when referring to a data query; index type, index value, and output type ID. Index type refers to the name of the input field to search in, while the index value contains the value to search for in that field. Lastly, output type ID specifies the ID of the "Associated Graph Template" to use. You do not have to worry about filling in values for these fields when creating data sources, Cacti will do that for you. Below are the default mappings that will work in almost all cases:
Index Type: Index Value: Output Type ID: |
SNMP Field Name (Dropdown) SNMP Field Value (From User) SNMP Output Type (Dropdown) |
Make sure to check the checkboxes to the right of these three fields, or the mappings will not be saved.
Associated Graph Templates
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 "Add" at the right of the "Associated Graph Templates" box. You will be presented with a few fields to fill in:
Name | 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. |
Graph Template | Choose the actual graph template that you want to make the association with. |
When you are finished filling in these fields, click the "Create" 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 "Associated Data Templates" box. For each data source item listed, you must selected the data query output field that corresponds with it. Do not forget to check the checkbox to the right of each selection, or your settings will not be saved.
The "Suggested Values" 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.
When you are finished filling in all necessary fields on this form, click the 'Save' 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.