SYNOPSIS

obnam-benchmark [--config=FILE] [--description=DESCRIPTION] [--drop-caches] [--dump-config] [--dump-memory-profile=METHOD] [--dump-setting-names] [--file-size=SIZE] [--generate-manpage=TEMPLATE] [--generations=N] [-h] [--help] [--larch-branch=DIR] [--list-config-files] [--log=FILE] [--log-keep=N] [--log-level=LEVEL] [--log-max=SIZE] [--log-mode=MODE] [--no-default-configs] [--obnam-branch=DIR] [--output=FILE] [--profile-name=PROFILE-NAME] [--results=DIR] [--seivot-branch=DIR] [--seivot-log=SEIVOT-LOG] [--sftp-delay=SFTP-DELAY] [--size=PAIR] [--use-sftp-repository] [--use-sftp-root] [--verify] [--version] [--with-encryption] [FILE]...

DESCRIPTION

obnam-benchmark benchmarks the obnam(1) backup application, by measuring how much time it takes to do a backup, restore, etc, in various scenarios. obnam-benchmark uses the seivot(1) tool for actually running the benchmarks, but makes some helpful assumptions about things, to make it simpler to run than running seivot directly.

Benchmarks are run using two different usage profiles: mailspool (all files are small), and mediaserver (all files are big). For each profile, test data of the desired total size is generated, backed up, and then several incremental generations are backed up, each adding some more generated test data. Then other operations are run against the backup repository: restoring, listing the contents of, and removing each generation.

The result of the benchmark is a .seivot file per profile, plus a Python profiler file for each run of obnam. These are stored in ../benchmarks. A set of .seivot files can be summarized for comparison with seivots-summary(1). The profiling files can be viewed with the usual Python tools: see the pstats module.

The benchmarks are run against a version of obnam checked out from version control. It is not (currently) possible to run the benchmark against an installed version of obnam. Also the larch Python library, which obnam needs, needs to be checked out from version control. The --obnam-branch and --larch-branch options set the locations, if the defaults are not correct.

OPTIONS

--config=FILE

add FILE to config files

--description=DESCRIPTION

describe benchmark

--drop-caches

drop kernel buffer caches

--dump-config

write out the entire current configuration

--dump-memory-profile=METHOD

make memory profiling dumps using METHOD, which is one of: none, simple, meliae, or heapy (default: simple)

--dump-setting-names

write out all names of settings and quit

--file-size=SIZE

how big should files be?

--generate-manpage=TEMPLATE

fill in manual page TEMPLATE

--generations=N

benchmark N generations (default: 5)

-h, --help

show this help message and exit

--larch-branch=DIR

use DIR as the larch branch (default: /sbuild-nonexistent/larch/trunk)

--list-config-files

list all possible config files

--log=FILE

write log entries to FILE (default is to not write log files at all); use "syslog" to log to system log, or "none" to disable logging

--log-keep=N

keep last N logs (10)

--log-level=LEVEL

log at LEVEL, one of debug, info, warning, error, critical, fatal (default: debug)

--log-max=SIZE

rotate logs larger than SIZE, zero for never (default: 0)

--log-mode=MODE

set permissions of new log files to MODE (octal; default 0600)

--no-default-configs

clear list of configuration files to read

--obnam-branch=DIR

use DIR as the obnam branch to benchmark (default: .)

--output=FILE

write output to FILE, instead of standard output

--profile-name=PROFILE-NAME

short name for benchmark scenario

--results=DIR

put results under DIR (../benchmarks)

--seivot-branch=DIR

use DIR as the seivot branch (default: installed seivot)

--seivot-log=SEIVOT-LOG

seivot log setting

--sftp-delay=SFTP-DELAY

add artifical delay to sftp transfers (in milliseconds)

--size=PAIR

add PAIR to list of sizes to benchmark (e.g., 10g/1m)

--use-sftp-repository

access the repository over SFTP (requires ssh to localhost to work)

--use-sftp-root

access the live data over SFTP (requires ssh to localhost to work)

--verify

verify restores

--version

show program's version number and exit

--with-encryption

run benchmark using encryption

FILES

../benchmarks/

The default directory where results of the benchmark are stored, in a subdirectory named after the branch and revision numbers.

EXAMPLE

To run a small benchmark:

TMPDIR=/var/tmp obnam-benchmark --size=10m/1m

To run a benchmark using existing data:

TMPDIR=/var/tmp obnam-benchmark --use-existing=$HOME/Mail

To view the currently available benchmark results:

seivots-summary ../benchmarks/*/*mail*.seivot | less -S
seivots-summary ../benchmarks/*/*media*.seivot | less -S

(You need to run seivots-summary once per usage profile.)