flamebearer: CPU trace analysis for Node and Chrome

flamebearer's CPU trace triage workflow

flamebearer solves a narrow problem: deciding where to look after collecting a JavaScript CPU trace. Its README describes the audience as agents and humans working through performance optimization loops. That wording matters because the tool does not try to be a graphical profiler or a general observability platform. It reads existing recordings and prints a compact, structured report that can be read directly in a terminal or passed into another automated process.

The supported inputs are Chrome DevTools Performance recordings in `.json` or `.json.gz` form and Node `.cpuprofile` files. With no flags, the command produces a one-page summary for each thread. The summary includes sample and busy-time information, the heaviest stacks, top CPU by self time, and hot source lines. That output is designed to answer the first investigation question quickly: which functions and source locations consumed the thread's time?

The distinction between self time and stack share is useful for triage. Self time identifies where sampled execution is attributed directly, while the stack section shows how that work fits into a larger call chain. A hot dependency can therefore stand out in the source-line report even when the application entry point appears first in the stack view. The README also says that long tasks are summarized, although the sample output focuses mainly on CPU offenders and source lines.

The project is not restricted to Node.js. A Chrome DevTools trace can be passed directly to flamebearer, and the Node wrapper provides a way to profile a script. The repository package is an ES module named flamebearer, with the main implementation in `index.js` and two command-line entry points under `bin/`. The package metadata identifies Node, profiling, traces, V8, and performance as its topics.

Reading flamebearer output and drilling into traces

The CLI is built around a summary-first workflow, followed by targeted filters. The default report gives one page per thread and highlights the heaviest stacks as percentages of thread busy time. It then lists self-time contributors in descending order, including function names and source locations when available. A separate hot-lines section groups samples by source line and accounts for inlined code according to the README.

This structure is different from printing every recorded event. flamebearer reduces a trace to a ranked set of candidates for investigation. The README's sample output attributes substantial time to functions in `node_modules/kdbush/index.js`, while also showing application functions such as `_cluster` and `load` in the source tree. The report makes dependency code and project code visible without requiring the reader to reconstruct the trace manually.

Filters can narrow the report to a function, several functions, a thread, a larger top-row count, or a time interval. The README gives these concrete forms:

flamebearer trace.json --stacks load

That command focuses the summary on a function named `load`. Multiple names can be supplied in one run:

flamebearer trace.json --stacks load,parse

The thread and row controls operate on the same report:

flamebearer trace.json --thread main --top 30

A time range can be used when a report contains an expensive period rather than an obviously expensive function:

flamebearer trace.json --from 1200 --to 1800

The Node wrapper passes drilldown flags through its separator:

flamebearer-node bench.js arg1 -- --stacks load

These options make flamebearer useful for successive investigation steps rather than a single fixed report. The README points to `flamebearer --help` for the complete flag list, so its examples are the confirmed command surface here rather than a complete specification of every available option.

Installing flamebearer and running a first profile

The documented installation is global npm installation. This makes the `flamebearer` and `flamebearer-node` commands available from the shell:

npm install -g flamebearer

For a first Node.js profile, pass the script to `flamebearer-node`. The wrapper is the path described by the README for profiling a script:

flamebearer-node bench.js

The reader should expect flamebearer to print a compact CPU summary rather than open an HTML document. The package metadata confirms that both `flamebearer` and `flamebearer-node` are registered binaries, so this is a command-line installation rather than a library API setup.

An existing recording can be summarized with either filename pattern shown in the README:

flamebearer profile.json.gz

This command reads a compressed Chrome DevTools recording. Node CPU profiles use the `flamebearer` command too:

flamebearer CPU.*.cpuprofile

The README states that the Node command accepts one or more files or a folder, although the example uses a shell glob. Expansion of that glob and any folder selection therefore depend on the local shell and command input rather than a graphical workflow.

For a normal first pass, run `flamebearer-node` against the script that reproduces the performance problem, then rerun the summary with a narrower `--stacks`, `--thread`, or time-range filter. This sequence matches the README's stated purpose: begin with the answer to what should be inspected, then drill into the relevant function or interval.

Source maps and boundaries of Chrome trace support

Source-map handling is built into flamebearer rather than left as a separate post-processing step. The README states that minified frames are de-minified automatically when source maps are available. It identifies three possible sources: sibling `.map` files, inline maps, and maps embedded in a Chrome trace. This matters for projects that ship transpiled or bundled JavaScript, because a report can otherwise point at generated locations instead of code recognized by a maintainer.

The behavior can be disabled with the documented option:

flamebearer trace.json --no-sourcemap

That switch is useful when the original source mapping is misleading or when the reader wants the recorded frame names without translation. The README does not claim that flamebearer can reconstruct a missing source map, so it should not be expected to produce original source locations when no mapping is available.

