# Konata draws an out-of-order CPU pipeline from a trace file in your browser

> Konata is a browser based visualizer for Onikiri2-Kanata and gem5 O3PipeView instruction traces, showing a pipeline diagram with dependency arrows, bookmarks, search and a two-trace comparison mode, and since v1.0.0 it runs entirely in the browser with local traces never leaving the machine. It suits performance engineers reading an out-of-order core, and it depends on the trace format rather than the CPU model.

**shioyadan/Konata** — Browser-based instruction pipeline visualizer for Onikiri2-Kanata and gem5 O3PipeView traces. Run it online or download a self-contained HTML release.

- Repository: https://github.com/shioyadan/Konata
- Website: https://shioyadan.github.io/Konata/
- Stars: 586 · Forks: 51
- Language: TypeScript
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/shioyadan-konata

## The pipeline diagram is the point, not a chart of your trace

Konata is a visualizer for instruction pipeline traces in the Onikiri2-Kanata and gem5 O3PipeView formats, and what it draws is the pipeline structure of an out-of-order core: the stages, the instructions in flight, and the dependencies between them. The result is that you can see why a cycle happened, which is a question a log file answers badly. The toolbar shows how the tool is meant to be used day to day. The Open control chooses one or more traces or accepts a drag and drop. Search works on a regular expression over the current trace, with F3 and Shift+F3 moving to the next and previous matches. Bookmark slots are number keys 0 to 9, and Ctrl or Command with those numbers saves the current position and zoom into that slot, which is a detail that tells you the tool was built by someone who reads a lot of traces. The Stats control opens a resizable dialog with statistics for the current trace, and the View control covers theme, pipeline colors, dependency arrows, lane layout, flushed-op visibility and minimum lane heights.

## Since v1.0.0 it is a browser app, and local traces stay local

The architectural change is the most consequential fact in the project. Since v1.0.0, Konata runs in the browser instead of as an Electron desktop application, local traces remain in the browser and are never uploaded, and the tool makes no background network requests unless remote loading is explicitly requested. The repository still lists electron in the dev dependencies, and the Makefile comments explain why, stating that Electron is not used in the product but only as a test runner to verify the production HTML in Chromium, so the dependency that remains is a testing tool rather than a runtime. The practical consequences are large. The hosted version needs no installation at all, you simply open Konata Web in a browser. A trace several gigabytes in size can be loaded, which is a different proposition from a desktop app that has to allocate the same memory. And the security posture is better than the old model, because a local trace is not a file that gets uploaded when you open it.

## The launcher serves a local port and prints an SSH tunnel command

For a remote server or WSL, the distribution includes a launcher that starts a local web server on an available port and runs until you press Ctrl+C, and the quick start is a download, an unzip and a launch. The build produces a konata-latest.zip, you extract it, change into the directory and run konata.sh with the trace path, and you can pass up to 10 trace paths to open them in separate tabs. The launcher prints what you need to reach it from another machine.

```text
    Konata URL: http://127.0.0.1:30080/#name=trace1.log.zst
    SSH tunnel: ssh -L 30080:127.0.0.1:30080 <host>
    Press Ctrl+C to stop the server.
```

The printed SSH tunnel line is the practical part, because the server binds to the loopback address and the tunnel is how you get to it from your laptop. A trace that lives on a build machine is a common situation, and this is the path that handles it without setting up a shared web server.

## The gem5 debug flags decide what the trace can show

To produce a trace Konata can draw, the gem5 side needs the right debug flags, and the README is specific about which is which. The example runs gem5 v25.1 with the O3 CPU model, using the bundled legacy SE script to run an arbitrary binary, and the debug flag list is O3PipeView, Rename, MemDepUnit and LSQUnit. Rename adds register dependencies and information used to recover SMT thread IDs, MemDepUnit adds memory-completion events, and LSQUnit adds load and store addresses. The consequence is that a trace produced without those flags is missing the arrows.

```bash
./build/ALL/gem5.opt \
    --debug-flags=O3PipeView,Rename,MemDepUnit,LSQUnit \
    --debug-file=trace.log \
    configs/deprecated/example/se.py \
    --cpu-type=ArmO3CPU --caches --mem-size=512MiB \
    --cmd=<path-to-binary> --options="<program arguments>" \
    --maxinsts=<instruction-limit>
```

There is a trade-off, since the documentation says to use only O3PipeView for a smaller trace, or O3PipeView and O3CPUAll for full troubleshooting. You open m5out/trace.log through the Open menu or by dragging it onto Konata, and for a large trace you compress it with Zstandard, where Konata opens .zst files directly.

## The command palette is the fast path through a long trace

A pipeline trace can be tens of thousands of instructions wide, so the shortcuts matter more than the mouse. F1 or Ctrl/Command+Shift+P opens the command palette, and the four commands it accepts are the ones you will use.

```text
j  <op ID>    Jump to an operation ID
jr <RID>      Jump to a retired operation ID
f  <pattern>  Find a regular expression
l             Open the file picker
```

The jump to a retired operation ID is the interesting one, because in a renamed trace the identifier you have from a log or a bug report is often the retired name rather than the current one, and being able to go straight to it avoids reading a rename table by hand. The canvas itself supports panning by dragging, horizontal scrolling with a trackpad gesture, vertical movement with the mouse wheel or the Up and Down keys, zoom with Ctrl or Command and the wheel or the plus and minus keys, double-click to zoom in and shift double-click to zoom out, and pinch with two pointers. Clicking an instruction label aligns its fetch cycle with the left edge, and Ctrl or Command clicking the pipeline pins matching vertical and horizontal guides, which then appear in the instruction labels and both navigators. Command palette history, bookmarks and view settings are saved between browser sessions.

