BenchDB

Workflow guide

From benchmark output to a tracked result.

BenchDB does not replace your benchmark harness. It gives the results a consistent identity, durable history, and a path into human investigation and CI. Follow one result through the system.

Start the guide Open quickstart
  1. 01

    Your harness stays in charge

    Measure the behavior you care about.

    Use Go benchmarks, pytest-benchmark, Google Benchmark, a shell script, or a purpose-built performance harness. Run on a developer machine, in CI, or across a controlled fleet. BenchDB begins after the measurement exists.

    Keep execution separate from publication. Save result files so a failed upload can retry without running an expensive benchmark again.
    Understand BenchDB concepts →
  2. 02

    Identity makes history possible

    Describe the result, not just the number.

    A useful result names the benchmark case and unit, then records the run, repository commit, machine, and timestamp. Stable tags let BenchDB group comparable measurements while machine context keeps fleet differences visible. 

    {
  "tags": {"name": "decode-batch", "rows": "1m"},
  "run_id": "ci-1842-1",
  "github": {
    "repository": "https://github.com/example/project",
    "commit": "8f3c29a"
  },
  "machine_info": {"name": "linux-arm64"},
  "stats": {"unit": "ms", "data": [82.1, 81.7, 82.4]}
}
    Read the result contract →
  3. 03

    CLI-first writes

    Publish files with a reporter token.

    BenchDB accepts one result object or an array per JSON file. The CLI resolves credentials, validates inputs, expands quoted globs, and submits larger suites with bounded concurrency. 

    export BENCHDB_SERVER_URL=https://benchdb.example.com
export BENCHDB_TOKEN=<reporter-token>

benchdb results submit "bench-results/*.json" \
  --server "$BENCHDB_SERVER_URL"
    Keep secrets out of arguments and payloads. Use BENCHDB_TOKEN in automation and preserve the JSON Lines submission receipt.
    Submit your first result →
  4. 04

    History with context

    Start at the signal, then follow the evidence.

    Browse recent runs to confirm a complete attempt arrived. Open an individual result for raw values and metadata. Move to its series to see calendar-time trends across machines, then compare specific points when a change needs closer inspection.

    Run→Result→Series→Compare
    Learn the investigation workflow →
  5. 05

    Performance in CI

    Turn the same results into a CI decision.

    After submission, benchdb ci report finds contender results for the repository and commit, selects or accepts a baseline, and reports stable, improved, regressed, insufficient, errored, or incomparable rows. Lookback analysis uses recent history so one noisy pair does not decide the entire build. 

    benchdb ci report \
  --server "$BENCHDB_SERVER_URL" \
  --repository "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" \
  --commit "$GITHUB_SHA" \
  --format markdown \
  --output benchdb-report.md
    Choose selectors and baselines →
  6. 06

    A small, explicit runtime

    Operate the server and database as load-bearing services.

    The BenchDB binary serves the Go API and embedded web application; PostgreSQL stores results and operational state. Run migrations as a separate deployment step, mint scoped reporter tokens, monitor the ping and metrics endpoints, and schedule alert evaluation independently from delivery.

    DeployOne application image plus PostgreSQL
    MigrateExplicit benchdb migrate step
    ObserveHealth and Prometheus metrics
    AutomateReporter tokens and scheduled alerts
    Read the operator reference →

Ready to publish a result?

Continue with the quickstart.

It covers the shortest working path from CLI setup to a result in the dashboard.

Open quickstart