NAME
Tapper::Benchmark - Autonomous SQL backend to store benchmarks
SYNOPSIS
require YAML::Syck;
require Tapper::Benchmark;
my $or_bench = Tapper::Benchmark->new({
dbh => $or_dbh,
debug => 0,
config => YAML::Syck::LoadFile('~/conf/tapper_benchmark.conf'),
});
my $b_success = $or_bench->add_single_benchmark({
NAME => 'testbenchmark',
UNIT => 'example unit',
testplanid => 813,
DATA => [
{
VALUE => 123.45,
testrun_id => 123,
machine => 'mx1.small',
benchmark_date => '2013-09-25 12:12:00',
},{
VALUE => 122.88,
testrun_id => 123,
machine => 'mx1.large',
benchmark_date => '2013-09-23 13:02:14',
},
...
],
},{
force => 1,
});
my $b_success = $or_bench->add_multi_benchmark([
{
NAME => 'testbenchmark',
UNIT => 'example unit',
VALUE => 123.45,
testrun_id => 123,
machine => 'mx1.small',
benchmark_date => '2013-09-25 12:12:00',
},{
NAME => 'testbenchmark',
UNIT => 'example unit',
VALUE => 122.88,
testrun_id => 123,
machine => 'mx1.large',
benchmark_date => '2013-09-23 13:02:14',
},
...
],{
force => 1,
});
my $or_benchmark_points = $or_bench->search({
select => [
'testrun_id',
'machine',
],
where => [
['!=', 'machine', 'mx1.small' ],
['=' , 'bench' , 'testbenchmark' ],
],
order_by => [
'machine',
['testrun_id','ASC',{ numeric => 1 }]
],
limit => 2,
offset => 1,
});
while my $hr_data_point ( $or_benchmark_points->fetchrow_hashref() ) {
...
}
my $b_success = $or_bench->subsume({
subsume_type => 'month',
exclude_additionals => [qw/ benchmark_date /],
date_from => '2013-01-01 00:00:00',
date_to => '2014-01-01 00:00:00',
});
DESCRIPTION
Tapper::Benchmark is a module for adding benchmark points in a standardised way to the the database. A search function with complexe filters already exists.
Class Methods
new
Create a new Tapper::Benchmark object.
my $or_bench = Tapper::Benchmark->new({ dbh => $or_dbh, debug => 0, config => YAML::Syck::LoadFile('~/conf/tapper_benchmark.conf'), });
add_single_benchmark
Add one or more data points to a single benchmark to the database.
my $b_success = $or_bench->add_single_benchmark({ NAME => 'testbenchmark', UNIT => 'example unit', data => [ { VALUE => 123.45, },{ VALUE => 122.88, testrun_id => 123, machine => 'mx1.large', benchmark_date => '2013-09-23 13:02:14', },{ VALUE => 122.88, testrun_id => 123, }, ... ], },{ force => 1 });
- 1st Parameter Hash => NAME
-
The name of the benchmark for grouping benchmark data points.
- 1st Parameter Hash => data
-
This parameter contains the benchmark data points. It's an array of hashes. The element
VALUE
is the only required element in this hashes. TheVALUE
is the benchmark data point value. - 1st Parameter Hash => UNIT [optional]
-
Containing a unit for benchmark data point values.
- 2nd Parameter Hash => force [optional]
-
Ignore forgivable errors while writing.
add_multi_benchmark
Add one or more data points for multiple benchmarks to the database.
my $b_success = $or_bench->add_multi_benchmark([ { NAME => 'testbenchmark 1', UNIT => undef, VALUE => 123.45, },{ NAME => 'testbenchmark 2', VALUE => 122.88, testrun_id => 123, machine => 'mx1.large', benchmark_date => '2013-09-23 13:02:14', },{ NAME => 'testbenchmark 1', UNIT => 'example unit', VALUE => 122.88, testrun_id => 123, }, ... ],{ force => 1 });
- 1st Parameter Array of Hashes => NAME
-
The name of the benchmark for grouping benchmark data points.
- 1st Parameter Hash => VALUE
-
The value is the benchmark data point value.
- 1st Parameter Hash => UNIT [optional]
-
Containing a unit for benchmark data point values.
- 1st Parameter Hash => all others
-
All other elements in the hashes are additional values added to this data point.
- 2nd Parameter Hash => force [optional]
-
Ignore forgivable errors while writing.
search
Search for benchmark data points in the database. Function returns a DBI Statement Handle.
my $or_benchmark_points = $or_bench->search({ select => [ 'testrun_id', 'machine', ], where => [ ['!=', 'machine', 'mx1.small' ], ['=' , 'NAME' , 'testbenchmark' ], ], where_sql => q#, AND NOT( ${testrun_id} = 123 OR ${VALUE} = '144' ) #, limit => 2, offset => 1, order_by => [ 'machine', ['testrun_id','ASC'] ], });
- select [optional]
-
An Array of Strings or Array References containing additional selected columns. The default selected columns are: NAME - name of benchmark UNIT - benchmark unit [optional] VALUE - value of benchmark data point VALUE_ID - unique benchmark data point identifier CREATED - benchmark data point created date in format YYYY-MM-DD HH:II:SS
Add additional data "testrun_id" and "machine" as columns to selection.
... select => [ 'testrun_id', 'machine', ], ...
Do the same as above.
... select => [ ['','testrun_id'], ['','machine'], ], ...
Get the maximum "testrun_id" of all selected data points. All other columns without an aggregation become the
default_aggregation
from Tapper::Benchmark-Configuration. Possible aggregation types are:- min = minimum - max = maximum - avg = average - gem = geometric mean - sum = summary - cnt = count - cnd = distinct value count ... select => [ ['max','testrun_id'], 'machine', ], ...
A aggregation is also possible for the default columns.
... select => [ ['max','testrun_id'], ['avg','VALUE'], ], ...
- where [optional]
-
An Array of Array References containing restrictions for benchmark data points.
... where => [ ['!=', 'machine', 'mx1.small' ], ['=' , 'NAME' , 'testbenchmark' ], ], ...
1. Parameter in Sub-Array = restriction operator
= - equal != - not equal < - lower > - greater <= - lower equal >= - greater equal like - SQL LIKE not like - SQL NOT LIKE
2. Parameter in Sub-Array = restricted column
A restriction is possible for additional values and the default columns.
3 - n. Parameters in Sub-Array = value for restriction
In general there is just a single value. For '=' and '!=' a check for multiple values is possible. In SQL it is implemented with IN and NOT IN.
- where_sql [optional]
-
A String containing an additional where clause. Please use this feature just if the "where" parameter is not sufficient to restrict.
- order_by [optional]
-
An Array of Strings or an Array of Array References determining the order of returned benchmark data points.
Array of Strings: column to sort with default order direction "ASC" (ascending)
Array of Array References 1. Element: column to sort 2. Element: order direction with possible values "ASC" (ascending) and "DESC" (descending) 3. Element: hash of additional options. Possible values: numeric: Set a true value for a numeric sort
... order_by => [ 'machine', ['benchmark_date','DESC'] ['testrun_id','ASC',{numeric => 1}] ], ...
- limit [optional]
-
An integer value which determine the number of returned benchmark data points.
- offset [optional]
-
An integer value which determine the number of omitted benchmark data points.
search_array
Returning all benchmark data points as Array of Hashes.
my $or_benchmark_points = $or_bench->search_array({ select => [ 'testrun_id', 'machine', ], where => [ ['!=', 'machine', 'mx1.small' ], ['=' , 'NAME' , 'testbenchmark' ], ], limit => 2, offset => 1, order_by => [ 'machine', ['testrun_id','ASC'] ], });
search_hash
Returning all benchmark data points as Hash of Hashes. As compared to search
search_array
this function needs the parameterkeys
.keys
is an Array of Strings which determine the columns used as the keys for the nested hashes. Every "key" create a new nested hash.my $or_benchmark_points = $or_bench->search_array({ keys => [ 'testrun_id', 'machine', 'VALUE_ID', ], select => [ 'testrun_id', 'machine', ], where => [ ['!=', 'machine', 'mx1.small' ], ['=' , 'NAME' , 'testbenchmark' ], ], limit => 2, offset => 1, order_by => [ 'machine', ['testrun_id','ASC'] ], });
subsume
This is a maintenance function for reducing the number of data points in the database. Calling this function reduces the rows in the benchmark values table by building an average value for all benchmark data points grouped by specfic columns. By default all old grouped columns will be added to backup tables for rebuilding the original state. It is highly recommended to do this periodically for better search performance.
my $b_success = $or_bench->subsume({ subsume_type => 'month', exclude_additionals => [qw/ benchmark_date /], date_from => '2013-01-01 00:00:00', date_to => '2014-01-01 00:00:00', backup => 0, });
- subsume_type
-
The subsume of benchmark data points is made by group with the following elements:
- bench_id - additional data values ( Example: testrun_id, machine ) - specific data range ( subsume_type ). The possible subsume types are stored in the extrapolation_type_table ( Tapper::Benchmark-Configuration ). By default there are the following types: "second", "minute", "hour", "day", "week", "month", "year".
- date_from
-
Begin of subsume period.
- date_to
-
End of subsume period.
- exclude_additionals
-
Array Reference of additional values that should be excluded from grouping.
- backup
-
By default all subsumed rows will be inserted to backup tables. If this isn't desired a false value must be passed.
NAME
Tapper::Benchmark - Save and search benchmark points by database
Configuration
The following elements are required in configuration:
- default_aggregation
-
Default aggregation used for non aggregated columns if an aggregation on any other column is found.
- tables
-
Containing the names of the tables used bei Tapper::Benchmark
tables => { unit_table => 'bench_units', benchmark_table => 'benchs', benchmark_value_table => 'bench_values', benchmark_backup_value_table => 'bench_backup_values', subsume_type_table => 'bench_subsume_types', additional_type_table => 'bench_additional_types', additional_value_table => 'bench_additional_values', additional_relation_table => 'bench_additional_relations', additional_type_relation_table => 'bench_additional_type_relations', backup_additional_relation_table => 'bench_backup_additional_relations', }
- select_cache [optional]
-
In case of a true value the module cache some select results
AUTHOR
Roberto Schaefer <schaefr@amazon.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2015 by Amazon.com, Inc. or its affiliates.
This is free software, licensed under:
The (two-clause) FreeBSD License