NAME

    PoCo::RRDTool - POE interface to Tobias Oetiker's RRDTool

SYNOPSIS

      use POE qw( Component::RRDTool );

      my $alias = 'controller';

      my @create_args = qw(
          test.rrd
          --start now
          --step 30
          DS:X:GAUGE:60:0:10
          RRA:MAX:0.5:1:1
      );

      # start up the rrdtool component
      POE::Component::RRDTool->new(  
          -alias   => $alias,
          -rrdtool => '/usr/local/bin/rrdtool',
      );

      POE::Session->create(
          inline_states => {
              _start => sub {
                   # set a session alias so that we can receive events from RRDTool
                   $_[KERNEL]->alias_set($_[ARG0]);

                   # create a round robin database
                   $_[KERNEL]->post( 'rrdtool', 'create', @create_args );

                   # stop the rrdtool component
                   $_[KERNEL]->post( 'rrdtool', 'stop' );
              },
              'rrd_error' => sub {
                  print STDERR "ERROR: " . $_[ARG0] . "\n";
              }
          },
          args => [ $alias ],
      );

      $poe_kernel->run();

DESCRIPTION

    RRDtool refers to round robin database tool. Round robin databases have
    a fixed number of data points in them and contain a pointer to the
    current element. Since the databases have a fixed number of data points
    the database size doesn't change after creation. RRDtool allows you to
    define a set of archives which consolidate the primary data points in
    higher granularity. RRDtool is specialized for time series data and can
    be used to create RRD files, update RRDs, retreive data from RRDs, and
    generate graphs from the databases. This module provides a POE wrapper
    around the rrdtool command line interface.

METHODS

    new - creates a POE RRDTool component
    new() is the constructor for POE::Component::RRDTool. The constructor is
    PoCo::RRDTool's only public method. It has two optional named parameters
    alias and rrdtool.

    The alias parameter is the alias of the session that the PoCo::RRDTool
    instance will send events to as callbacks. It defaults to component. It
    is important to understand that an RRDTool instance ALWAYS uses the
    rrdtool alias to reference itself. Events are posted to the rrdtool
    alias and callbacks are posted to the alias set via the constructor.

    The rrdtool parameter is the name of the RRDTool command line utility.
    It defaults to /usr/local/bin/rrdtool.

    In the calling convention below the "[]"s indicate optional parameters.

        POE::Component::RRDTool->new(
            [-alias   => 'controller'],
            [-rrdtool => '/usr/local/bin/rrdtool'],
        );

EVENTS

    RRDTool events take the same parameters as their rrdtool counterpart.
    Use the RRDTool manual as a reference for rrdtool command parameters.

    The following events can be posted to an RRDtool component.

    create
      create a round robin database

            my @create_args = qw(
                test.rrd
                --start now
                --step 30
                DS:X:GAUGE:60:0:10
                RRA:MAX:0.5:1:1
            );
    
            $_[KERNEL]->post( qw( rrdtool create ), @create_args);

    update
      update a round robin database

            $_[KERNEL]->post( qw( rrdtool update test.rrd N:1 ) );

    fetch
      fetch data from a RRD

            my $callback = 'rrd_fetch_handler';

            my @fetch_args = qw( 
                test.rrd 
                MAX
                --start -1s
            );

            $_[KERNEL]->post( qw( rrdtool fetch ), $callback, @fetch_args );

    graph
      generate a graph image from RRDs

            my $callback = 'rrd_graph_handler';

            my @graph_args = (
                '-',
                '--start', -86400,
                '--imgformat', 'PNG',
                'DEF:x=test.rrd:X:MAX',
                'AREA:x#00FF00:test_data',
            );

            $_[KERNEL]->post( qw( rrdtool udpate ), $callback, @graph_args );

    info
      get information about a RRD

            my $callback = 'rrd_info_handler';

            $_[KERNEL]->post( qw( rrdtool info ), $callback, 'test.rrd' );

    xport
      generate xml reports from RRDs

            my $callback = 'rrd_xport_handler';

            my @xport_args = (
              '--start', -300,
              '--step', 300,
              'DEF:x=test.rrd:X:MAX',
              'XPORT:x:foobar',
            );

            $_[KERNEL]->post( qw( rrdtool xport ), $callback, @xport_args );

    dump
      dump a RRD in XML format

            my $callback = 'rrd_dump_handler';

            $_[KERNEL]->post( qw( rrdtool dump ), $callback, 'test.rrd' );

    stop
      stop an RRDTool component

            $_[KERNEL]->post( qw( rrdtool stop ) );

CALLBACKS

    The callbacks listed below are sent by the RRDTool component to the
    session alias passed to it's constructor. You can provide event handlers
    for them in the controlling session's constructor. However it is not
    required to handle any of the callbacks.

    rrd_status - notification of rrdtool runtimes
    Returns the user, system, and real time of the rrdtool process in ARG0,
    ARG1, and ARG2 respectively.

        POE::Session->create(
            inline_states => {
                'rrd_status' => sub {
                    my ($user, $system, $real) = @_[ARG0 .. ARG2];
                    print "u: $user\ts: $system\tr: $real\n";
                },
                ....,
            }
        );

    rrd_error - rrdtool error notification
    Returns error messages returned from rrdtool in ARG0.

        POE::Session->create(
            inline_states => {
                'rrd_error' => sub {
                    my $error = $_[ARG0];
                    print "Error: $error\n";
                },
                ....,
            }
        );

    rrd_stopped - rrdtool process stopped
    This callback provides a hook to do something when the rrdtool process
    is stopped.

        POE::Session->create(
            inline_states => {
                'rrd_stopped' => sub {
                    print "rrdtool stopped\n";
                },
                ....,
            }
        );

AUTHOR

    Todd Caine <todd@pobox.com>

BUGS

    The graph event doesn't support rrdtool's print method.

    There's probably more so send me an email and let me know how it worked
    or didn't work for you. I'd be interested to hear what kind of programs
    this component gets used in.

SEE ALSO

    An RRDTool Tutorial

    http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/tutorial/rrdtutorial.
    html

    The Main RRDTool Website

    http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/index.html

    The RRDTool Manual

    http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/manual/index.html