Skip to content

Ganglia Web 2

Jump to bottom
Ng Zhi An edited this page Jul 28, 2014 · 2 revisions

Overview

Ganglia Web 2 (gweb2) is a refresh of the Ganglia PHP UI. We plan to continue adding new features, and bringing the Ganglia web code up to date after some years of inattention. This page details some of the main new features which will be available in an upcoming release.

You can see these features in action right now at http://fjrkr5ab.joyent.us/ganglia-2.0/.

Requirements

You will need PHP JSON extension. It is included in PHP 5.2 and later. If you are on 5.1 use pecl to install e.g.

pecl install json

pecl is part of php-pear package on RHEL/CentOS. Make sure you add extension.json to your PHP extensions ie.

# cat /etc/php.d/json.ini 
extension=json.so

On RHEL/CentOS 4, you will also need phpize which comes with the php-devel package.

You will also need PHP XML support which is part of e.g. php-xml or php5-xml package. Without it export of graphs in CSV and JSON format will not work.

Installation

Latest release of Ganglia Web 2 can be downloaded from https://sourceforge.net/projects/ganglia/files/gweb/. Download the gweb tarball and unarchive it somewhere in your web tree then rename the resulting directory to a URL you want e.g. /var/www/ganglia2 (Ubuntu/Debian) or /var/www/html/ganglia2 (Centos/RHEL) e.g.

tar xvf gweb-1.9.9.2607M.tar.gz
mv gweb-1.9.9.2607M ganglia2

You can run Ganglia Web 2 in parallel to your existing Ganglia UI if you so desire. You can now opt to either run make to create the necessary directory structure or conduct a manual install.

Makefile install

Please edit the Makefile found in the tarball. Adjust the DESTDIR to where you copied the files e.g. /var/www/ganglia2 and APACHE_USER is the name of the user that runs the Apache server e.g. apache or www-data (Ubuntu/Debian). When done type

make install

Manual install

To install it manually execute following

APACHE_USER="apache"
DEST_DIR="/var/www/ganglia2"
sed -e "s|@varstatedir@|/var/lib|" conf_default.php.in > conf_default.php
install -o $APACHE_USER -d /var/lib/ganglia/dwoo
install -o $APACHE_USER -d /var/lib/ganglia/conf
chown -R $APACHE_USER $DEST_DIR/conf
rsync -a $DEST_DIR/conf/ /var/lib/ganglia/conf/

You should now be able to access Ganglia in your browser by going to e.g.

http://server/ganglia2/

Configuration

All of Ganglia configuration options can be found in conf_default.php. If you want to override them you will need to create a conf.php file. This way even if you upgrade Gweb 2.0 you will retain your customizations. For example I use a following override file

<?php

$conf['default_metric'] = "cpu_report";
$conf['graphreport_stats'] = false;
$conf['rrdtool'] = "env RRD_DEFAULT_FONT='DejaVuSansMono-Roman' /usr/bin/rrdtool";
$conf['rrdcached_socket'] = "/var/run/rrdcached/rrdcached.sock";
$conf['auth_system'] = "disabled";
?>

WARNING: If you end up changing $confgmetad_root? variable please check any other variables that depend on it like $confconf_dir? and $confviews_dir?.

New Features

Timeline Zooming

You can zoom to arbitrary time on the graph by clicking on any of the graphs in cluster and host views. Click and hold the mouse when you do an outline will show up which will allow you to select time range you want. Once you release the mouse button the whole page will reload and show the new range.

Defining Custom Graphs Via JSON

