Vizb: Visualize Go Benchmarks in 4D

Vizb is a CLI tool that transforms Go benchmark raw output into interactive 4D visualizations. It allows you to merge multiple benchmark data, apply advanced grouping logic, and explore performance across four dimensions: Source, Group, and two customizable axes (X and Y). All within a single and deployable HTML file.

Features

• Modern Interactive UI: Robust Vue.js application with a smooth and responsive experience.
• Multi-Chart: Supports multiple charts (bar, line and pie) in a single place.
• Sorting: Sort data (asc/desc) for comparison through UI settings or CLI flags.
• Swap Axis: Swap the n, x and y axes for diverse comparison through UI settings.
• Logarithmic Scale: Use --scale log for bar and line charts to better visualize benchmarks with high variance in values.
• Multi-Dimensional Grouping: Merge multiple benchmark data for deep comparative analysis.
• Tag-Based Merging: Tag benchmarks with commit hashes or version labels to compare performance across releases with automatic data merging.
• Flexible Input: Automatically processes raw go test -bench output and the standard JSON output of go test -bench -json.
• Comprehensive Metrics: Compare time, memory, and numbers with customizable units.
• Smart Grouping: Extract grouping logic from benchmark names using regex and group patterns.
• Filtering: Filter benchmarks to include only those matching a regex pattern.
• Export Options: Generate single-file HTML/JSON and options to save charts as JPEG.

GitHub Action

Vizb provides a composite GitHub Action to run benchmarks and generate visualizations in CI.

Basic Usage

- uses: actions/setup-go@v6
  with:
    go-version-file: go.mod

- uses: goptics/vizb@v0
  with:
    bench-cmd: "go test -bench=."
    output-html: pages/index.html

Tracking Performance Across Releases

Tag benchmarks with release versions, merge historical data, and deploy charts:

on:
  push:
    tags: ['v*']

jobs:
  bench:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod

      - name: Download previous benchmark data
        uses: dawidd6/action-download-artifact@v21
        continue-on-error: true
        with:
          workflow: bench.yml
          name: merged.json
          path: prev

      - uses: goptics/vizb@v0
        with:
          bench-cmd: "go test -bench=."
          tag: ${{ github.ref_name }}
          merge-dir: prev
          tag-axis: x
          output-json: merged.json
          output-html: pages/index.html

      - uses: actions/upload-artifact@v4
        with:
          name: merged.json
          path: merged.json

      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: pages

Note

The tag-axis input controls which data dimension receives the tag annotation. Use x to show versions on the X-axis for clean progressive comparison.

Installation

Go Toolchain

go install github.com/goptics/vizb@latest

Download Binary

Pre-built binaries for Linux, macOS, and Windows are available on the releases page.

Basic Usage

Using raw benchmark output

Run your Go benchmarks and save the output:

go test -bench . > bench.txt

Generate charts from the benchmark:

vizb bench.txt -o output.html

Using logarithmic scale

For benchmarks with high variance in values (e.g., 1 to 1,000,000), use the logarithmic Y-axis scale:

vizb bench.txt -o output.html --scale log

The --scale flag accepts linear (default) or log. It works with bar and line charts; pie charts and 1D data automatically use linear scale.

Direct piping

Pipe benchmark results directly to vizb:

# Raw output
go test -bench . | vizb -o output.html

# JSON output (automatically detected and converted)
go test -bench . -json | vizb -o output.html

Using vizb standard JSON benchmark output

vizb bench.txt -o output.json

Generate charts from the standard JSON benchmark data:

vizb output.json -o output.html

Merging multiple benchmarks

You can combine multiple benchmark JSON files using the merge command. This is useful for aggregating benchmark data from different runs, machines, or environments. The merge command always outputs JSON — use vizb html to render the result as an interactive HTML chart.

# Merge specific files into JSON
vizb merge output.json output2.json -o merged.json

# Generate HTML from merged JSON
vizb html merged.json -o merged_report.html

# Merge all JSON files in a directory
vizb merge ./results/ -o all.json

# Mix and match files and directories
vizb merge ./old_results/ output.json -o comparison.json

Open the generated HTML file in your browser to view the interactive charts.

Note

The merge command requires JSON files as input, which must be generated using vizb bench.txt -o output.json.

Tag-Based Merging

Vizb supports tagging benchmarks to compare performance across multiple commits, releases, or environment variants. The --tag flag on the main command assigns a label (e.g., commit hash, version number) to a benchmark run. When merging, vizb groups benchmarks by name and deep-merges those sharing the same name but different tags into a single object, preserving all timestamps, history, and data.

Tagging a benchmark run

vizb bench-v1.txt -o v1.json --tag v1 -n "Foo"

vizb bench-v2.txt -o v2.json --tag v2 -n "Foo"

How tag-based merging works

When you merge benchmarks sharing the same name with different tags:

vizb merge v1.json v2.json -o comparison.json
vizb html comparison.json -o comparison.html

Vizb groups benchmarks by name and processes each group as follows:

