wukong-profiler

🔥 High-performance Node.js / CLI wall-time profiler, designed for real async / await workloads.

Key capabilities:

• ✅ Accurate async / await wall-time profiling

• ✅ Nested steps (true hierarchical Flame Tree)

• ✅ Automatic HOT / SLOW step detection

• ✅ CPU vs I/O heuristic classification

• ✅ Actionable performance explanations

• ✅ Chrome Trace export (Chrome / Perfetto)

• ✅ Profile diff for regression detection (CI-friendly)

English | 简体中文

---

📦 Installation

npm install wukong-profiler

yarn add wukong-profiler

Or use directly via npx:

npx wukong-profiler [options]

---

🧑‍💻 CLI Usage

npx wukong-profiler report ./profile.json

CLI

# Generate HTML report from a profile.json
npx wukong-profiler report ./profile.json

To profile code, use the programmatic API (createProfiler) or the examples in the examples/ folder.

🧠 Output Example

⏱ Total 28.52 s
├─ getGitLogsFast        957.78 ms  ⚠ SLOW [IO]
│   ↳ Likely I/O-bound (serial await or blocking I/O)
├─ getOvertimeStats      26.39 s    🔥 HOT  [CPU]
│   ↳ Likely CPU-bound (loops or heavy computation)
│   ↳ Deep call stack — consider flattening logic

###

Generate HTML report

# Generate HTML report from profile.json
npx wukong-profiler report ./profile.json

# Generate and open automatically in browser
npx wukong-profiler report ./profile.json --open

# Specify output HTML file
npx wukong-profiler report ./profile.json -o my-report.html

Usage: npx wukong-profiler report <profile>

<profile> is the path to a profile.json file (required).

Report subcommand options:

Option	Description
--profile	Saved profile JSON for analysis
-o, --output <file>	Output HTML file (default: “wukong-report.html”)
--open	Open the report in the default browser after generation

Note: This CLI only exposes the report subcommand. To profile code, use the JavaScript API (createProfiler) or the examples/ folder. For report-specific help run npx wukong-profiler report -h.

---

📘 Programmatic Usage

import { createProfiler } from 'wukong-profiler'

const profiler = createProfiler({
  enabled: true,
  flame: true,
  traceFile: 'trace.json',
  profileFile: 'artifacts/profile.json', // write profile to a custom directory
  hotThreshold: 0.8,
  failOnHot: true,
  diffBaseFile: 'baseline.json',
  diffThreshold: 0.2
})

// Example: write outputs to an `artifacts/` folder for CI
// const profiler = createProfiler({ enabled: true, profileFile: 'artifacts/profile.json', traceFile: 'artifacts/trace.json' })

profiler.step('load config', () => {
  // sync work
})

await profiler.stepAsync('fetch data', async () => {
  await fetchRemoteData()
})

profiler.end('Total')

---

Async / Await Profiling (Recommended)

wukong-profiler explicitly supports async profiling via stepAsync.

This guarantees correct wall-time measurement, even when the event loop is idle.

await profiler.stepAsync('getGitLogsFast', async () => {
  await readGitLogs()
})

await profiler.stepAsync('getOvertimeStats', async () => {
  await calculateStats()
})

Why stepAsync?

• ✔ Measures full async duration (not just sync part)

• ✔ Maintains correct nesting structure

• ✔ Enables accurate I/O vs CPU classification

---

🧩 API Reference

createProfiler(options)

Returns a profiler instance.

Options

Name	Default	Description
enabled	false	Enable output & JSON export
verbose	false	Verbose logging
flame	false	Flame-style tree output
slowThreshold	500	Slow step threshold (ms)
hotThreshold	0.8	HOT step ratio
traceFile	undefined	Chrome trace file		profileFile	profile.json	Path to write profile JSON file		failOnHot	false	Fail CI on HOT step
diffBaseFile	undefined	Base profile for diff
diffThreshold	0.2	Regression threshold

---

profiler.step(name, fn)

Measure a synchronous step.

profiler.step('parse config', () => {
  parseConfig()
})

profiler.stepAsync(name, asyncFn)

Measure an async step with full wall-time accuracy.

await profiler.stepAsync('fetch users', async () => {
  await fetchUsers()
})

---

profiler.measure(name, fn)

Alias of step (sync). For async workloads, prefer stepAsync for clarity.

---

profiler.end(label?)

Finish profiling and output results.

profiler.end('Total')

---

profiler.summary(options?)

Get structured summary data for reporting or CI.

const summary = profiler.summary({ top: 3 })

summary.top.forEach((step) => {
  console.log(step.name, step.ratio)
})

---

📊 Profile Summary (Top HOT Paths)

const summary = profiler.summary({ top: 3 })

summary.top.forEach((step) => {
  console.log(step.path, step.ratio)
})

---

Examples

node examples/basic.mjs
node examples/flame.mjs
node examples/async.mjs

---

🧪 Chrome Trace

node examples/basic.mjs

Open:

chrome://tracing

Load the generated trace file.

or

https://ui.perfetto.dev

drag to Load the generated trace file.

This site is open source. Improve this page.