Ubuntu Manpage: obnam-benchmark

NAME

       obnam-benchmark - benchmark obnam

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]  [--help-all]  [--larch-branch=DIR]  [--list-config-files] [--log=FILE]
       [--log-keep=N] [--log-level=LEVEL]  [--log-max=SIZE]  [--log-mode=MODE]  [--memory-dump-interval=SECONDS]
       [--no-default-configs]  [--no-drop-caches]  [--no-use-sftp-repository] [--no-use-sftp-root] [--no-verify]
       [--no-with-encryption] [--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 oth‐
er 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 mod‐
ule.

The benchmarks are run against a version of obnam checked out from version control. It is not (current‐
ly) 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

       --description=DESCRIPTION
              describe benchmark

       --drop-caches
              drop kernel buffer caches

       --file-size=SIZE
              how big should files be?

       --generate-manpage=TEMPLATE
              SUPPRESSHELP

       --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: )

       --no-drop-caches

       --no-use-sftp-repository

       --no-use-sftp-root

       --no-verify

       --no-with-encryption

       --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

   Configuration files and settings
       --config=FILE
              add FILE to config files

       --dump-config
              write out the entire current configuration

       --dump-setting-names
              SUPPRESSHELP

       --help-all
              show all options

       --list-config-files
              SUPPRESSHELP

       --no-default-configs
              clear list of configuration files to read

   Logging
       --log=FILE
              write log entries to FILE (default is to not write log files at all); use "syslog" to log to  sys‐
              tem 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)

   Peformance
       --dump-memory-profile=METHOD
              make  memory  profiling  dumps  using METHOD, which is one of: none, simple, meliae, or heapy (de‐
              fault: simple)

       --memory-dump-interval=SECONDS
              make memory profiling dumps at least SECONDS apart

ENVIRONMENT

       TMPDIR This variable must be set.  It controls where the temporary files (generated test data) is stored.
              If this variable was not set, they'd be put into /tmp, which easily fills up, to the detriment  of
              the entire system.  Thus.  obnam-benchmark requires that the location is set explicitly.  (You can
              still use /tmp if you want, but you have to set TMPDIR explicitly.)

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.)