Add a New Graph

You won't stop now as you've just created a device from cli. Surely, the task of setting up graphs is the next step. This is done using add_graphs.php. Calling the script with the parameter --help yields

shell>php -q add_graphs.php
Add Graphs Script 1.2, Copyright 2008 - The Cacti Group

A simple command line utility to add graphs in Cacti

usage: add_graphs.php --graph-type=[cg|ds] --graph-template-id=[ID]
    --host-id=[ID] [--graph-title=title] [graph options] [--force] [--quiet]

For cg graphs:
    [--input-fields="[data-template-id:]field-name=value ..."] [--force]

    --input-fields  If your data template allows for custom input data, you may specify that
                    here.  The data template id is optional and applies where two input fields
                    have the same name.
    --force         If you set this flag, then new cg graphs will be created, even though they
                    may already exist

For ds graphs:
    --snmp-query-id=[ID] --snmp-query-type-id=[ID] --snmp-field=[SNMP Field] --snmp-value=[SNMP Value]

    [--graph-title=]       Defaults to what ever is in the graph template/data-source template.

    [--reindex-method=]    the reindex method to be used for that data query
                           if data query already exists, the reindex method will not be changed
                    0|None   = no reindexing
                    1|Uptime = Uptime goes Backwards (Default)
                    2|Index  = Index Count Changed
                    3|Fields = Verify all Fields
List Options:
    --list-hosts
    --list-graph-templates [--host_template=[ID]]
    --list-input-fields --graph-template-id=[ID]
    --list-snmp-queries
    --list-query-types  --snmp-query-id [ID]
    --list-snmp-fields  --host-id=[ID] [--snmp-query-id=[ID]]
    --list-snmp-values  --host-id=[ID] [--snmp-query-id=[ID]] --snmp-field=[Field]

'cg' graphs are for things like CPU temp/fan speed, while
'ds' graphs are for data-source based graphs (interface stats etc.)

Like the graph creation from the console, this task is split into two different ones:

Exact typing required

When running this cli script, caution must be taken to avoid typos. Sometimes, list options take an ending "s", where the option for graph creation comes without "s". Error messages are not issued to indicate this typo; instead you will see the general help screen.

List Options for Associated Graph Templates

The first list option, --list-hosts, is required only if you do not know the id of the device you want to add graphs for. It will produce output as follows

shell>php -q add_graphs.php --list-hosts

Known Hosts: (id, hostname, template, description)
...
11      router.mydomain.com 3       Device Add Test

You surely recognize the device we've just added?

The next list option, --list-graph-templates, is required to identify the number of an Associated Graph Templates.

shell>php -q add_graphs.php --list-graph-templates

Known Graph Templates:(id, name)
2       Interface - Traffic (bits/sec)
3       ucd/net - Available Disk Space
4       ucd/net - CPU Usage
5       Karlnet - Wireless Levels
6       Karlnet - Wireless Transmissions
7       Unix - Ping Latency
8       Unix - Processes
9       Unix - Load Average
...

We will need the graph template id of the ucd/net - CPU Usage template later. So note the number 4 for it.

It is possible to reduce the listing to the graph templates associated with a specific host template by using --list-graph-templates --host-template-id=[id]. For a "ucd/net SNMP Host" this yields

shell>php -q add_graphs.php --list-graph-templates --host-template-id=3

Known Graph Templates:(id, name)
4   ucd/net - CPU Usage
11	ucd/net - Load Average
13	ucd/net - Memory Usage...

List Options for Associated Data Queries

First task is to find all id's for available data queries.

shell>php -q add_graphs.php --host-id=2 --list-snmp-queries

Known SNMP Queries:(id, name)
1       SNMP - Interface Statistics
2       ucd/net -  Get Monitored Partitions
3       Karlnet - Wireless Bridge Statistics
4       Netware - Get Available Volumes
6       Unix - Get Mounted Partitions
7       Netware - Get Processor Information
8       SNMP - Get Mounted Partitions
9       SNMP - Get Processor Information

For standard interface statistics, we note the id of 1

Next task is to find the query_type as done by issuing

shell>php -q add_graphs.php --snmp-query-id=1 --list-query-types

Known SNMP Query Types: (id, name)
2       In/Out Errors/Discarded Packets
3       In/Out Non-Unicast Packets
4       In/Out Unicast Packets
9       In/Out Bytes (64-bit Counters)
13      In/Out Bits
14      In/Out Bits (64-bit Counters)
16      In/Out Bytes
20      In/Out Bits with 95th Percentile
21      In/Out Bits with Total Bandwidth
22      In/Out Bytes with Total Bandwidth
23      In/Out Bits 1 min
24      In/Out Bits 1 min (64-bit Counters)

For a standard In/Out Bits type, we note the id of 13

Next issue is to select the SNMP Field that shall be used for a new graph.

shell>php -q add_graphs.php --host-id=11 --list-snmp-fields

Known SNMP Fields for host-id 11: (name)
ifAlias
ifDescr
ifHwAddr
ifIndex
ifIP
ifName
ifOperStatus
ifSpeed
ifType

For our graph, we will use the field ifOperStatus to select the correct interfaces.

In general, you will next determine the values available for the SNMP Field, in our case ifOperStatus. This is done by

shell>php -q add_graphs.php --host-id=11 --snmp-field=ifOperStatus --list-snmp-values

Known values for ifOperStatus for host 11: (name)
Down
Up

This is no surprise, of course. Now, all paarmeters required for creating a new graph are determined.

Add Non-Indexed Graphs

We will create a graph for ucd/net - CPU Usage. Above, we've identified the graph template it to be 4. In total, that makes up for the following command

shell>php -q add_graphs.php --host-id=11 --graph-type=cg --graph-template-id=4

Graph Added - graph-id: (39) - data-source-id: (63)

Find the result when visiting Graph Management

Graph Title** 			Template Name 		Size
Device Add Test - CPU Usage 	ucd/net - CPU Usage 	120x500

If the graph template was not associated with that host before, it is now added to the list of Associated Graph Templates.

Add Indexed Graphs

First, let's sum up the id's of all resources required for this task:

Table 20-2. Parametes required for an Interface Traffic Graph

ObjectValueDescription
Graph Template Id2Interface - Traffic (bits/sec)
SNMP Query Id1SNMP - Interface Statistics
SNMP Query Type Id13In/Out Bits
SNMP FieldifOperStatus 
SNMP ValueUp 

This will make up for the following command

shell>php -q add_graphs.php --host-id=11 --graph-type=ds --graph-template-id=2 --snmp-query-id=1 --snmp-query-type-id=13 --snmp-field=ifOperStatus --snmp-value=Up

Graph Added - graph-id: (40) - data-source-id: (65)

Find the result when visiting Graph Management

Graph Title** 				Template Name 				Size
Device Add Test - CPU Usage 		ucd/net - CPU Usage 			120x500
Device Add Test - Traffic - lo  	Interface - Traffic (bits/sec)  	120x500

If the data query was not associated with that host before, it is now added to the list of Associated Graph Templates. In this case, the Re-Index Method of Uptime Goes Backwards is defaulted if not given otherwise. You may provide a different Re-Index Method by entering the optional parameter --reindex-method.