1. Deduplication: If two entries share the same name and tag, only the one with the latest timestamp is kept. Older entries are discarded.
2. Inner merge: Entries with different tags are deep-merged into a single benchmark. Data points are sorted in chronological tag order and each is annotated with its originating tag.
3. Legacy entries: Untagged benchmarks (no --tag) with the same name are deduplicated (first-seen wins) and their data is prepended before tagged entries.
4. Output: The merged benchmark retains the latest tag (by timestamp), carries a history of older tags, and includes data from all runs.

Controlling where the tag is injected

By default, the tag is injected into the name dimension of each inner data object. Use --tag-axis (shorthand -A) to target xAxis or yAxis instead:

# Inject tag into xAxis so the X-axis labels show version differences
vizb merge v1.json v2.json -A x -o comparison.json
vizb html comparison.json -o comparison.html

Accepted values: n (name), x (xAxis), y (yAxis). Default is n.

Advance Usage

How vizb groups your benchmark data

Vizb creates charts that make sense by putting your benchmark data into logical groupings and axes. It sees the data as 1D (xAxis) by default, but if you have to deal with 2D or 3D data, you can use the --group-pattern and --group-regex flags to group your data.

Understanding Group Patterns

A group pattern tells vizb how to dissect your benchmark names into three key components:

1. Name (n): The family or group the benchmark belongs to. Benchmarks with the same Name will be grouped together in the same chart. (optional)
2. XAxis (x): The category that goes on the X-axis (e.g., input size, concurrency level).
3. YAxis (y): The specific test case or variation (e.g., algorithm name, sub-test).

Visualizing the Extraction

Imagine you have a benchmark named BenchmarkSort/100/Ints, which has 3D data.

If you use the pattern name/xAxis/yAxis (or n/x/y), vizb splits the name wherever it finds a /:

Benchmark Name:  BenchmarkSort  /  100  /  Ints
                     │              │        │
Pattern:           [Name]        [XAxis]   [YAxis]
                     │              │        │
Result:            "Sort"         "100"    "Ints"

Group Pattern Syntax (--group-pattern)

• Components: Use name, xAxis, yAxis (or shorthands n, x, y).
• Separators: Use / (slash) or _ (underscore) to match the separators in your benchmark names.
• Skipping parts: You can leave parts empty in the pattern to ignore sections of the benchmark name.

Standard Go Benchmarks (Slash Separated)

Format: Benchmark<Group>/<InputSize>/<Variant>

Pattern: n/x/y

Benchmark Name	Extracted Data
BenchmarkSort/1024/QuickSort	Name: Sort XAxis: 1024 YAxis: QuickSort
BenchmarkSort/1024/MergeSort	Name: Sort XAxis: 1024 YAxis: MergeSort

Underscore Separated

Format: Benchmark<Group>_<Variant>_<InputSize>

Pattern: n_y_x

Benchmark Name	Extracted Data
BenchmarkHash_SHA256_1KB	Name: Hash YAxis: SHA256 XAxis: 1KB
BenchmarkHash_MD5_1KB	Name: Hash YAxis: MD5 XAxis: 1KB

Simple Grouping (No X-Axis)

Format: Benchmark<Group>/<Variant>

Pattern: n/y

Benchmark Name	Extracted Data
BenchmarkJSON/Marshal	Name: JSON XAxis: (empty) YAxis: Marshal
BenchmarkJSON/Unmarshal	Name: JSON XAxis: (empty) YAxis: Unmarshal

Ignoring Prefixes

Sometimes you might want to ignore a common prefix or a specific part of the name.

Pattern: /n/y (Starts with a separator to skip the first part)

Benchmark Name	Extracted Data
BenchmarkTest/JSON/Marshal	Name: JSON YAxis: Marshal (First part "Test" is ignored)

Group Regex Syntax (--group-regex)

For more complex benchmark names where simple patterns aren't enough, you can use Regular Expressions with named groups.

• Named Groups: Use (?<name>...), (?<xAxis>...), (?<yAxis>...) (or shorthands (?<n>...), (?<x>...), (?<y>...)) to capture parts of the benchmark name.
• Flexibility: Regex allows you to match specific characters, ignore parts, and handle irregular formats.

Examples

Benchmark Name	Regex	Extracted Data	Dimensions
BenchmarkHashing64MD5	Hashing64(?<x>.*)	XAxis: MD5	1D
BenchmarkJSONByMarshal	(?<x>.*)By(?<y>.*)	XAxis: JSON YAxis: Marshal	2D
BenchmarkDecode/text=digits/level=speed	(?<n>.*)/text=(?<x>.*)/level=(?<y>.*)	Name: Decode XAxis: digits YAxis: speed	3D

Note

You must specify at least one of the x and y axes when you use the --group-[pattern|regex] command. the n is optional.

Development

This project uses Task for managing development workflows.

Setup Development Environment

# Install Task runner
go install github.com/go-task/task/v3/cmd/task@latest

Available Tasks

# install dependencies
task init

# Run the UI in development mode
task dev:ui

# Build The UI
task build:ui

# Build the binary (run from ./bin/vizb)
task build:cli

# Build everything
task build

# Run tests
task test

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.