Ganglia has supported the definition of custom graphs via PHP files for some time. Gweb2 continues to support PHP-based graphs, and adds support for JSON-based graphs as well. Defining graphs in JSON is much simpler (you don't need to know any rrdtool syntax) and will probably suit most cases. If you need more flexibility than in possible given the syntax supported by the JSON format, then defining a graph in PHP is still an option. In order migrate your PHP-based graphs to Gweb2, you will need to make a few changes to your graphs as you copy them to the new install.

If a given report is defined in both PHP and JSON, the PHP file takes precedence.

JSON options

Key Expected Value report_type standard or template. Use template when you are using Graphite rendering, and want GWeb to replace HOST_CLUSTER in your Graphite config string with the actual name of the host the graph is for. This value is ignored when rendering with rrdtool. title Used to label the top of the graph. vertical_label Label for the y-axis. series An array of hashes, describing which metrics should be part of the graph.

series member hashes should contain the following:

Key Expected Value metric The name of the metric to graph. Corresponds to an rrd file. color A hex value to color the line/area for this metric. label Label text for use in the graph's legend. type line or stack. stack is an rrdtool term for area. The area under the line will be filled. line_width '1', '2', or '3'. Only relevant for type==line.

Show metric only in certain contexts

There are certain such as number of nodes (servers) in a cluster that will show only in meta and cluster contexts. You can define those metrics by adding a contexts array to the JSON definition for an item. You can also override the DS (datasource name) to be something other than the default "sum".

      { "metric": "cpu_num", "color": "00FF00", "label": "Nodes",
"line_width": "2", "type": "line", "ds": "num", "contexts": [ "cluster", "meta" ] },

Graphite Integration

If you are using the graphite integration features in GWeb2, you may add additional syntax to a JSON graph file to configure your graph for Graphite rendering. See source:/trunk/branches/monitor-web-2.0/graph.d/apache_report.json for an example.

Examples

source:/branches/monitor-web-2.0/graph.d contains many examples.

Network Report

The network report is a good basic example of a simple 2-line graph.

{
  "report_name" : "network_report",
  "report_type" : "standard",
  "title" : "Network",
  "vertical_label" : "Bytes/sec",
  "series" : [
    { "metric": "bytes_in", "color": "33cc33", "label": "In", "line_width": "2", "type": "line" },
    { "metric": "bytes_out", "color": "5555cc", "label": "Out", "line_width": "2", "type": "line" }
  ]
}

Example network report, defined via JSON.

CPU Report

This CPU report is set up for use with Graphite. Note that it would be possible to also define a series key here, and the report would work with rrdtool as well.

{
  "report_name" : "cpu_report",
  "report_type" : "template",
  "title" : "CPU",
  "graphite"  : "target=alias(HOST_CLUSTER.cpu_user.sum,'User')&
target=alias(HOST_CLUSTER.cpu_nice.sum%2C'Nice')&target=alias(HOST_CLUSTER.cpu_system.sum,'System')&
target=alias(HOST_CLUSTER.cpu_wio.sum,'Wait')&target=alias(HOST_CLUSTER.cpu_idle.sum%2C'Idle')&
areaMode=stacked&max=100&colorList=3333bb,ffea00,dd0000,ff8a60,e2e2f2"
}

See Also

Aggregate Graphs

Aggregate graphs allow you to overlay same metric

Aggregate Stacked graph

Views

Views are arbitrary collection of metrics. They are useful if you want to have an easy overview of e.g. load on the webservers, DB servers, as well as number of SQL queries on host1.

There are two ways to create/modify views. One is via the Web GUI and the other one programatically by defining views using JSON.

Web GUI

Create views

To create views click on the Views tab then Click Create View. Type your name then click Create. Next step is to add metrics to a view.

Add metrics to a view

Above or below each metric or composite graph is a plus sign. Click on it. A window will pop up. Select the view you want the metric to be added. Repeat the process for consecutive metrics.

JSON definition for views

Views are stored as JSON files in the conf_dir. Default for the conf_dir is in /var/lib/ganglia/conf. You can change that by specifying an alternate directory in conf.php ie.

$conf['conf_dir'] = "/var/www/html/conf";

You can create or edit existing files. Name for a view needs to start with view_ and end with .json e.g. view_1.json or view_jira_servers.json. It needs to be unique. This is an example definition of a view which will result with a view with 3 different graphs.

Key Expected Value view_name Name of the view view_type Standard or Regex. Regex view allows you to specify regex to match hosts items An array of hashes, describing which metrics should be part of the view.

items member hashes should contain the following:

Key Expected Value hostname Hostname of the host for which we want metric/graph displayed metric Name of the metric e.g. load_one. graph Graph Name e.g. cpu_report, load_report. You can use only metric or graph keys but not both aggregate_graph If this value exists and is set to true item defines an aggregate graph. This item needs a hash of regular expressions and a description

If you add aggregate_graph item you need to specify a host_regex_hash that contains list of of regex elements. Please check the example for guidance on how to do it.

Example

 {
 "view_name":"jira",
 "items":[
  { "hostname":"web01.domain.com","graph":"cpu_report"},
  { "hostname":"web02.domain.com","graph":"load_report"},
  { "aggregate_graph":"true",
      "host_regex":[ 
        {"regex":"web[2-7]"},
        {"regex":"web50"}
      ],
      "metric_regex":[
        {"regex":"load_one"}
      ],
      "graph_type":"stack",
      "title":"Location Web Servers load"
  }
 ],
 "view_type":"standard"
 }

Automatic Rotation

Automatic rotation is a feature aimed for people in data centers that need to continuously rotate metrics to help spot early signs of trouble. It is intended to work in conjunction with views. To activate it click on Automatic Rotation then select the view you want rotated. Metrics will be rotated until the browser window is closed. You can change the view while the view is rotated and changes will be reflected within one full rotation.

Another powerful thing about automatic rotation is that if you have multiple monitors you can invoke different views to be rotated on different monitors.

Mobile

Mobile is a mobile optimized view for Ganglia. It is intended for any mobile browsers supported by jQueryMobile toolkit. This covers most WebKit? implementations ie. Android, iPhone iOS, HP webOS and Blackberry OS 6+. Interface intends to provide a better experience viewing Ganglia on your mobile phone by eliminating panning and zooming.

Search

Search allows you to find hosts and metrics quickly. It has multiple purposes ie.

  • Find a particular metric - especially useful if a metric is rare e.g. outgoing_sms_queue
  • Quickly find a host regardless of a cluster

To use click on the Search Tab and start typing in the search field. Start typing a search term. Once you stop typing a list of results will appear. Results will contain

  • First a list of matching hosts
  • Second list of matching metrics. If the search term matches metric on multiple hosts all hosts will be shown.

Click on any of the links and a new window will open that will take you directly to the result. You can keep clicking on the results and for each result a new window will open.

Authorization System

wiki:ganglia-web-2/AuthSystem

Using Graphite as the graphing engine

New in Gweb 2.0 is the ability to generate graphs using Graphite as the graphing engine as opposed to RRDtool.

First, install Graphite on the server that have direct access to the RRD files generated by Gmetad and RRDtool. You can follow the instructions found here.

For integration with Ganglia, you only need to install "whisper" and the "graphite webapp".

After Graphite has been installed, it needs to be patched to work with Ganglia. Get the respective patch for the version of Graphite you have installed here.

If you are using version 0.9.8 of Graphite, you might also want to apply the following patches:

To switch over to use Graphite for graph generation, you just need to add the following to conf.php:

$conf['graph_engine'] = "graphite";

You may or may not need to adjust the following configuration options in conf.php depending on your Graphite setup (these options should also be found in conf_default.php):

$conf['graphite_url_base'] = "http://127.0.0.1/render";
$conf['graphite_rrd_dir'] = "/opt/graphite/storage/rrd";

The directory structure of your RRD files will be symlinked to $conf['graphite_rrd_dir'] with some minor changes (such as replacing space with "_"). The actual RRD files will not be duplicated.

Note: Certain reports (such as CPU Report) currently does not work correctly as the JSON representation does not support certain metric calculations

Other misc. features

Export metric data in JSON/CSV

You will notice little CSV and JS icons next to graphs displayed. Clicking on these will export graph values for the displayed time period in a CSV (comma separated values) or JSON format. If there are multiple metrics used to create graphs like in e.g. CPU report all metrics will be exported.

Metric groups initially collapsed

By default when you click on a host view all of the metric groups are expanded. You can change that so that only metric graph titles are showing and you have to click on the metric group to expand the view. To default to metric groups initially collapsed add following setting in conf.php

$conf['metric_groups_initially_collapsed'] = true;

Filter hosts in cluster view

If you'd like to display only certain hosts in the cluster view you can filter them out using the text box that is located next to the Show Node drop down. Filter accepts regular expressions ie. you can show any host that has web in it's name by putting

web

or to filter out webservers web10-web17 you could type

web1[0-7]

or show me web03 and web04 and all mysql servers

(web-0[3,4]|mysql)

Max graphs to show in cluster view

This feature has existed before but has been enhanced. This feature is intended to speed up cluster view rendering when you have lots of hosts in a cluster ie. hundreds or thousands. This will result in large load times as all images are rendered and downloaded. Instead you can opt to show only first X graphs. Rest of the graphs will not be loaded and will be replaced with a placeholder showing current metric value. You can do that on the fly by selecting from the drop down menu. You can also set a default by setting it in conf.php ie.

$conf['max_graphs'] = 100;

RRDtool Slope Mode

You can now enable slope mode for your RRDtool graphs. This option is disabled by default. Slope mode is defined in RRDtool documentation as

http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html

RRDtool graphs are composed of stair case curves by default. This is in line with the way RRDtool calculates its data. Some people favor a more 'organic' look for their graphs even though it is not all that true.

Here is an example of two different presentations. First one is standard and the second is one with slope mode turned on

Standard (no-slope-mode) output

Attachments

Clone this wiki locally