Chrome support is centered on Performance recordings, not arbitrary browser automation output. The documented `.json` and `.json.gz` inputs indicate that flamebearer consumes a trace that has already been recorded. It does not document a browser extension, recorder, or live monitoring mode. The project is therefore better suited to offline analysis after collection than to watching a running page continuously.

The combination of Chrome input support, Node `.cpuprofile` support, and automatic source-map translation makes flamebearer a reporting layer for two related environments. The underlying data still comes from V8 or the recording tool, so flamebearer summarizes sampling information rather than replacing the profiler that collected it.

Failure cases and the wrong tool for flamebearer

The clearest limitation is the deliberate absence of an HTML interface. The README explicitly says “No HTML, no GUI” and points to Speedscope for that use case. A user who needs to explore call stacks visually, zoom through nested frames, or interact with a graphical flame graph will get a different workflow from Speedscope. flamebearer is designed for a compact answer and drilldown, not for replacing visual profiling tools.

The input scope is also limited. The documented formats are Chrome DevTools Performance recordings and Node `.cpuprofile` files. The README does not document flamebearer as a general trace viewer, system-wide profiler, browser automation recorder, or live telemetry service. A project that needs continuous CPU monitoring rather than post-run analysis should not treat this CLI as a monitoring system.

Another constraint is the source-map boundary. Automatic de-minification depends on an available mapping. If a deployment removes sibling maps, omits inline maps, and produces a Chrome recording without an embedded map, the report may not identify the original source lines. The README does not document an option for supplying an arbitrary source-map file, so that case requires checking the recorded inputs before relying on source-level results.

The report can only summarize what the trace contains. flamebearer does not claim to reproduce a workload, modify application code, or prove that a selected function is the sole cause of a slow operation. Its output is a prioritization aid for performance investigation. Sampling also means that brief operations or lightly sampled code may not appear prominently, although the README does not provide a numerical threshold for interpreting the results.

flamebearer compared with Speedscope and its CLI niche

Speedscope is the direct alternative named by the README, and the difference is interface and workflow. Speedscope provides the graphical flame graph experience that flamebearer intentionally leaves out. flamebearer instead turns CPU evidence into terminal text, with ranked functions, source lines, thread summaries, and command-line filters. A human doing broad visual exploration may prefer Speedscope; an automation step or agent looking for a small set of hotspots may prefer flamebearer's output format.

The README also credits 0x as the project that originally inspired flamebearer. It does not document 0x's command set or provide a detailed feature comparison, so a claim-by-claim comparison would go beyond the known information. The documented history of flamebearer is still revealing. The README says the project used to generate an HTML flamegraph for Node traces, remained dormant after 2018, and was revived in 2026 with a CLI-oriented purpose. Its current text reports reflect that change in direction.

The practical choice is based on output needs. Choose flamebearer when the result should be plain text, filterable by function names or time ranges, and convenient within a command-oriented process. Choose Speedscope when interactive flame graph inspection is the main requirement. The README does not claim that flamebearer replaces either tool for all profiling tasks, and its stated feature set supports treating it as a narrower analysis layer.

Maintenance, licensing, and upgrade boundaries

The repository is not archived. Its last push was on 2026-10-15, and `package.json` reports version 2.2.0. The release history also lists v2.2.0 on 2026-10-15 and v2.1.0 and v2.0.0 on 2026-06-25. The project therefore has recent development activity, but the README does not provide a release policy, compatibility matrix, or migration guide for moving between v1 and the v2 releases.

The package uses the ISC license. The repository contains an `LICENSE` file, and `package.json` declares the same license identifier. That is relevant to adoption because flamebearer is distributed as an npm package, but this article does not interpret the license or provide legal advice.

The published package has a small declared file set containing `bin` and `index.js`. Its runtime dependency is `@jridgewell/trace-mapping`. Development dependencies include `eslint` and `eslint-config-mourner`. The package declares both command binaries and identifies Node.js and V8-related trace processing as its subject area. The README does not state a minimum Node.js version, so runtime compatibility must be checked before installation in a constrained environment.

For users who rely only on the documented commands, adoption introduces a relatively small package and CLI surface. That does not prove upgrades are free of disruption. The README does not document breaking changes or whether scripts that parse flamebearer's text output will remain compatible. Automation should therefore verify its expected fields against the selected release instead of assuming that every v2 release preserves the sample layout.

Editorial conclusion

Adopt flamebearer when a Node or Chrome CPU trace needs a text-oriented triage pass, especially in an automation or agent workflow. Do not choose it when an interactive flame graph is the primary requirement, since the README points to Speedscope for that case. Verify first that the trace format is supported, that source maps are available when frame names need translation, and that the summary ranks functions relevant to the workload.

Frequently asked questions

Official sources

1. Issues
2. License: ISC
3. mourner/flamebearer on GitHub
4. README
5. Releases