Index of /~plonka/RRGrapher

Name	Last modified	Size

Parent Directory		-
Changes	2003-09-18 13:42	14K
RRGrapher_cgi.txt	2003-09-18 13:22	57K
ReadMe	2003-09-18 13:42	8.3K
old/	2014-05-25 12:02	-

README - information about RRGrapher

NAME
DESCRIPTION
Announcement
Availability
Mailing List
Prerequisites
Installation
Usage
Current Limitations, Bugs
Copyright and Disclaimer

NAME

README - information about RRGrapher

DESCRIPTION

RRGrapher, the Round Robin Grapher, is a Graph Construction Set for RRDTOOL. This document is the RRGrapher README $Revision: 1.12 $, $Date: 2003/09/18 18:42:00 $.

Announcement

I'm pleased to announce the latest release of RRGrapher.

RRGrapher is a ``companion'' tool for use with RRDTOOL that allows you to interactively build graphs of your own design. Also it allows you the freedom to use any combination of the RRDTOOL frond-ends such as MRTG, Cricket, or FlowScan to create and maintain the .rrd files, then generate graphs that containing data from any of those sources.

I originally wrote this tool in 1999, and upon releasing FlowScan, a front-end for RRDTOOL, I realized that I was using RRGrapher all the time and it'd be nice if other FlowScan users had access to it so they didn't go criminally insane trying to maintain rrdtool graph command lines by following my complex examples in FlowScan's graphs.mf Makefile.

Availability

RRGrapher is available under the terms of the GNU General Public License, and is available to you at:

   http://net.doit.wisc.edu/~plonka/RRGrapher/

Mailing List

There is an announcement mailing list having to do with RRGrapher:

rrgrapher-announce a low-volume, restricted post mailing list to keep RRGrapher users informed of news regarding RRGrapher.

This list is hosted by the Division of Information Technology's Network Services group at the University of Wisconsin - Madison. To subscribe send email to:

   majordomo@net.doit.wisc.edu

containing:

   subscribe rrgrapher-announce

You should receive an automatic response that will request that you verify your request to become a member of the list, to which you must reply with the authentication information there-in. Then, in response to your reply, you should receive a welcome message. If you have any questions about the administrative policies of this list's manager, please contact:

   owner-rrgrapher-announce@net.doit.wisc.edu

Prerequisites

   * perl version 5
   * RRDTOOL

Installation

Edit the script's CONFIGURATION SECTION (near the top) and then install it as ``.cgi'' script for the web server (e.g. Apache) running *on the same machine* as where the .rrd files reside.

Take a glance at the OPTIONAL CONFIGURATION too, espectially if your using IIS.

If you don't have, or want, Apache on the same machine as where you produce .rrd files, I've found it convenient to simply scp or rcp the .rrd files over to the web server periodically via cron.

Usage

Hopefully usage is somewhat self explanatory. Here's a step-by-step example, demonstrating the ``logic'':

You should see a list of Available Databases - these are the ``.rrd'' files in the directories that you configured. Select one or more of these which contain the data sources that you'd like to graph.
If the Database contains multiple Data Sources of different types, such as bytes and packets which wouldn't make sense to attempt to plot on the same graph, consider using the ``Data Source Filter RegExp'' to limit which Data Sources will be selected when you click ``Add>>''. E.g. I often enter ``bytes'' as the regular expression when using ``.rrd'' files created by FlowScan. One might enter ``ds[01]'' as the filter to get just in and out octets with Cricket-produced Databases.
Click ``Add>>'' to select the Data Sources.
Choose the ``Plot Type''. I often use ``AREA'' for the first Data Source, and ``STACK'' for all the subsequent Data Sources.
If desired, change the color selections. Clicking ``Update Colors'' isn't necessary unless you want to see them before generating the graph.
Add a Data Source of your own, using an RPN expression. This is an advanced option. You should understand how to use RRDTOOL's graph feature. An example would be to enter ``A,B,+,8,*'' to add source A and B, then convert from bytes to bits.
Click either ``Graph Data Sources'' or ``Graph Data Sources to GIF'' to produce the graph. The former results in the graph being displayed above the rest of the user-interface. ``Graph Data Sources to GIF'' is more suitable if you just want to see the result quickly and perhaps save the image to a file using your web browser.
You can continue to use the above steps to tweak the graphs as you'd like.
Once you have something you like, add it to your ``Bookmarks'' or ``Favorites'' of your web browser.
To do an entirely different graph, I'd suggest starting all over, rather than deleting the individual data sources.

Now that you've mastered that, here's another example which uses RPN expressions:

Let's say your using MRTG or Cricket. Typically, this means that the Data Source called ``ds0'' represents inbound bytes, and ``ds1'' represents outbound bytes. Let's create a graph that plots the outbound traffic above the horizontal axis, and the corresponding inbound traffic below it. This is a particularly useful visualization technique because it exposes the relationship inbound and outbound traffic levels, which is often somewhat symmetric.
To keep it simple, enter ``ds[01]'' as the ``Data Source Filter RegExp''. This should limit you to just the first two Data Sources - i.e. AVERAGE bytes. (If you were using FlowScan, ``bytes'' would be the RegExp to use.)
Select one of the RRD ``Databases'' and click ``Add>>''. You should now see two ``Data Sources'':
```
   A) ds0
   B) ds1
```
In the box next to the button that says `Add Data Source ``C'' as RPN Expression', enter ``A,-1,*'' and click on the button. Now you should have a third item in ``Data Sources'':
```
   C) A,-1,*
```
Change the ``Plot Type'' for Data Source ``A'' to ``NONE''.
Click on ``Graph Data Sources''. Voila! Your inbound traffic is plotted as negative, and your outbound is positive.

Current Limitations, Bugs

When RRGrapher gets an error, your web browser might show a broken graph icon, or an error message might be placed into your web server log. Please check your web server error log when RRGrapher doesn't seem to be working. It was my intention to make those error messages display to the user in the web browser, but I probably missed some.

RRGrapher is slow on some machines, on some network connections, and with some web browsers.

Its performance is partly based on the number of rrd files you make available to it in your configuration. Currently, it's faster to tell it to look in the ``leaf'' node directories than to have it recursively find all files under a ``root'' directory hierarchy, such as ``cricket-data''.

Slowness is also due in part to RRGrapher being a simple CGI - no fancy databases helping it along or anything. It sometimes causes hundreds of KBytes to be exchanged between the web server and browser. I'm making the browser do all the work by storing all the graph options in the form and in hidden fields.

To remedy this I'd need a database on the web server to store your queries, and would need to use cookies and lots of stuff that I don't have time to do right now, nor do I know if I ever want to write such a thing.

In the mean time, one way to speed things up once you've got a graph you like is to bookmark the URL of just the GIF output itself (i.e. use the ``Graph Data Source to GIF'' rather than simple the ``Graph Data Source'' button). Using mod_perl might help too.

Copyright and Disclaimer

Note that this document is provided `as is'. The information in it is not warranted to be correct. Use it at your own risk.

   Copyright (c) 2000-2003 Dave Plonka
   All rights reserved.

This document may be reproduced and distributed in its entirety (including this authorship, copyright, and permission notice), provided that no charge is made for the document itself.