The Cacti Manual
Prev | Chapter 20. Command Line Scripts | Next

# 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.0, Copyright 2007 - 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.

    List Options:
        --list-hosts
        --list-graph-templates
        --list-input-fields --graph-template-id=[ID]
        --list-snmp-queries
        --list-query-types  --snmp-query-id [ID]
        --list-snmp-fields  --host-id=[ID]
        --list-snmp-values  --host-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:

- Associated Graph Templates: These are named `cg` graph_type for this script.

- Associated Data Queries: These are named `ds` graph_type for this script. Additional SNMP parameters are required to define those graphs.

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.

## 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

## 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

Object | Value | Description
--- | --- | ---
Graph Template Id | 2 | Interface - Traffic (bits/sec)
SNMP Query Id | 1 | SNMP - Interface Statistics
SNMP Query Type Id | 13 | In/Out Bits
SNMP Field | ifOperStatus |
SNMP Value | Up |

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

Prev | Home | Next
Add a New Device | Up | Add Items to a Tree