## Comparing two traces uses A, B and overlay, with a shared anchor

The comparison feature is the reason to run Konata in a browser rather than drawing screenshots. You open two traces, select the tab to use as A, and choose Compare. Use A or B to inspect one trace with the other as a faint reference, and use Overlay to highlight differences. Dragging in A or B mode moves only that trace, while overlay mode moves both traces together. The alignment mechanism is worth understanding, because it is the difference between a useful comparison and a misleading one. Align to A aligns the two traces using a shared retired-operation ID when available, which is a stable identifier that survives renames, and if a trace has no shared retired operation ID the alignment has to fall back to something weaker. The guide-pinning feature described earlier is the manual counterpart, and the pipeline tooltip shows signed offsets from the pinned reference as Cycle and Op, where the op offset counts visible instructions. Guides are temporary and are cleared when you switch tabs.

## Browser limitations are documented rather than discovered

The limitations section is short and specific, which is preferable to finding out later. Recent files, reload and external change detection require the File System Access APIs, which are supported by compatible Chromium based browsers, and other browsers still support file selection and drag and drop. Remote traces opened with konata.sh can be reloaded manually, but automatic external change detection is not available for them. And loading arbitrary URLs or paths is intentionally disabled, which is a deliberate security decision rather than a missing feature, and it also means the tool cannot be pointed at a trace on a random web server. That last one has a cost, because the old Electron version could open a file from anywhere on the filesystem, and the browser version cannot. The Makefile shows how seriously the project takes verification, with a check target that runs typecheck, the test suite, a launcher check and a production regression, plus separate browser and web regression targets and a benchmark rendering target.

## The command line mode is a prototype and says so

Downloaded distributions include konata-cli.js, and with Node.js 18 or later installed you can run the same binary in a line-oriented mode.

```bash
./konata.sh --cli trace.log.zst
```

The documentation is careful to say what this is and is not. It is a line-oriented CLI, not a full-screen TUI, and the commands are of the form show, overview, find stage ID min 3, detail id 413 and quit, with help listing all commands. It keeps the trace and the inspection state between commands, supports one Kanata or gem5 O3PipeView trace at a time in plain text, gzip or Zstandard, and keeps the whole trace in memory. Loading is asynchronous by default, so show and searches work against the instructions available while the file is still loading, and status, wait and cancel manage that, with open --sync "path" to wait instead. Commands can also come through standard input, and a --jsonl flag returns one JSON response per command without prompts, which is the part that makes it scriptable rather than interactive. Interactive terminals get Tab completion and session history.

## Conclusion

Performance engineers who already produce Kanata or gem5 O3PipeView traces and want to read the pipeline structure rather than grep the log are the people Konata is for, and the fact that it runs in the browser, loads multi-gigabyte files and never uploads a local trace makes it usable on a trace that would be painful to move. It is the wrong tool for anyone who does not have a trace in one of those two formats, since it is a trace viewer and not a simulator, and it is the wrong tool for a browser that is not Chromium based if you rely on the recent files and reload features. Check three things before you rely on it: that your trace producer emits the fields the pipeline needs, since the gem5 example shows the debug flags Rename, MemDepUnit and LSQUnit being required for register dependencies, memory completion events and load and store addresses, that your files are compressed with Zstandard for the large ones, since Konata opens .zst files directly, and that the browser you use supports the File System Access APIs if you want reload and external change detection. The licence is BSD-3-Clause, the newest release is v1.2.0 from 2026-09-26, and the last push was on 2026-10-20.

## FAQ

### What does Konata do with my trace file?

Since v1.0.0 it runs in the browser rather than as an Electron desktop app, and local traces remain in the browser and are never uploaded. It makes no background network requests unless remote loading is explicitly requested.

### How do I run Konata on a remote server?

Download the build archive, extract it and run konata.sh with the trace path, up to 10 traces to open in separate tabs. The launcher starts a local web server on an available port, prints the Konata URL and an SSH tunnel command such as ssh -L 30080:127.0.0.1:30080 <host>, and runs until you press Ctrl+C.

### Which gem5 debug flags does Konata need?

The example uses O3PipeView, Rename, MemDepUnit and LSQUnit. Rename adds register dependencies and information used to recover SMT thread IDs, MemDepUnit adds memory completion events, and LSQUnit adds load and store addresses. Use only O3PipeView for a smaller trace, or O3PipeView and O3CPUAll for full troubleshooting.

### How do I compare two traces in Konata?

Open two traces, select the tab to use as A, and choose Compare. Use A or B to inspect one trace with the other as a faint reference, and Overlay to highlight differences. Align to A aligns them using a shared retired-operation ID when available.

### What are the browser limitations of Konata?

Recent files, reload and external change detection need the File System Access APIs supported by compatible Chromium based browsers, though other browsers still support file selection and drag and drop. Remote traces opened with konata.sh can be reloaded manually, and loading arbitrary URLs or paths is intentionally disabled.

## Sources

- [License: BSD-3-Clause](https://github.com/shioyadan/Konata/blob/master/LICENSE)
- [Project website](https://shioyadan.github.io/Konata/)
- [README](https://github.com/shioyadan/Konata/blob/master/README.md)
- [Releases](https://github.com/shioyadan/Konata/releases)
- [shioyadan/Konata on GitHub](https://github.com/shioyadan/Konata)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shioyadan-konata