A quick tour of the codebase

This page is a short tour of the magic-trace codebase. Its target audience is someone who wants to contribute to magic-trace, but has never looked at the code before.

magic-trace invokes perf in intel_pt mode and turns its output into Fuchsia traces that can be read by Perfetto. In some sense, it's a glorified text filter that leaves the heavy lifting to perf. There's some complexity in turning perf's linear history of control flow into usable stack traces, but that's about it.

Anyhow, before you start poking around the code you definitely want to make sure you have your editor set up. It should, at the very least, support "show me the type of the thing under my cursor". Reading OCaml code without that is very hard; many types are inferred automatically by the compiler instead of explicitly annotated.

The entry point to magic-trace is in src/trace.ml.

The code that shells out to perf and interprets perf output is in src/perf_tool_backend.ml. The reason why it's called a "backend" is because we hope to one day integrate with perf directly instead of shelling out to it. There is the start of that work available in direct_backend/, but it's incomplete and we don't even build that folder by default. So for now, we have exactly one backend, and it's the "perf_tool_backend".

The code that turns the parsed perf output into a trace is in src/trace_writer.ml. It also happens to be where the logic that turns control flow into call stacks lives.

core/event.ml contains the type definition of a parsed perf event. It's the data that's fed from the perf_tool_backend to the trace_writer.

demo/ contains small self-contained example programs that you can test magic-trace with. Some of those examples don't generate reasonable traces yet, they're aspirational. ./demo/demo.c should always look good.

lib/ contains lib/magic_trace which is an ocaml library that OCaml applications can use for "start" and "stop" trace markers.