=cut

TITLE=architecture
DESCRIPTION=how the pieces fit together
KEYWORDS=architecture,design
DOCTOP=index
DOCPREV=index
DOCNEXT=releasenotes

=pod

=head1 Architecture

This will tell how the major pieces of remstats work together, when I finish it.

=head2 A Bit of History

There were several things which decided how remstats would work.  One of the
major ones was, of course, L<RRDtool|@@RRDTOOLHOME@@>.  I wanted to have good
graphs, without having to build them from scratch.  I liked the side benefit
that RRDs do not grow, lessening the file-management required.

I've dealt with various monitoring packages with long-running daemons which are
always needing to be restarted, or checked via cron jobs and I decided that
remstats wouldn't have that kind of problem.

Back in the bad old days, you couldn't count on having an SNMP agent available
on every platform, so I decided that remstats wouldn't require SNMP to work.
Now, of course, there is the wonderful 
L<Net-SNMP project|http://net-snmp.sourceforge.net/> to provide a portable
SNMP implementation.

I wanted it to be easily extendable, without having to completely understand
the guts of remstats.  This goal has not been met very successfully, though
I hope to improve this in the 2.x releases.  However, some folks have managed
to create new collectors, so I guess it wasn't a complete failure.

=head2 The Collection Process

The process of data collection in remstats is begun by the L<run-remstats2>
program.  (In older versions, L<run-remstats>, a more primitive program,
filled the same niche.)  It is started by cron at the minimum collection
interval.  It passes through several stages in the order listed in the
L<run config-file|configfile-run>.  Some of these stages may have conditions
on them.  E.G. the standard stage C<pagemakers> will only be run if the
remstats configuration has changed.

Each stage is described by a file in the
L<run-stages config-dir|configfile-run-stages>, which lists all the programs
to run.  These are all started and run in parallel.  When all the programs
(or pipelines) are finished, T<run-remstats2> moves to the next stage.

The standard stages are:

=over 4

=item check
- checks the configuration to make sure it's good, and as a side-effect
creates any required new/missing RRDs, other files or directories.

=item ping
- runs the L<ping-collector> to see which hosts are up, so as to avoid
wasting time on hosts which are down.  Hosts which aren't pinged are considered
to be "up" for collection purposes, to deal with un-pingable hosts.

=item collectors
- runs all the other L<collectors> in parallel

=item post-collector
- runs the L<error-collector>, which collects info on the collectors.

=item monitors
- runs the remstats L<monitors> which evaluate the current status of the
monitored systems and issue alerts, if warranted.

=item pagemakers
- runs a motley crew of programs to create various kinds of web pages, but
only if the configuration has changed.  One of the standard cron jobs will
touch the man configuration directory to force page generation once a day.

=back 4

=head2 Collectors

At the centre of remstats are the L<collectors>, and their L<servers>.  The
collectors do whatever they need to do to acquire data, reformat it to the
remstats standard collector form and pass it to an instance of the L<updater>
which does the RRD updating.  Some collectors have a corresponding server
which they will contact on remote hosts, and which will provide information
on request.  The servers do not know about the configuration of remstats and
are completely stand-alone; the collector will tell them what kind of data it
requires and the server will provide it in a standard form.

XXX
