NAME

Whisper - Handle Whisper fixed-size database files

SYNOPSIS

            

              
              
use Whisper;
# Read archive information
my $info = wsp_info( file => "/path/to/my/database.wsp"); 
# Fetch archive data
my $data = wsp_fetch( 
        file => "/path/to/my/database.wsp",
        from => $from,
        until => $until
);
# Fetch archive data in the tuples format: 
# { values => [ [timestamp, data], [timestamp,data], ... ] }
my $tuple_data = wsp_fetch(
        file => "/path/to/my/database.wsp",
        from => $from,
        until => $until,
        format => 'tuples'
);
# Fetch archive data in the split format: 
# { keys => [timestamp1, timestamp2], values => [data1, data2] }
   my $split_data = wsp_fetch(
       file => "/path/to/my/database.wsp",
       from => $from,
       until => $until,
       format => 'tuples'
   );
         
# Same as fetch tuple/split data but with POSIX::strftime formatted datetime
my $formatted_tuple_data = wsp_fetch(
        file => "/path/to/my/database.wsp",
        from => $from,
        until => $until,
        format => 'tuples'
        date_format => '%Y/%m/%d %H:%M:%S'
);
            
          

DESCRIPTION

This is a simple Whisper (fixed-size database) reader.

Whisper archive/databse files (.wsp) are similiar to RRD archive files. For more details about Whisper see http://graphite.wikidot.com/whisper

The following operations are supported:

            

              
              
wsp_info        Read basic archive information
wsp_fetch       Fetch data points from archive
            
          

These operations are planned:

            

              
              
wsp_create      Create wsp database
wsp_update      Add a data point to a wsp database
wsp_update_bulk Add multiple data points to a wsp database
wsp_merge       Merge two wsp database files
            
          

Feel free to help implement the above operations.

EXPORTS

By default, use Whisper exports all the functions listed below.

FUNCTIONS

wsp_info ( %parameters )

Parameters

            

              
              
file    String filepath towards a valid .wsp file
            
          

Returns

Returns a hash reference with Header/Metadata information:

            

              
              
{
        'aggregationType' => 1,
        'fileSize' => 32872,
        'archiveCount' => 2,
        'xFilesFactor' => '0.5',
        'maxRetention' => 2592000
        'archives' => [
                {
                        'secondsPerPoint' => 300,
                        'points' => 2016,
                        'retention' => 604800,
                        'size' => 24192,
                        'offset' => 40
                },
                {
                        'secondsPerPoint' => 3600,
                        'points' => 720,
                        'retention' => 2592000,
                        'size' => 8640,
                        'offset' => 24232
                }
        ],
};
            
          

wsp_fetch ( %parameters )

Parameters

            

              
              
- file          String filepath towards a valid .wsp file
- from          epoch timestamp, defaults to oldest timepoint in archive
- until         epoch timestamp, defaults to now
- format                Valid formats are:
   - tuples     returns the values in a tuple format: [ [timestamp1, data1], [timestamp2, data2], ... ]
   - split      returns an array for the timestamps in 'keys' and one for the data in 'values': { keys => [timestamp1, timestamp2], values => [data1, data2] }
- date_format   Dictates the POSIX::strftime format for timestamps in tuples, defaults to epoch timestamp: %s
            
          

Returns

Returns a hash refrence with data points and meta data for the given range:

            

              
              
{
        'step' => 300,
        'end' => 1374830700,
        'start' => 1374830100,
        'values' => [
                '0.000000',
                '1.000000'
        ],
        'cnt' => 2
};
            
          

In combination with tuples format, the values is an array of arrays with timestamp,data tuples:

            

              
              
{
        'step' => 300,
        'end' => 1374830700,
        'start' => 1374830100,
        'values' => [
                [ 1374830100, '0.000000' ],
                [ 1374830400, '1.000000' ]
        ],
        'cnt' => 2
};
            
          

In combination with split format, the values are accessible under 'values' and timestamps under 'keys'

            

              
              
  {
      'step' => 300,
      'end' => 1374830700,
      'start' => 1374830100,
      'values' => [
          '0.000000',
          '1.000000'
      ],
'keys' => [
        1374830100,
        1374830400
],
      'cnt' => 2
  };
            
          

Or in combination with date_format .e.g: "%Y/%m/%d %H:%M"

            

              
              
{
        'step' => 300,
        'end' => '2013/07/26 11:25',
        'start' => '2013/07/26 11:15',
        'values' => [
                [ '2013/07/26 11:15', '0.000000' ],
                [ '2013/07/26 11:20', '1.000000' ]
        ],
        'cnt' => 2
};
            
          

CVS

Current CVS: https://github.com/corecache/libwhisper-perl

COPYRIGHT AND LICENSE

Original Copyright 2008 Orbitz WorldWide (python) Perl port 2013 Jean Stebens (perl)

cpanm Whisper

perl -MCPAN -e shell
install Whisper