time-trace: C++ compile-time profiling with Clang and Linux perf

time-trace converts Clang -ftime-trace JSON into a synthetic perf.data profile. Use familiar perf report and perf script workflows to find slow template instantiations, compiler phases, and compile-time call paths.

Requirements

• Linux on x86_64 or ARM64 (aarch64/arm64)
• Python 3.12 or newer
• clang or clang++, plus nm, on PATH
• perf for inspecting the generated profile

Install

Until the first PyPI release, install directly from GitHub:

uv tool install git+https://github.com/romanpauk/time-trace.git
time-trace --help

For local development, see the development guide.

Quick start

Profile one Clang compile and keep only template-related events:

time-trace --output time-trace-out/example --include "tag:template" -- \
  clang++ -std=c++20 -c example.cpp -o example.o

perf report --stdio --percent-limit 0 --call-graph caller \
  -i time-trace-out/example/perf.data --sort symbol

The command adds -ftime-trace, runs Clang, reconstructs the compiler call tree, and writes perf.data plus synthetic-image.so.

A caller view from the repository's sample programs looks like this:

clang++ compilation
`--template
   `--VariantDispatcher<std::variant<...>>::run
      `--std::visit<Overloaded<...>, const std::variant<...>&>

Already have a Clang trace?

time-trace --trace-file compile.json --compiler clang++

What the percentages mean

The profile contains samples reconstructed from Clang trace intervals. Perf percentages therefore represent relative Clang trace duration, not runtime CPU cycles or samples captured by perf record. Use them to locate expensive compile-time paths and compare similar builds.

Keep synthetic-image.so beside perf.data; perf needs it to resolve the generated symbols.

Focus the profile

Filters accept glob patterns and can target raw event names, labels, categories, or derived tags:

time-trace --include "tag:template" -- clang++ -c example.cpp -o example.o
time-trace --include "name:Instantiate*" --exclude "tag:codegen" -- \
  clang++ -c example.cpp -o example.o
time-trace --trace-file compile.json --list-event-names
time-trace --trace-file compile.json --list-tags

Documentation

• Usage and perf recipes
• Architecture and profile format
• Development setup and checks

Found a bug or missing workflow? Open an issue.