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)

cpanm Whisper

perl -MCPAN -e shell
install Whisper