OBNAM-BENCHMARK(1)					      General Commands Manual						OBNAM-BENCHMARK(1)

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]    [--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 pro-
       file, 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  log-
	      ging

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

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

SEE ALSO

       obnam(1), seivot(1), seivots-summary(1).

																OBNAM-BENCHMARK(1)