Merging

What is Merging

Merging combines multiple JSON benchmark files into a single dataset for visualization. This enables comparing benchmarks across different runs, machines, versions, or releases — all in one interactive chart.

Without merging, each benchmark run is an isolated report. With merging, you can overlay results from v1.0 and v2.0, compare performance across different machines, or track regressions over time.

How Merging Works

The general pipeline has three steps:

1. Convert each benchmark run to JSON:

   vizb bench.txt -o data.json

2. Merge the JSON files:

   vizb merge file1.json file2.json -o merged.json

3. Generate the HTML report:

   vizb html merged.json -o report.html

Outer Merging (Untagged)

Outer merging is a simple concatenation of benchmark data. When JSON files contain benchmarks with the same name and no tags, duplicates are resolved by keeping the first-seen entry. Use outer merging when combining different benchmark suites or independent runs.

vizb merge cpu.json memory.json -o combined.json

Directory Scanning

You can pass a directory to merge all JSON files it contains:

vizb merge ./results/ -o all.json

This recursively finds and merges all .json files in the ./results/ directory.

Inner Merging (Tagged)

Inner merging is for comparing the same benchmarks across different conditions. When benchmarks share the same name but carry different tags, they deep-merge into a single entry — producing a chart with multiple series, one per tag.

1. Tag individual runs

   Use --tag to label each run with a version, machine name, or any identifier:

   vizb bench-v1.txt -o v1.json --tag v1 -n "MyBenchmark"
   vizb bench-v2.txt -o v2.json --tag v2 -n "MyBenchmark"

2. Merge tagged files

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

3. Generate the HTML report

   vizb html comparison.json -o comparison.html

How Tagged Merge Works

The merge process handles tagged data as follows:

• Deduplication: If the same benchmark name appears with the same tag, only the entry with the latest timestamp is kept.
• Deep merge: Benchmarks with the same name but different tags are combined into a single benchmark entry. The data points from each tag are sorted chronologically, creating a multi-series chart.
• Legacy entries: Untagged benchmarks (those without a tag) are prepended before any tagged data, so they appear as the baseline in the chart.

Tag-Axis

The -A (or --tag-axis) flag controls where the tag label is injected in the grouped dimensions. By default, tags are added to the name/n dimension, which creates separate charts per tag. Changing the axis lets you control how the comparison is visualized.

Value	Axis	Effect
n	Name (default)	Creates separate chart groups per tag
x	XAxis	Places tag values on the X-axis for direct comparison
y	YAxis	Places tag values on the Y-axis as separate series

vizb merge v1.json v2.json -A x -o comparison.json

Tip

Use -A x (tag on X-axis) when comparing versions. This places version labels along the X-axis, making it easy to see performance changes side by side within the same chart.

Caution

Merge requires JSON files as input — it does not accept raw go test -bench text output. Convert text to JSON first using vizb bench.txt -o data.json.