repository·main·Indexed 23 days ago
https://github.com/mourner/flamebearerA JavaScript CPU trace analysis tool (v2.1.0) that converts Chrome DevTools Performance recordings and Node.js CPU profiles into compact, structured text summaries. It provides a CLI for identifying CPU offenders and hot code paths, a Node.js script wrapper (flamebearer-node), and a programmatic API for parsing traces, resolving source maps, and generating performance reports for humans and AI agents.
flamebearer automatically de-minifies frames if source maps are available. It looks for:
.map filesTo disable this behavior and skip de-minification, use the --no-sourcemap flag.
You can refine the output of flamebearer using several flags to focus on specific functions, threads, or time ranges.
--stacks <function>: Generate a summary for a specific function.--thread <name>: Restrict the output to a specific thread.--top <number>: Restrict the number of rows shown in the top CPU section.--from <ms>: Slice the trace starting from a specific millisecond.--to <ms>: Slice the trace up to a specific millisecond.When using the flamebearer-node wrapper, pass these flags after a -- separator to ensure they are passed to the underlying flamebearer command.
# Summary for a specific function
flamebearer trace.json --stacks load
# Restrict to the 'main' thread and show the top 30 rows
flamebearer trace.json --thread main --top 30
# Slice a time range (in milliseconds)
flamebearer trace.json --from 1200 --to 1800
# Passing drilldown flags through the Node wrapper
flamebearer-node bench.js arg1 -- --stacks loadflamebearer trace.json --stacks load
flamebearer trace.json --thread main --top 30
flamebearer trace.json --from 1200 --to 1800
flamebearer-node bench.js arg1 -- --stacks loadInstall the flamebearer CLI tool globally to profile scripts or summarize existing trace files.
npm install -g flamebearerUse the flamebearer command to generate a compact, structured text summary of CPU performance. It supports Chrome DevTools recordings (.json or .json.gz) and Node.js .cpuprofile files.
# Summarize a Chrome DevTools trace
flamebearer profile.json.gz
# Summarize Node.js --cpu-prof traces (supports one or more files or a folder)
flamebearer CPU.*.cpuprofileflamebearer profile.json.gz
flamebearer CPU.*.cpuprofileUse the flamebearer-node wrapper to profile a specific Node.js script directly.
flamebearer-node bench.jsThe flamebearer CLI reads CPU traces (Chrome .json or .json.gz traces, or .cpuprofile files) and prints a plain-text summary of top CPU offenders, hot source lines, and heaviest stacks. This is designed for use in terminals and by AI agents.
Input Formats:
.json or .json.gz Chrome traces..cpuprofile files..cpuprofile files (multiple inputs are merged as additional threads).Basic Usage:
flamebearer <input>... [options]The topPaths function identifies the most expensive code paths in a thread by aggregating child nodes and returning a tree of the heaviest branches. This is the default view for high-level performance analysis.
Options:
cutoffPct: The percentage of total busy time a branch must consume to be included (default: 5).maxDepth: Maximum recursion depth for the tree (default: 6).maxBranch: Maximum number of branches to show per level (default: 3).budget: Total number of nodes allowed in the resulting tree (default: 8).The formatReport function is the primary way to generate a human-readable, colorized text summary of a trace. It can switch between a high-level 'top paths' view and a detailed 'stacks' view.
Options:
top: Number of top paths to show (default: 20).color: Boolean to enable ANSI color output.sourceMaps: Boolean to resolve source maps (default: true).from/to: Time range filters.threads: Thread name filters.stacks: If true, switches the report from 'top paths' to detailed 'findStacks' results for specific functions.mergeTraces to combine multiple trace objects into a single unified trace. This is useful for analyzing multiple files or threads as a single view. If multiple traces are provided, the resulting source is set to 'mixed'.Use findStacks to perform a deep dive into a specific function. It returns detailed information about the function's self-time, total time, callers, callees, and hot code lines.
Arguments:
thread: The thread object to search within.pattern: A string representing the function name to search for (case-insensitive).Special Case: If the pattern is '(garbage collector)', it uses specialized logic to reconstruct callers based on temporal adjacency (who was running when GC occurred).
Returns: An array of match groups. Each group contains:
frame: The function's call frame.self: Self-time in microseconds.total: Total time in microseconds.callers: Sorted list of functions that called this function.callees: Sorted list of functions called by this function.hotLines: The specific source lines where the most time was spent.suggestNames provides a list of the most likely candidates based on substring matches and Levenshtein edit distance, ranked by their self-time (relevance).Use filterTrace to narrow down a trace to a specific time range or a subset of threads. This is useful for zooming into specific performance events or focusing on specific workers.
Options:
from: Start time in milliseconds (relative to thread start).to: End time in milliseconds (relative to thread start).threads: An array of strings. Only threads whose names contain one of these strings will be included (case-insensitive).