Skip to content

Quickstart

This guide gets you from an installed prof binary to one tagged collect and one compare between two tags in about 10 minutes, using either menus or flags.

Before you begin

  • Go 1.24.3 or newer (Install Prof lists full prerequisites).
  • Module root: your shell cwd is the directory that contains go.mod.
  • Benchmarks: you have at least one benchmark in *_test.go (replace BenchmarkExample below with a real name from your module).
  • Terminal: prof ui needs a normal TTY; for non-interactive shells, use the flag flow below.

What is a tag?

A tag is a short label for one profiling run. Prof writes all artifacts for that run under bench/<tag>/. You compare two tags (for example baseline and candidate) to see what changed between runs.

Path A: menus (default)

Step 1: start the UI

prof ui

Step 2: collect twice

In the menu, run Run benchmarks and collect profiles once with tag baseline, then change code (or stay on the same commit for a dry run), run again with tag candidate.

Step 3: compare

Choose Compare two tagged runs, pick baseline and candidate, your benchmark, and profile type cpu.

Verify: you should see compare output in the terminal and directories bench/baseline/ and bench/candidate/ with bin/ and text/ populated.

If the UI does not start, your environment may not expose a TTY. Use Path B or see Troubleshooting.

Path B: flags (CI or scripts)

Step 1: collect baseline

prof auto --benchmarks "BenchmarkExample" --profiles "cpu,memory,mutex,block" --count 10 --tag "baseline"

Step 2: collect after your change

prof auto --benchmarks "BenchmarkExample" --profiles "cpu,memory,mutex,block" --count 10 --tag "candidate"

Step 3: compare

prof track auto --base "baseline" --current "candidate" \
  --profile-type "cpu" --bench-name "BenchmarkExample" \
  --output-format "summary"

Verify:

  • On disk: bench/baseline/ and bench/candidate/ each contain bin/BenchmarkExample/ and text/BenchmarkExample/.
  • In the terminal: prof track auto prints a report; with --output-format summary the report is shorter than the default detailed format (Compare runs).

If something fails

See Troubleshooting (wrong cwd, missing tags, Graphviz, regression exit codes).

Next steps