Jean Stebens > Whisper-1.033 > Whisper

Download:
Whisper-1.033.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.033   Source   Latest Release: Whisper-1.035

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: [ [timestamp, data], [timestamp,data], ... ]
        my $tuple_data = wsp_fetch(
                file => "/path/to/my/database.wsp",
                from => $from,
                until => $until,
                format => 'tuples'
        );
        
        # Same as fetch tuple 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 and one for the data: [ [timestamp1, timestamp2], [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
        };

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)

syntax highlighting: