Total Pageviews

Friday 30 September 2016

ganglia web

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.

Requirements

It is recommended that you install the PHP JSON extension. It isn't *required*, but it provides better performance than the Net_JSON PEAR extension. The extension 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 fromhttps://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
  bash
  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/

Troubleshooting

  • you need to copy `/var/www/ganglia2/apache.conf` (Ubuntu/Debian) or `/var/www/html/ganglia2/apache.conf` (CentOS/RHEL) to `/etc/apache2/sites-enabled`.
  • In most cases, you need to modify the above apache.conf to make sure the alias /ganglia refers to `/var/www/ganglia2` (Ubuntu up to 13.10/Debian) or `/var/www/html/ganglia2` (CentOS/RHEL/Ubuntu 14.04+) .
  • In most cases, you need to modify `/var/www/ganglia2/conf.php` (Ubuntu/Debian) to make sure `gweb_confdir` refers to the directory where the directories of `conf` and `dwoo` locate in, such as `/var/lib/ganglia-web` or `/var/lib/ganglia`.
  • Make sure you have the dir of rrds under `gmetad_root` e.g. /var/lib/ganglia/rrds
  • Make sure the above RRD files are owned by the same user as one running as gmetad e.g. nobody

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 the following override file
  php
  <?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 `$conf['gmetad_root']` variable please check any other variables that depend on it like `$conf['conf_dir']` and `$conf['views_dir']`.

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 Migrating PHP Graphs to Gweb 2to 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

KeyExpected Value
report_nameTextual name of this report, used to identify the report to the engine. This should be the filename without the '.json' extension.
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`.
graphiteAmpersand separated list of arguments to be passed to Graphite targets.
percentUsually omitted. When specified with a value of '1', the graph is formed with all values being represented as a percentage of the aggregate total of all metrics.
titleUsed to label the top of the graph.
vertical_labelLabel for the y-axis.
scaleScaling factor. All values are multiplied by this number before being graphed or displayed in the legend. (Normally omitted, which is equivalent to specifying "1")
seriesAn array of hashes, describing which metrics should be part of the graph.
show_totalIf defined and set to '1', this adds an aggregate total for all of the displayed metrics to the graph legend.
`series` member hashes should contain the following values
KeyExpected Value
metricThe name of the metric to graph. Corresponds to an rrd file.
colorA hex value to color the line/area for this metric.
labelLabel text for use in the graph's legend.
type`line`, `stack`, `area` or `percentile`. Difference between stack and area are that if you specify something as a stack is that all stacked values will be stacked on top of each other whereas area types will not be stacked on top of each other. Percentile is a vertical line that displays percentile value for particular metric. Valid values are 0-100.
line_width'1', '2', or '3'. Only relevant for `type`==`line` or `type`==`percentile`.
percentileYou need specify percentile value for the percentile line e.g. 75, 95 etc.

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".
 json
 {
   "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 link:https://github.com/ganglia/ganglia-web/blob/master/graph.d/apache_response_report.json[apache_response_report.json] for an example.

Examples

Network Report

json
 {
   "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 graph:
    Sample Network Report Graph

CPU Report

This link:https://github.com/ganglia/ganglia-web/blob/master/graph.d/cpu_report.json[CPU]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.
  json
  {
    "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
.Example aggregate stacked graph Example aggregate stack 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.
  php
  $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.

View configuration file

KeyExpected Value
view_nameName of the view
view_typeStandard or Regex. Regex view allows you to specify regex to match hosts
itemsAn array of hashes, describing which metrics should be part of the view.
`items` member hashes should contain the following values
KeyExpected Value
hostnameHostname of the host for which we want metric/graph displayed
metricName of the metric e.g. load_one.
graphGraph Name e.g. cpu_report, load_report. You can use only metric or graph keys but not both
aggregate_graphIf 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.
You can also embed composite graph/reports as described in the JSON definition above. The only difference is that you are required to add a unique key called item_id to identify the graph e.g.
  json
  {
     "item_id": "abcde",
     "report_name" : "load_all_report",
     "report_type" : "standard",
     "title" : "Load All Report",
     "vertical_label" : "load",
     "series" : [
        { "hostname": "localhost", "clustername": "unspecified", "metric": "load_one", "color": "9933bb", "label": "95th percentile", "percentile": 95, "line_width": "2", "type": "percentile" },
        { "hostname": "localhost", "clustername": "unspecified", "metric": "load_one", "color": "3333bb", "label": "Load 1", "line_width": "2", "type": "line" },
     ]
    }

Example

  json
  {
    "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

Using Graphite as the graphing engine

New in Gweb 2.0 is the ability to generate graphs using link:http://graphite.wikidot.com[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 link:http://graphite.readthedocs.org/en/latest/install.html[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 link:https://github.com/vvuksan/ganglia-misc/tree/master/graphite[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`:
  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`):
  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.
WARNING: 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
  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.
  php
  $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 ashttp://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.
from https://github.com/ganglia/ganglia-web/wiki#Installation
--------
This is an attempt to make the Ganglia UI more usable. 

from https://github.com/ganglia/ganglia-web