{"_id":"pprof-to-md","_rev":"2-84b2687f5fa04d212a85bd8b992d96c4","name":"pprof-to-md","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"pprof-to-md","version":"0.1.0","keywords":["pprof","profiling","performance","llm","markdown","analysis"],"license":"Apache-2.0","_id":"pprof-to-md@0.1.0","maintainers":[{"name":"matteo.collina","email":"hello@matteocollina.com"}],"homepage":"https://github.com/platformatic/pprof-to-md#readme","bugs":{"url":"https://github.com/platformatic/pprof-to-md/issues"},"bin":{"pprof-to-md":"dist/cli.js"},"dist":{"shasum":"af67e9e48fb9c04c3bc35f9111f6ca835f0aa2e6","tarball":"https://registry.npmjs.org/pprof-to-md/-/pprof-to-md-0.1.0.tgz","fileCount":42,"integrity":"sha512-2OnF8vTBT37lfaDwIK9xJHGl6Sl05mQpoFjnqLOrLw0XTSN8tj6nVlwIOSAi67Ys57/qZpyHvqzpQlw36bH4kg==","signatures":[{"sig":"MEUCIQDjRyrW2d96MREWZZkQBYSiwxyntdIZWwc9DnTLk9/hhAIgBJ4D3f30PrlRa75/Suou89GOAtDVCCQYTEcBnimylP4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":118865},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=22.6.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a44ca0678e7c4d20917493baeeab2c445ed143f1","scripts":{"test":"node --test test/*.test.ts","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run build","generate-profiles":"node test/generate-profiles.ts"},"_npmUser":{"name":"matteo.collina","email":"hello@matteocollina.com"},"repository":{"url":"git+https://github.com/platformatic/pprof-to-md.git","type":"git"},"_npmVersion":"11.6.2","description":"Convert pprof profiling data into Markdown format for performance analysis","directories":{},"_nodeVersion":"24.13.0","dependencies":{"pprof-format":"^2.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0","@datadog/pprof":"^5.4.1"},"_npmOperationalInternal":{"tmp":"tmp/pprof-to-md_0.1.0_1769015657164_0.4018122633070047","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"pprof-to-md","version":"0.2.0","description":"Convert pprof profiling data into Markdown format for performance analysis","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"pprof-to-md":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build","test":"node --test test/*.test.ts","typecheck":"tsc --noEmit","generate-profiles":"node test/generate-profiles.ts"},"keywords":["pprof","profiling","performance","llm","markdown","analysis"],"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/platformatic/pprof-to-md.git"},"dependencies":{"pprof-format":"^2.1.0"},"devDependencies":{"@datadog/pprof":"^5.4.1","@types/node":"^22.0.0","typescript":"^5.7.0"},"engines":{"node":">=22.6.0"},"gitHead":"42db5993af5c2c62337f14f534ad29f0fa9bad3a","_id":"pprof-to-md@0.2.0","bugs":{"url":"https://github.com/platformatic/pprof-to-md/issues"},"homepage":"https://github.com/platformatic/pprof-to-md#readme","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-+xo3aSoDHI+M6DnM5jW6Iva4I0LS3NmAAkci3fGSIj6JiP8hs5o8IWpmkTtoQ62l9joDC8eSSOZE9dt1t38HHw==","shasum":"01dee3160a9f350de20a6bd357d81467adaee08e","tarball":"https://registry.npmjs.org/pprof-to-md/-/pprof-to-md-0.2.0.tgz","fileCount":42,"unpackedSize":118758,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEYPXwCfvsLCWMQ/TSTWiN2ZcIcZe4+hWmLdt+wjuyxBAiAhkoYhqvnJ6abKTYGs/dHB7g9NWGKibEE4daMcAUCA5A=="}]},"_npmUser":{"name":"matteo.collina","email":"hello@matteocollina.com"},"directories":{},"maintainers":[{"name":"matteo.collina","email":"hello@matteocollina.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pprof-to-md_0.2.0_1769708784639_0.5056640380612811"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-21T17:14:17.163Z","modified":"2026-01-29T17:46:24.919Z","0.1.0":"2026-01-21T17:14:17.307Z","0.2.0":"2026-01-29T17:46:24.801Z"},"bugs":{"url":"https://github.com/platformatic/pprof-to-md/issues"},"license":"Apache-2.0","homepage":"https://github.com/platformatic/pprof-to-md#readme","keywords":["pprof","profiling","performance","llm","markdown","analysis"],"repository":{"type":"git","url":"git+https://github.com/platformatic/pprof-to-md.git"},"description":"Convert pprof profiling data into Markdown format for performance analysis","maintainers":[{"name":"matteo.collina","email":"hello@matteocollina.com"}],"readme":"# pprof-to-md\n\nConvert pprof profiling data into Markdown format for LLM-assisted performance analysis.\n\n## Overview\n\n`pprof-to-md` transforms binary pprof profiles into structured Markdown that LLMs can analyze to identify performance bottlenecks, explain root causes, and suggest optimizations.\n\n## Installation\n\n```bash\nnpm install pprof-to-md\n```\n\nOr run directly:\n\n```bash\nnpx pprof-to-md profile.pb.gz\n```\n\n## Usage\n\n### CLI\n\n```bash\n# Basic usage - analyze a CPU profile\npprof-to-md cpu-profile.pb.gz\n\n# Output to file\npprof-to-md profile.pb.gz -o analysis.md\n\n# Detailed format with full call tree\npprof-to-md --format=detailed profile.pb.gz\n\n# Summary format for quick triage\npprof-to-md --format=summary profile.pb.gz\n\n# Memory profile analysis\npprof-to-md --type=heap heap-profile.pb.gz\n```\n\n### Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-f, --format` | Output format: `summary`, `detailed`, `adaptive` | `adaptive` |\n| `-t, --type` | Profile type: `cpu`, `heap`, `auto` | `auto` |\n| `-o, --output` | Output file (stdout if not specified) | - |\n| `-s, --source-dir` | Source directory for code context | - |\n| `--no-source` | Disable source code inclusion | `false` |\n| `--max-hotspots` | Maximum hotspots to show | `10` |\n\n### Programmatic API\n\n```typescript\nimport { convert } from 'pprof-to-md'\n\nconst markdown = convert('profile.pb.gz', {\n  format: 'adaptive',\n  profileType: 'cpu',\n  maxHotspots: 10\n})\n\nconsole.log(markdown)\n```\n\n## Output Formats\n\n### Summary\n\nCompact format for quick triage:\n\n```markdown\n# PPROF Analysis: CPU\n\n**Profile:** `profile.pb.gz`\n**Duration:** 30s | **Samples:** 45,231\n\n## Top Hotspots (by self-time)\n\n| Rank | Function | Self% | Cum% | Location |\n|------|----------|-------|------|----------|\n| 1 | `JSON.parse` | 23.4% | 23.4% | `<native>` |\n| 2 | `processRequest` | 15.2% | 67.8% | `handler.ts:142` |\n\n## Key Observations\n\n- Native `JSON.parse` dominates (**23.4%** self-time)\n```\n\n### Detailed\n\nFull context with annotated call trees:\n\n```markdown\n## Call Tree (annotated flame graph)\n\n> Legend: `[self% | cum%] function @ location`\n\n[  0.1% | 100.0%] (root)\n└── [ 15.2% |  67.8%] processRequest @ handler.ts:142  ◀ HOTSPOT\n    └── [ 23.4% |  23.4%] JSON.parse @ <native>  ◀ HOTSPOT\n\n## Function Details\n\n### `processRequest` @ `handler.ts:142`\n\n**Samples:** 6,878 (15.2% self) | **Cumulative:** 30,678 (67.8%)\n**Callers:** `handleHTTP`\n**Callees:** `parseBody`, `validateSchema`\n```\n\n### Adaptive (Default)\n\nSummary with drill-down sections and anchor links:\n\n```markdown\n## Executive Summary\n\n- **Primary bottleneck:** `JSON.parse` (**23.4%** of CPU)\n- **Optimization potential:** 🟢 HIGH (67% in application code)\n\n## Top Hotspots\n\n1. `JSON.parse` (**23.4%**) → [Details](#json-parse)\n2. `processRequest` (**15.2%**) → [Details](#processrequest)\n\n---\n\n## Detailed Analysis\n\n<a id=\"json-parse\"></a>\n\n### `JSON.parse`\n\n**Call path:** `handleHTTP` → `processRequest` → `parseBody` → `JSON.parse`\n**Self-time:** 23.4% (10,584 samples)\n```\n\n## Collecting Profiles\n\n### Node.js with @datadog/pprof\n\n```typescript\nimport * as pprof from '@datadog/pprof'\nimport { writeFileSync } from 'fs'\nimport { gzipSync } from 'zlib'\n\n// CPU profiling\npprof.time.start({ durationMillis: 30000 })\n// ... run workload ...\nconst profile = await pprof.time.stop()\nwriteFileSync('cpu.pb.gz', gzipSync(profile.encode()))\n\n// Heap profiling\npprof.heap.start(512 * 1024, 64)\n// ... run workload ...\nconst heapProfile = await pprof.heap.profile()\nwriteFileSync('heap.pb.gz', gzipSync(heapProfile.encode()))\n```\n\n## Requirements\n\n- Node.js >= 22.6.0 (uses native TypeScript type stripping)\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}