The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
BenchmarkAnything-Storage-Frontend-Lib-0.023
River stage two • 6 direct dependents • 11 total dependents
/ BenchmarkAnything::Storage::Frontend::Lib

NAME

BenchmarkAnything::Storage::Frontend::Lib - Basic functions to access a BenchmarkAnything store

new

Instantiate a new object.

  • cfgfile

    Path to config file. If not provided it uses env variable BENCHMARKANYTHING_CONFIGFILE or $home/.benchmarkanything.cfg.

  • noconfig

    If set to 1, do not initialize configuration.

  • noconnect

    If set to 1, do not automatically connect to backend store.

  • really

    Used for critical functions like createdb. Provide a true value or, in case of "createdb", the DSN of the database that you are about to (re-)create.

  • skipvalidation

    Disables schema validation checking, e.g., when you know your data is correct and want to save execution time, ususally for add().

  • verbose

    Print out progress messages.

  • debug

    Pass through debug option to used modules, like BenchmarkAnything::Storage::Backend::SQL.

  • separator

    Used for output format flat. Sub entry separator (default=;).

  • fb

    Used for output format flat. If set it generates [brackets] around outer arrays (default=0).

  • fi

    Used for output format flat. If set it prefixes outer array lines with index.

_output_format

This function converts a data structure into requested output format.

Output formats

The following output formats are allowed:

 yaml   - YAML::Any
 json   - JSON (default)
 xml    - XML::Simple
 ini    - Config::INI::Serializer
 dumper - Data::Dumper (including the leading $VAR1 variable assignment)
 flat   - pragmatic flat output for typical unixish cmdline usage

The 'flat' output format

The flat output format is meant to support typical unixish command line uses. It is not a strong serialization format but works well for simple values nested max 2 levels.

Output looks like this:

Plain values

 Affe
 Tiger
 Birne

Outer hashes

One outer key per line, key at the beginning of line with a colon (:), inner values separated by semicolon ;:

inner scalars:

 coolness:big
 size:average
 Eric:The flat one from the 90s

inner hashes:

Tuples of key=value separated by semicolon ;:

 Affe:coolness=big;size=average
 Zomtec:coolness=bit anachronistic;size=average

inner arrays:

Values separated by semicolon ;:

 Birne:bissel;hinterher;manchmal

Outer arrays

One entry per line, entries separated by semicolon ;:

Outer arrays / inner scalars:

 single report string
 foo
 bar
 baz

Outer arrays / inner hashes:

Tuples of key=value separated by semicolon ;:

 Affe=amazing moves in the jungle;Zomtec=slow talking speed;Birne=unexpected in many respects

Outer arrays / inner arrays:

Entries separated by semicolon ;:

 line A-1;line A-2;line A-3;line A-4;line A-5
 line B-1;line B-2;line B-3;line B-4
 line C-1;line C-2;line C-3

Additional markup for arrays:

 --fb            ... use [brackets] around outer arrays
 --fi            ... prefix outer array lines with index
 --separator=;   ... use given separator between array entries (defaults to ";")

Such additional markup lets outer arrays look like this:

 0:[line A-1;line A-2;line A-3;line A-4;line A-5]
 1:[line B-1;line B-2;line B-3;line B-4]
 2:[line C-1;line C-2;line C-3]
 3:[Affe=amazing moves in the jungle;Zomtec=slow talking speed;Birne=unexpected in many respects]
 4:[single report string]

connect

Connects to the database according to the DB handle from config.

Returns the object to allow chained method calls.

disconnect

Commits and disconnects the current DB handle from the database.

Returns the object to allow chained method calls.

_are_you_sure

Internal method.

Find out if you are really sure. Usually used in "createdb". You need to have provided an option really which matches the DSN of the database that your are about to (re-)create.

If the DSN does not match it asks interactively on STDIN - have this in mind on non-interactive backend programs, like a web application.

createdb

Initializes the DB, as configured by backend and dsn. On the backend this means executing the DROP TABLE and CREATE TABLE statements that come with BenchmarkAnything::Storage::Backend::SQL. Because that is a severe operation it verifies an "are you sure" test, by comparing the parameter really against the DSN from the config, or if that doesn't match, asking interactively on STDIN.

_default_additional_keys

Internal method. Specific to SQL backend.

Return default columns that are part of each BenchmarkAnything data point.

_get_benchmark_operators

Internal method. Specific to SQL backend.

Return the allowed operators of the BenchmarkAnything query API.

_get_additional_key_id

Internal method. Specific to SQL backend.

Returns id of the additional key.

init_workdir

Initializes a work directory ~/.benchmarkanything/ with config files, which should work by default and can be tweaked by the user.

add ($data)

Adds all data points of a BenchmarkAnything structure to the backend store.

search ($query)

Execute a search query against the backend store, currently BenchmarkAnything::Storage::Backend::SQL, and returns the list of found data points, as configured by the search query.

listnames ($pattern)

Returns an array ref with all metric NAMEs. Optionally allows to restrict the search by a SQL LIKE search pattern, allowing % as wildcard.

listkeys ($pattern)

Returns an array ref with all additional key names that are used for metrics. Optionally allows to restrict the search by a SQL LIKE search pattern, allowing % as wildcard.

stats

Returns a hash with info about the storage, like how many data points, how many metrics, how many additional keys, are stored.

gc()

Run garbage collector. This cleans up potential garbage that might have piled up, in particular qeued raw results that are already processed but still in the storage.

Initially the garbage collection is made for the queing functionality (see "process_raw_result_queue" until we are confident it is waterproof. However, generally there might be new code arriving in the future for which garbage collection might also make sense, so we provide this function as general entry point to do The Right Thing - whatever that is by that time.

process_raw_result_queue($count)

Works on the queued entries created by add in queuemode=1. It finishes as soon as there are no more unprocessed raw entries, or it processed $count entries (default=10).

init_search_engine($force)

Initializes the configured search engine (Elasticsearch). If the index already exists it does nothing, except when you set $force to a true value which deletes and re-creates the index. This is necessary for example to apply new type mappings.

After a successful (re-)init you need to run sync_search_engine.

During (re-init) and sync you should disable querying by setting

  benchmarkanything.searchengine.elasticsearch.enable_query: 0

Options

force

If set, an existing index is deleted before (re-)creating.

sync_search_engine($force, $start, $count)

Synchronizes entries from the ::SQL backend into the configured search engine (usually Elasticsearch). It starts at entry $start and bulk indexes in blocks of $count.

Options

force

If set, all entries are (re-)indexed, not just the new ones.

getpoint ($value_id)

Returns a single benchmark point with all its key/value pairs.

AUTHOR

Steffen Schwigon <ss5@renormalist.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Steffen Schwigon.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.