Benchmarks

hledger’s performance is measured in a few ways. Most of them use the synthetic sample journals in examples/, like examples/10ktxns-1kaccts.journal, generated by just samplejournals (see FILES).

quickbench

quickbench times the commands listed in a file (just bench uses bench/bench.sh by default) and shows a table of results, optionally running each command with several different executables, side by side. Install it as described in DEVWORKFLOWS, then:

$ just bench                    # time the commands in bench/bench.sh, with the hledger in PATH
$ just bench -f bench/bench10k.sh -w hledger-1.30,hledger-1.31,hledger-1.32 -n2 -N2   # compare versions, best of 2 runs, twice

The other bench*.sh files in the bench/ directory are alternative command sets, eg for many accounts, many transactions, or comparing with Ledger.

Throughput

hledger stats reports transactions per second. These recipes use it to show throughput at various data sizes:

$ just bench-throughput EXE      # with the given hledger executable
$ just bench-throughput-dev      # with the current dev build
$ just bench-throughput-recent   # with recent installed hledger versions

Performance test

just perftest runs hledger/test/_perf.test, which logs hledger stats throughput to perf.log (kept locally, for spotting changes over time), tagging each line with the machine’s CPU model, and fails if throughput is below a threshold.

Profiling

just hledgerprof builds a profiling-enabled bin/hledgerprof, then just quickprof CMD runs a hledger command on a sample journal and shows the profile (using profiterole). See just h prof for related recipes. With GHC 9.14, stack --profile fails (a compiler panic while building tls); instead build with stack-prof.yaml, which works around that and keeps its own .stack-prof work dir, as described in its header.

Package benchmark

hledger/bench/bench.hs is the hledger package’s benchmark suite: it calls the library directly, timing a journal read and the print, register and balance reports (quick timings by default, or criterion measurements with --criterion). It is currently disabled (buildable: false in hledger/package.yaml) to save build time, so stack bench hledger does nothing; to use it, enable it there.

Phase timings

Running any hledger command with --debug=1 (or higher) reports on stderr the run time and memory allocation of each phase: reading and parsing the data, each stage of journal finalising, and the command itself (see dbgTime in Hledger.Utils.Debug). Each stage’s result is fully evaluated to measure it (and the cost of that evaluation is excluded), so this describes a strict evaluation of the pipeline, but the totals closely match normal runs. One consequence: work that a normal run leaves unevaluated is charged too, eg inferred market prices, which only valuation uses, appear as a cost of every command. Allocation figures are deterministic, so they are a reliable guide even on a busy machine.