README

ORCA
====

Orca is a tool useful for plotting arbitrary data from text files onto
a directory on a Web server.  It has the following features:

    * Creates an HTML tree of HTML and image (PNG or GIF) files.
    * Creates an index of URL links listing all available targets.
    * Creates an index of URL links listing all different plot types.
    * No separate CGI set up required.
    * Can be run under cron or it can sleep itself waiting for file updates
      based on when the file was last updated.
    * Configuration file based.
    * Reads arbitrarily formatted text or binary data files.
    * Watches data files for updates and sleeps between reads.
    * Finds new files at specified times.
    * Remembers the last modification times for files so they do not have to
      be reread continuously.
    * Allows arbitrary grouping of data from different files into the same
      or different plots.
    * Allows arbitrary math performed on data read from one file.

An example of the output generated by Orca is located at:

    http://www.orcaware.com/orca/orca-example/

Orca is written completely in Perl.  To install, configure and use Orca,
read the INSTALL file.  Some sample configuration files for Orca can be
found in the lib directory.

For an overview of the design decisions that made Orca what it is today,
read the article

    http://www.sunworld.com/sunworldonline/swol-07-1999/swol-07-realtime.html

Orca is based on the RRDtool written by Tobias Oetiker.  To really
understand Orca and how it saves and manages your data, you should
understand RRDtool, which serves as the backend binary data filestore.
I recommend reading the documentation that comes with RRDtool.  It will
explain how the data files Orca uses are created, maintained, and used
to create the images that Orca creates.  Read about RRDtool at

    http://people.ethz.ch/~oetiker/webtools/rrdtool/

DATA COLLECTION TOOLS
=====================

Orca does not generate the data itself that it plots.  This is left for
other programs.  Currently only one such data gathering and measuring
program is included here with Orca.

    orcallator.se
    ==============

    The other tool in this package is an updated version of
    orcallator.se written by Adrian Cockcroft.  Percollator.se
    is a tool written for Solaris SPARC and Solaris x86 that
    collects a large amount of system and web server statistics
    and prints them into a file for later processing and plotting.
    For documentation on the original orcallator.se tool, see the URL
    http://www.sunworld.com/swol-03-1996/swol-03-perf.html

    This version of orcallator.se collects much more data than the
    original on Solaris systems.  I have designed an Orca configuration
    file designed to read the output of this orcallator.  Sample output
    from this set up is displayed at

    http://www.orcaware.com/orca/orca-example/

    Documentation on the data that orcallator.se collects can be viewed at

    http://www.orcaware.com/orca/docs/orcallator.html

DOWNLOAD AT
============

These tools are available for download from

http://www.orcaware.com/orca/

KEEPING BLAIR HAPPY
===================

If you want to show your appreciation for Orca, go to

http://www.orcaware.com/wish_list.html

MAILING LISTS
=============

Four mailing lists exist for Orca.  To subscribe to any of the mailing
lists, please visit the URL listed below.  You have the option of
choosing a digest form of the mailing list when you subscribe to the
mailing list or anytime thereafter.  To send email to any of these
lists you must subscribe to the list.

orca-announce@orcaware.com

    The orca-announce@orcaware.com mailing list is a *low* volume
    moderated mailing list for announcing stable releases of Orca and
    affiliated data measurement tools used with Orca.

    Home                http://www.orcaware.com/mailman/listinfo/orca-announce
    Subscribe via web   http://www.orcaware.com/mailman/listinfo/orca-announce
    Subscribe via email orca-announce-request@orcaware.com
                        with subject "subscribe"
    Archive             http://www.orcaware.com/pipermail/orca-announce/

orca-users@orcaware.com

    The orca-users@orcaware.com is the mailing list for Orca users.
    Problems relating to downloading, configuring, compiling the
    necessary Perl modules, installing and configuring Orca belong
    here.

    Home                http://www.orcaware.com/mailman/listinfo/orca-users
    Subscribe via web   http://www.orcaware.com/mailman/listinfo/orca-users
    Subscribe via email orca-users-request@orcaware.com
                        with subject "subscribe"
    Archive             http://www.orcaware.com/pipermail/orca-users/

orca-dev@orcaware.com

    The orca-dev@orcaware.com mailing list is for Orca developers who
    develop Orca or its affiliated data gathering tools.

    Home                http://www.orcaware.com/mailman/listinfo/orca-dev
    Subscribe via web   http://www.orcaware.com/mailman/listinfo/orca-dev
    Subscribe via email orca-dev-request@orcaware.com
                        with subject "subscribe"
    Archive             http://www.orcaware.com/pipermail/orca-dev/

orca-checkins@orcaware.com

    The orca-checkins@orcaware.com is a publically accessible,
    moderated list which is used to disseminate version control
    check-in messages made by the Orca maintainers, to the Orca
    developer community.  This list is an adjunct to the publically
    available Subversion tree currently residing on OrcaWare. If you
    intend to follow the Subversion checkins, you should also join the
    orca-dev@orcaware.com mailing list for discussions.

    Home                http://www.orcaware.com/mailman/listinfo/orca-checkins
    Subscribe via web   http://www.orcaware.com/mailman/listinfo/orca-checkins
    Subscribe via email orca-checkins-request@orcaware.com
                        with subject "subscribe"
    Archive             http://www.orcaware.com/pipermail/orca-checkins/

INSTALLATION
============

Read and follow the installation steps in INSTALL.

AUTHOR
======

These two tools were written by Blair Zajac.  I welcome any patches
for bugs or improvements, comments and suggestions.  Please send any
Orca correspondence to orca-dev@orcaware.com or
orca-users@orcaware.com, which I read and participate on.

If you wish to contact me directly, my email address is
blair@orcaware.com.

NAMING OF ORCA
==============

I originally named Orca FMRTG, but after asking my wife Ashley
Rothschild (http://www.rothschildimage.com) for some suggestions, she
came up with Orca.  It turns out that there are only one or two small
programs on the Internet named Orca, so the name stuck.