--- name: "obnam-benchmark" section: "1" platform: "linux" package: "obnam" version: "1.1-1.1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/obnam-benchmark" --- # obnam-benchmark(1) benchmark obnam ## 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)](/obnam/1.md) backup application, by measuring how much time it takes to do a backup, restore, etc, in various scenarios. **obnam-benchmark** uses the [**seivot**(1)](/seivot/1.md) 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)](/seivots-summary/1.md). 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 ## 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.) ## SEE ALSO [**obnam**(1)](/obnam/1.md), [**seivot**(1)](/seivot/1.md), [**seivots-summary**(1)](/seivots-summary/1.md).