ninjatracing README

The project's README from github.com/nico/ninjatracing. As one markdown file: README.md.

ninjatracing

Convert .ninja_log files to chrome's about:tracing format.

To view traces, either open about:tracing in chrome, or use https://www.speedscope.app/ or https://ui.perfetto.dev/.

Idea from Nick Carter, initial implementation from Richard Smith.

$ ./ninjatracing
Converts one (or several) .ninja_log files into chrome's about:tracing format

Usage:
    ninja -C $BUILDDIR
    ninjatracing $BUILDDIR/.ninja_log > trace.json

By default this will show build timing results for the most recent (possibly
incremental) build. To show build timing results for every target, whether
built in the last build or previously, use --showall. Note that this will
overlap multiple builds and will thus exaggerate build parallelism.

(When using --showall, ideally rm $BUILDDIR/.ninja_log and do a clean build.
If you don't have time for a clean build, at least run
`ninja -C $BUILDDIR -t recompact` first to remove no-longer-built targets.)

The results can be converted from .json format to .html format, for easier
loading into about:tracing, using trace2html from:
https://github.com/catapult-project/catapult/blob/master/tracing/bin/trace2html

ninjatracing (nico/ninjatracing)

Searching Database…

530 ·GitHub
Ninjatracing
What is this?ninjatracing converts .ninja_log build log files produced by the Ninja build system into Chrome's about:tracing JSON format, so you can visualize how long each build step took as a timeline.
Is this a GUI app or just a script I run from the terminal?It's a small single-file command-line script, not a library or GUI app — you point it at a Ninja build directory and it prints JSON to stdout.
How do I generate and view a trace?Build your project with Ninja, then run 'ninja -C $BUILDDIR; ninjatracing $BUILDDIR/.ninja_log > trace.json' and open the resulting JSON file in chrome's about:tracing (or convert it with trace2html).
Do I need anything besides Ninja to use this?You need a Ninja-based build so a .ninja_log file exists, plus Chrome's about:tracing viewer (or the trace2html tool) to actually look at the output.
What happens if I use the --showall flag?--showall shows timing for every target that was ever built, not just the most recent build, which overlaps multiple builds and exaggerates how parallel the build actually looked.
What is chrome's about:tracing viewer?It's Chrome's built-in timeline/trace viewer, originally built for profiling the browser itself, which ninjatracing's JSON output is directly compatible with.
What is trace2html used for?trace2html is a separate tool that converts the .json trace into a standalone .html file, so you can view the timeline without needing to open chrome://tracing.
What are similar projects?live-panel-skill, git-filter-repo, pyinstaller, scalene, task, bazel, hey, memray
Which topics is it in?profiling, script, chrome, build-tool, visualization, data-visualization, devops, performance, command-line-tool, terminal, tool, apache-2.0
Creator
nico
Size
0.1 MB
Stars
530
Updated
CommitJan 31
Age
12y
Commits · 90 Days