[!NOTE]

This package is in a beta state and I'm excited for you to try it out!

I'd love your feedback! Share any suggestions, bug reports, feature requests, or general thoughts by filing an issue.

Features

• Multi-format: supports pprof, Speedscope, V8 CPU profiles, V8 heap profiles, and V8 heap snapshots
• Multi-language: JS/TS via V8 formats (Node.js, Bun, Deno); Go, Python, Rust, Java, and more via pprof and Speedscope
• Configurable: control the number of top entries shown, working directory for relative paths, third-party detection, and entry filtering
• CLI and API: usable on the command-line or programmatically

Install

$ npm i profiler-md

Usage

CLI

$ profiler-md --help

  Converts performance profiles to human and LLM friendly Markdown.

  Usage: profiler-md [options] [file]

  Options:
    -t, --type <type>     Profile type, auto-detected from content if omitted
                          [pprof|speedscope|v8-cpu-profile|v8-heap-profile|v8-heap-snapshot]
    -o, --output <file>   Output file (default: - for stdout)
    --top-n <n>           Number of top entries to show (default: 20)
    --cwd <path>          Working directory for relative file paths in output
    --third-party <glob>  Mark URLs matching this glob as third-party
                          (repeatable; default: node_modules)
    --source-maps <glob>  Apply source maps matching this glob to profile
                          locations; files may be source map JSON or contain
                          inline source map comments (repeatable)
    --help                Show this help message

API

import { readFile } from 'node:fs/promises'
import {
  defaultIncludeEntry,
  defaultIsThirdPartyEntry,
  pprofToMd,
  speedscopeProfileToMd,
  v8CpuProfileToMd,
  v8HeapProfileToMd,
  v8HeapSnapshotToMd,
} from 'profiler-md'

const pprofData = await readFile(`example.pprof`)
const speedscopeProfileData = await readFile(`example.speedscope.json`)
const v8CpuProfileData = await readFile(`example.cpuprofile`)
const v8HeapProfileData = await readFile(`example.heapprofile`)
const v8HeapSnapshotData = await readFile(`example.heapsnapshot`)

// Basic usage
console.log(pprofToMd(pprofData))
console.log(speedscopeProfileToMd(speedscopeProfileData))
console.log(v8CpuProfileToMd(v8CpuProfileData))
console.log(v8HeapProfileToMd(v8HeapProfileData))
console.log(v8HeapSnapshotToMd(v8HeapSnapshotData))

// Complex usage
const options = {
  // Show top 10 functions instead of the default 20.
  topN: 10,
  // Make paths relative to a custom directory.
  cwd: `/path/to/project`,
  isThirdPartyEntry: entry =>
    defaultIsThirdPartyEntry(entry) ||
    // Treat an additional vendor directory as third-party.
    !!entry.location?.url.pathname.includes(`/vendor/`),
  includeEntry: entry =>
    defaultIncludeEntry(entry) &&
    // Exclude entries from a specific file.
    !entry.location?.includes(`/path/to/project/src/noisy`),
}
console.log(pprofToMd(pprofData, options))
console.log(speedscopeProfileToMd(speedscopeProfileData, options))
console.log(v8CpuProfileToMd(v8CpuProfileData, options))
console.log(v8HeapProfileToMd(v8HeapProfileData, options))
console.log(v8HeapSnapshotToMd(v8HeapSnapshotData, options))

Skills

Use this profiler-md skill to have an agent profile and optimize your code:

$ npx skills add TomerAberbach/profiler-md --skill profile-optimize

See skills.sh for more info.

Fun fact: the skill has been used to profile and optimize profiler-md using itself!

Contributing

Stars are always welcome!

For bugs and feature requests, please create an issue.

License

MIT © Tomer Aberbach