Introduction

Starting with Ganglia version 3.1.x, the web front end supports a new method of generating graphs and custom reports. Previous versions used a single, monolithic graph.php file that was responsible for all graph generation. This made adding new graphs difficult, and made maintenance on existing graphs problematic. To get around these problems, the graphing system was made more general, and (hopefully) easier to use.

Structure

All requests for graphs that Ganglia handles still go through graph.php; however, code has been added that will automatically make use of a specific .php file that is responsible for that specific graph. All simple metric graphs (as seen in the host view, for example), are routed through the metric.php file. The CPU report and memory reports are routed through the cpu_report.php and memory_report.php file, respectively.

All of these "graph handlers" are stored in the WEB/graph.d directory, where "WEB" is the top-level directory used by the webserver to publish the various Ganglia webpages. Ganglia ships with one general handler for metrics, five basic reports, and one heavily commented sample report.

[root@webserver /var/www/htdocs/ganglia/]# ls graph.d/
cpu_report.php       mem_report.php      network_report.php  sample_report.php
metric.php           load_report.php     packet_report.php

Adding Custom Reports

It is possible to add new custom reports, without making any changes to the "official" Ganglia PHP code (outside of a small tweak to conf.php). Adding new reports is a four step process:

1. All reports should be contained in a single PHP file with the name "YOURTEST_report.php" in the graph.d/ directory. Obviously, replace "YOURTEST" with something suitable.

2. The *_report function should return an associative array that contains a number of specifically named variables (listed below). Many of these values have reasonable defaults, and may not need to be changed (although you can if you wish). Other values must be set, or the graphing system will not function. The values you must set are:

   $series
   $title
   $vertical_label
   

(Note that these are values in the $rrdtool_graph hash, and not variables themselves.)

3. Within this file, you must have a PHP function called "YOURTEST_report" that takes a single array argument that is passed by reference (not by value!). The function definition for this will look something like this:

function temperature_report ( &$rrdtool_graph ) {
    $rrdtool_graph['vertical_label'] = 'Temperature (C)';
    $rrdtool_graph['title']          = 'CPU Temeratures';
    $rrdtool_graph['series']         = "... very long set of RRD tool RPN commands...";
}

4. Edit the $optional_graphs variable in the conf.php file to include the base name of your new report. Thus, if the function name is YOURTEST_report, and the PHP file is "YOURTESTS_report.php", include only "YOURTEST" in the $optional_graphs array.

   $optional_graphs = array('packets', 'YOURTEST');
   

Variables Listing

A list of all of the pre-populated variables that are understood by the graphing engine. Variables not in this list but included in the $rrdtool_graph array will be ignored.

$series

(string) holds the meat of the rrdgraph definition Required.

$title

(string) title of the report Required.

$vertical_label

(string) label for Y-Axis. Required.

$start

(string) Start time of the graph, can usually be left alone.

$end

(string) End time of the graph, also can usually be left alone.

$width and $height

(string) Width and height of *graph*, the actual image will be larger due to text elements and padding. These are normally set automatically, depending on the graph size chosen from the web UI. The $height value may need to be adjusted by increments of 14 to make the size of the graph the same as the others. See any of the official _report php files for examples. (This is related to the number of entries in the legend, with each line of text being 14 high.)

$upper-limit and $lower-limit

(string) Maximum and minimum Y-value for the graph. RRDtool normally will auto-scale the Y min and max to fit the data. You may override this by setting these variables to specific limits. The default value is a null string, which will force the auto-scale behavior.

$color

(array) Sets one or more chart colors. Usually used for setting the background color of the chart. Valid array keys are BACK, CANVAS, SHADEA, SHADEB, FONT, FRAME and ARROW. Usually, only BACK is set.

$extras

(string) Any other custom rrdtool commands can be added to this variable. For example, setting a different --base value or use a --logarithmic scale. If explicit values for $upper-limit or $lower-limit are set, consider passing "--rigid" in the $extras slot.

Global Variables

It is very likely that a number of global variables will be useful in writing the custom reports. Any variable defined by conf.php, get_context.php, or in graph.php may be imported directly into the *_report function. Several commonly used variables:

$context

The context in which the graph was called. This is useful if a graph should behave differently for a per-host report, or in one of the aggregation modes for multiple hosts or clusters. Valid values are "meta", "grid", "cluster" and "host".

$hostname

The hostname of the system in question (only useful when $context is "host").

$rrd_dir

The location of the correct RRD files for the given context. This variable should almost certainly be imported by all reports''

$range

The timeframe for the report, i.e. "hour," "day," "week," "month," and "year."

$size

The requested size of the report, i.e. "small," "medium," or "large." This is useful for suppressing text in the "small" and "medium" graph sizes.

Creating the report

The heart of the custom report is the $rrdtool_graph['series'] value. This variable stores a string with rrdtool RPN commands that will be used to actually generate the graphs. The other variables in the array are used for various labels, ranges, image geometry, and related metadata.

The $series variable should contain all of the various DEF, CDEF, VDEF, LINE, AREA, GPRINT, and COMMENT commands needed to create the graph. The $series variable should not contain any options to the rrdtool binary or output filenames (such as "myreport.png"). It may contain paths to the various source RRD files used in DEF statements, of course.

Putting it together

Please see the graph.d/sample_report.php file for further details. It is heavily commented version of the CPU report, and shows off how to create a useful report that works well in many different contexts.