File	Date	Author	Commit
cgi-bin	2012-08-22	Petteri Tolonen	[c86305] changed handling of beforeunload to unload, bec...
css	2012-08-14	Petteri Tolonen	[2000ab] The initial release.
js	2012-08-14	Petteri Tolonen	[2000ab] The initial release.
LICENSE.txt	2012-08-15	Petteri Tolonen	[e77330] Added license file, and notice about the extern...
README.txt	2012-08-21	Petteri Tolonen	[c8c0d1] Moved index* to cgi-bin/ so only need to enable...

Read Me

CollectD-CSV Plotter
====================

A simple browser interface for visualizing CollectD CSV data.

Notes
-----
jQuery UI plugins bundled with CollectD-CSV Plotter (in /js): 
- spinner v1.20 (https://github.com/btburnett3/jquery.ui.spinner)
- datetimepicker v1.0.1 (http://trentrichardson.com/examples/timepicker)

Requirements
------------
The server hosting CollectD-CSV Plotter needs the following features:
- HTTP server with support for python CGI scripts (e.g. Apache)

- Python 2.7.3 or later (older versions might work.. not tested)

- GNUplot 4.6.0 or later (4.4.X doesn't work)

- collectd-csv module installed from PyPI 
(http://pypi.python.org/pypi/collectd-csv)

- sed (for a workaround of a gnuplot bug)

Client (browser) requirements:
- JavaScript support

- HTML5 support - canvas-element (mandatory) and localStorage (optional)

Installation
------------

0) Install Collect-CSV module from PyPI 
(http://pypi.python.org/pypi/collectd-csv). This module will be used for 
fetching the data. 
You can use easy_install:

First install setuptools to get easy_install, if you don't have that yet
> sudo apt-get install python-setuptools
> easy_install collectd-csv

Or you can use pip
To get pip you can use easy_install for example
> easy_install pip
> pip install collectd-csv

1) Choose a site root directory, where you want to install the Plotter. 
The usual choice is something like /var/www or /home/username/public_html

2) Install Apache or some other HTTP server that allows you to run CGI
applications (mod_cgi in Apache)

3) Configure your server to allow running CGI-scripts in the 
<siteroot>/cgi-bin directory and set root directory index to 
cgi-bin/index.py. Here's part of my apache site configuration 
(/etc/apache2/sites-available/default) for example:

<Directory /var/www/>
    DirectoryIndex cgi-bin/index.py
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

<Directory "/var/www/cgi-bin/">
    AllowOverride None
    AddHandler cgi-script .py 
    Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
    Order allow,deny
    Allow from all
</Directory>


4) Install gnuplot (4.6.0 or newer) on the server. If you are using Ubuntu
precise you have to install gnuplot from the quantal repository.

5) Copy the collectd-csv plotter repository to <siteroot>. Git clone can
be used. The server process should be able to write to the plot/data 
cache directory (as default <siteroot>/plots), so change the owner of this
directory to "www-data".

6) Copy the files needed by the Gnuplot canvas terminal somewhere under 
your CollectD-CSV Plotter site root. A good choice is <siteroot>/js/gnuplot_js.
On ubuntu they are located in /usr/share/gnuplot/gnuplot/4.6/js. 

7) cgi-bin/Conf.py includes paths that Plotter will use. If needed, edit these
accordingly. See comments in Conf.py for more information.

After all this you should be able to access the index.py with your browser.

To really make use of the Plotter, there should be CollectD CSV data available. 
It doesn't mean, that CollectD has to be installed, but usually that's 
the case. I will not go into detail of installing CollectD here. 
See the documentation on their website: http://collectd.org/documentation.shtml

Limitations & Known Issues
--------------------------
- Some browsers (opera) don't support the beforeunload-event, so data files 
cached in <siteroot>/plot/ are not cleaned and the form state is not saved.
If these kind of browsers are used a lot, the <siteroot>/plots directory will
bloat. A cron job cleaning up the directory of unused files might be a good
idea.

- The date/time input is in local time, so things get messy, if the collectd 
server and client are on different time zones. Quite easy to change to UTC, 
but this was chosen for convenience in a specific use case.