Events

Overlay events and events timeline is a feature added starting in Ganglia Web 2.1.0. It allows you to add vertical lines in the timeline to denote "events" e.g. "DB export", "Deployment" etc. It is a great way to add context to graphs. For example events timeline in this graph gives us immediate context to why is the load on the machine elevated.

Another way to display this info is this way

Configuration

Events are turned on by default. To disable them you will need to set following value in conf.php

$conf['overlay_events'] = false;

There are couple other options you can tune if you desire.

Type of line used to denote events.

$conf['overlay_events_line_type']  "dashed" (default) or "solid"

What is the provider used to provide events. Currently only JSON files supported

$conf['overlay_events_provider'] = "json";

Where is the Overlay events file stored. Defaults to /var/lib/ganglia/conf/events.json.

$conf['overlay_events_file'] defaults to $conf['conf_dir'] . "/events.json";

For event shading. Value in hex, 'FF' = 100% opaque. The _shade_ value should be less than _tick_

$conf['overlay_events_tick_alpha']  = '30';
$conf['overlay_events_shade_alpha'] = '50';

Events File

At this time the only way to provide events to Ganglia is using a JSON array. There

Key	Value
event\_id	Unique id of an event. This is currently optional. Needed if you want to delete or edit events through the API
start\_time	Start time of an event. It can be either "now" or anything else parseable by PHP's strtotime function e.g. 2011-05-23 20:11:11
end\_time	End time of an event. Same format as start time. This is an optional value
summary	This is a short title that will show up in the graph legend. We suggest you keep it short in order not to crowd out the legend
description	A more verbose description of an event (optional). This will not show up in the legend however will show up in the Events Tab.
grid	Grid this event applies to. Currently not used. Defaults to "\*"
cluster	Cluster this event applies to. Currently not used. Defaults to "\*"
host\_regex	Host regular expression that this event applies to e.g. you can say (host1|host3|host5)

Example JSON

[
 {"event_id":"1234",
 "start_time":1308496361,
 "end_time":1308496961,
 "summary":"DB Backup",
 "description":"Prod daily db backup",
 "grid":"*",
 "cluster":"*",
 "host_regex":"centos1"},
 {event_id:"2345",
 "start_time":1308497211,
 "summary":"FS cleanup",
 "grid":"*",
 "cluster":"*",
 "host_regex":"centos1"}
]

API

You can manipulate Events using the API. Currently only three actions are supported: 'add', 'remove', and 'edit' events. We are working on adding new ones. Possible keys you can use are identical to the ones specified in the events file e.g. start_time, end_time, summary etc. The only addition is following

Key	Value
action	API action. It can be 'add' to add a new event, 'edit' to edit, 'remove' or 'delete' to remove an event

URL for the Events API is

http://yourgangliahost/ganglia/api/events.php

Examples

To add an event from your cron job simply execute a command like this

wget -O /dev/null -q "http://mygangliahost.com/ganglia/api/events.php?action=add&start_time=now&summary=Prod DB Backup&host_regex=db02"

API will return a JSON encoded status message with either

status = ok or status = error

If you are adding an event you will also get the event_id of the event that was just added in case you want to edit it later e.g. to add an end_time.