Add pprof-to-md integration for LLM-friendly markdown analysis (#58)

Integrates pprof-to-md to generate markdown analysis files alongside existing
HTML flamegraphs and pb files, making profile data more accessible to LLMs and
automated analysis tools.

Changes:
- Added pprof-to-md dependency and bumped Node.js requirement to >=22.6.0
- Implemented generateMarkdown() function in lib/index.js
- Extended preload.js to generate markdown files automatically
- Added --md-format CLI flag supporting summary/detailed/adaptive modes
- Added comprehensive test coverage (8 new tests across unit/integration)
- Updated documentation with markdown generation examples and usage

The markdown format provides structured, readable profile analysis that can be
easily consumed by LLMs, while maintaining full backward compatibility with
existing HTML and pb output formats.

Author: mcollina

README.md

@@ -7,6 +7,7 @@
 - **Dual Profiling**: Captures both CPU and heap profiles concurrently for comprehensive performance insights
 - **Auto-Start Profiling**: Profiling starts immediately when using `flame run` (default behavior)
 - **Automatic Flamegraph Generation**: Interactive HTML flamegraphs are created automatically for both CPU and heap profiles on exit
+- **LLM-Friendly Markdown Analysis**: Generates markdown reports with hotspot analysis, ideal for AI-assisted performance debugging
 - **Sourcemap Support**: Automatically translates transpiled code locations back to original source files (TypeScript, bundled JavaScript, etc.)
 - **Clear File Path Display**: Shows exact paths and browser URLs for generated files
 - **Manual Control**: Optional manual mode with signal-based control using `SIGUSR2`
@@ -34,10 +35,11 @@ flame run server.js
 # 🔥 Heap profile written to: heap-profile-2025-08-27T12-00-00-000Z.pb
 # 🔥 Generating CPU flamegraph...
 # 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T12-00-00-000Z.html
+# 🔥 CPU markdown generated: cpu-profile-2025-08-27T12-00-00-000Z.md
 # 🔥 Generating heap flamegraph...
 # 🔥 Heap flamegraph generated: heap-profile-2025-08-27T12-00-00-000Z.html
+# 🔥 Heap markdown generated: heap-profile-2025-08-27T12-00-00-000Z.md
 # 🔥 Open file:///path/to/cpu-profile-2025-08-27T12-00-00-000Z.html in your browser to view the CPU flamegraph
-# 🔥 Open file:///path/to/heap-profile-2025-08-27T12-00-00-000Z.html in your browser to view the heap flamegraph
 ```
 
 ### Manual Profiling Mode
@@ -53,14 +55,17 @@ kill -USR2 <PID>
 flame toggle
 ```
 
-### Generate Flamegraph
+### Generate Flamegraph and Markdown
 
 ```bash
-# Generate HTML flamegraph from pprof file
+# Generate HTML flamegraph and markdown from pprof file
 flame generate cpu-profile-2024-01-01T12-00-00-000Z.pb
 
 # Specify custom output file
 flame generate -o my-flamegraph.html profile.pb.gz
+
+# Use detailed markdown format for comprehensive analysis
+flame generate --md-format=detailed profile.pb
 ```
 
 ## CLI Usage
@@ -70,14 +75,15 @@ flame [options] <command>
 
 Commands:
   run <script>           Run a script with profiling enabled
-  generate <pprof-file>  Generate HTML flamegraph from pprof file
+  generate <pprof-file>  Generate HTML flamegraph and markdown from pprof file
   toggle                 Toggle profiling for running flame processes
 
 Options:
   -o, --output <file>       Output HTML file (for generate command)
   -m, --manual             Manual profiling mode (require SIGUSR2 to start)
   -d, --delay <value>      Delay before starting profiler (ms, 'none', or 'until-started')
   -s, --sourcemap-dirs <dirs>  Directories to search for sourcemaps (colon/semicolon-separated)
+      --md-format <format>  Markdown format: summary (default), detailed, or adaptive
       --node-options <options>  Node.js CLI options to pass to the profiled process
   -h, --help               Show help message
   -v, --version            Show version number
@@ -86,7 +92,7 @@ Options:
 ## Programmatic API
 
 ```javascript
-const { startProfiling, generateFlamegraph, parseProfile } = require('@platformatic/flame')
+const { startProfiling, generateFlamegraph, generateMarkdown, parseProfile } = require('@platformatic/flame')
 
 // Start profiling a script with auto-start (default)
 const { pid, toggleProfiler } = startProfiling('server.js', ['--port', '3000'], { autoStart: true })
@@ -102,16 +108,20 @@ toggleProfiler()
 // Generate interactive flamegraph from pprof file
 await generateFlamegraph('profile.pb.gz', 'flamegraph.html')
 
+// Generate LLM-friendly markdown analysis
+await generateMarkdown('profile.pb', 'analysis.md', { format: 'summary' })
+
 // Parse profile data
 const profile = await parseProfile('profile.pb')
 ```
 
 ## How It Works
 
 1. **Auto-Start Mode (Default)**: Both CPU and heap profiling begin immediately when `flame run` starts your script
-2. **Auto-Generation on Exit**: Profile (.pb) files and interactive HTML flamegraphs are automatically created for both CPU and heap profiles when the process exits
+2. **Auto-Generation on Exit**: Profile (.pb) files, interactive HTML flamegraphs, and markdown analysis files are automatically created for both CPU and heap profiles when the process exits
 3. **Manual Mode**: Use `--manual` flag to require `SIGUSR2` signals for start/stop control (no auto-HTML generation)
 4. **Interactive Visualization**: The `@platformatic/react-pprof` library generates interactive WebGL-based HTML flamegraphs for both profile types
+5. **Markdown Analysis**: The `pprof-to-md` library generates LLM-friendly markdown reports with hotspot tables for AI-assisted debugging
 
 ## Sourcemap Support
 
@@ -167,11 +177,23 @@ flame run server.js
 
 Profile files are saved with timestamps in the format:
 ```
-cpu-profile-2024-01-01T12-00-00-000Z.pb
+cpu-profile-2024-01-01T12-00-00-000Z.pb     # Binary pprof data
+cpu-profile-2024-01-01T12-00-00-000Z.html   # Interactive flamegraph
+cpu-profile-2024-01-01T12-00-00-000Z.md     # LLM-friendly markdown analysis
 heap-profile-2024-01-01T12-00-00-000Z.pb
+heap-profile-2024-01-01T12-00-00-000Z.html
+heap-profile-2024-01-01T12-00-00-000Z.md
 ```
 
-Both CPU and heap profiles share the same timestamp for easy correlation. The files are compressed Protocol Buffer format compatible with the pprof ecosystem.
+Both CPU and heap profiles share the same timestamp for easy correlation. The `.pb` files are compressed Protocol Buffer format compatible with the pprof ecosystem. The `.md` files contain hotspot analysis tables suitable for AI/LLM-assisted performance debugging.
+
+### Markdown Formats
+
+The `--md-format` option controls the markdown output:
+
+- **summary** (default): Compact hotspots table, ideal for AI triage and quick overview
+- **detailed**: Comprehensive analysis with full stack traces and detailed statistics
+- **adaptive**: Automatically chooses format based on profile complexity
 
 ## Integration with Existing Apps
 
@@ -200,14 +222,15 @@ curl http://localhost:3000
 curl http://localhost:3000
 curl http://localhost:3000
 
-# Stop the server (Ctrl-C) to automatically save profiles and generate HTML flamegraphs
+# Stop the server (Ctrl-C) to automatically save profiles and generate flamegraphs
 # You'll see the exact file paths and browser URLs in the output:
 # 🔥 CPU profile written to: cpu-profile-2025-08-27T15-30-45-123Z.pb
 # 🔥 Heap profile written to: heap-profile-2025-08-27T15-30-45-123Z.pb
 # 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T15-30-45-123Z.html
+# 🔥 CPU markdown generated: cpu-profile-2025-08-27T15-30-45-123Z.md
 # 🔥 Heap flamegraph generated: heap-profile-2025-08-27T15-30-45-123Z.html
+# 🔥 Heap markdown generated: heap-profile-2025-08-27T15-30-45-123Z.md
 # 🔥 Open file:///path/to/cpu-profile-2025-08-27T15-30-45-123Z.html in your browser to view the CPU flamegraph
-# 🔥 Open file:///path/to/heap-profile-2025-08-27T15-30-45-123Z.html in your browser to view the heap flamegraph
 ```
 
 **Manual Mode:**
@@ -296,9 +319,10 @@ kill -USR2 <PID>
 
 ## Requirements
 
-- Node.js >= 18.0.0
-- `@datadog/pprof` for CPU profiling
-- `@platformatic/react-pprof` for flamegraph generation
+- Node.js >= 22.6.0
+- `@datadog/pprof` for CPU and heap profiling
+- `react-pprof` for flamegraph generation
+- `pprof-to-md` for markdown analysis generation
 
 ## License
 

bin/flame.js

@@ -3,7 +3,7 @@
 const { parseArgs } = require('node:util')
 const fs = require('fs')
 const path = require('path')
-const { startProfiling, generateFlamegraph } = require('../lib/index.js')
+const { startProfiling, generateFlamegraph, generateMarkdown } = require('../lib/index.js')
 
 const { values: args, positionals } = parseArgs({
   args: process.argv.slice(2),
@@ -42,6 +42,9 @@ const { values: args, positionals } = parseArgs({
     'node-modules-source-maps': {
       type: 'string',
       short: 'n'
+    },
+    'md-format': {
+      type: 'string'
     }
   },
   allowPositionals: true
@@ -59,7 +62,7 @@ Usage: flame [options] <command>
 
 Commands:
   run <script>           Run a script with profiling enabled
-  generate <pprof-file>  Generate HTML flamegraph from pprof file
+  generate <pprof-file>  Generate HTML flamegraph and markdown from pprof file
 
 Options:
   -o, --output <file>     Output HTML file (for generate command)
@@ -69,6 +72,7 @@ Options:
   -s, --sourcemap-dirs <dirs>  Directories to search for sourcemaps (colon/semicolon-separated)
   -n, --node-modules-source-maps <mods>  Node modules to load sourcemaps from (comma-separated, e.g., "next,@next/next-server")
       --node-options <options>  Node.js CLI options to pass to the profiled process
+      --md-format <format>  Markdown format: summary (default), detailed, or adaptive
   -h, --help             Show this help message
   -v, --version          Show version number
 
@@ -80,6 +84,7 @@ Examples:
   flame run --delay=until-started server.js                # Start profiling after next event loop tick (default)
   flame run --sourcemap-dirs=dist:build server.js          # Enable sourcemap support
   flame run -n next,@next/next-server server.js            # Load Next.js sourcemaps from node_modules
+  flame run --md-format=detailed server.js                 # Use detailed markdown format
   flame run --node-options="--require ts-node/register" server.ts     # With Node.js options
   flame run --node-options="--import ./loader.js --max-old-space-size=4096" server.js
   flame generate profile.pb.gz
@@ -136,12 +141,20 @@ async function main () {
           ? args['node-modules-source-maps'].split(',').map(s => s.trim())
           : undefined
 
+        // Parse markdown format option
+        const mdFormat = args['md-format'] || 'summary'
+        if (!['summary', 'detailed', 'adaptive'].includes(mdFormat)) {
+          console.error(`Error: Invalid md-format value '${mdFormat}'. Must be 'summary', 'detailed', or 'adaptive'.`)
+          process.exit(1)
+        }
+
         const { pid, process: childProcess } = startProfiling(script, scriptArgs, {
           autoStart,
           nodeOptions,
           delay,
           sourcemapDirs,
-          nodeModulesSourceMaps
+          nodeModulesSourceMaps,
+          mdFormat
         })
 
         console.log(`🔥 Started profiling process ${pid}`)
@@ -188,13 +201,30 @@ async function main () {
           process.exit(1)
         }
 
+        // Parse markdown format option
+        const mdFormat = args['md-format'] || 'summary'
+        if (!['summary', 'detailed', 'adaptive'].includes(mdFormat)) {
+          console.error(`Error: Invalid md-format value '${mdFormat}'. Must be 'summary', 'detailed', or 'adaptive'.`)
+          process.exit(1)
+        }
+
         const outputFile = args.output || `${path.basename(pprofFile, path.extname(pprofFile))}.html`
+        const mdOutputFile = outputFile.replace(/\.html$/, '.md')
         const profileType = path.basename(pprofFile).includes('heap') ? 'Heap' : 'CPU'
 
         console.log(`🔥 Generating ${profileType} flamegraph from ${pprofFile}...`)
         await generateFlamegraph(pprofFile, outputFile)
         console.log(`🔥 ${profileType} flamegraph generated: ${outputFile}`)
         console.log(`🔥 Open file://${path.resolve(outputFile)} in your browser to view the flamegraph`)
+
+        // Generate markdown
+        console.log(`🔥 Generating ${profileType} markdown analysis...`)
+        try {
+          await generateMarkdown(pprofFile, mdOutputFile, { format: mdFormat })
+          console.log(`🔥 ${profileType} markdown generated: ${mdOutputFile}`)
+        } catch (error) {
+          console.error(`Warning: Failed to generate ${profileType} markdown:`, error.message)
+        }
         break
       }
 

lib/index.js

@@ -24,7 +24,8 @@ function startProfiling (script, args = [], options = {}) {
     ...process.env,
     ...options.env,
     FLAME_AUTO_START: options.autoStart ? 'true' : 'false',
-    FLAME_DELAY: options.delay ?? 'until-started'
+    FLAME_DELAY: options.delay ?? 'until-started',
+    FLAME_MD_FORMAT: options.mdFormat || 'summary'
   }
 
   // Add sourcemap configuration if provided
@@ -142,8 +143,27 @@ async function generateFlamegraph (pprofPath, outputPath) {
   })
 }
 
+/**
+ * Generate LLM-friendly markdown analysis from a pprof file
+ * @param {string} pprofPath - Path to the pprof file
+ * @param {string} outputPath - Path to write the markdown file
+ * @param {object} options - Options for markdown generation
+ * @param {string} options.format - Markdown format: 'summary' (default), 'detailed', or 'adaptive'
+ * @returns {Promise<object>} Result with outputPath
+ */
+async function generateMarkdown (pprofPath, outputPath, options = {}) {
+  const { convert } = await import('pprof-to-md')
+  const markdown = convert(pprofPath, {
+    format: options.format || 'summary',
+    profileName: path.basename(pprofPath)
+  })
+  fs.writeFileSync(outputPath, markdown)
+  return { outputPath }
+}
+
 module.exports = {
   startProfiling,
   parseProfile,
-  generateFlamegraph
+  generateFlamegraph,
+  generateMarkdown
 }

package.json

@@ -40,6 +40,7 @@
     "@datadog/pprof": "^5.9.0",
     "fastify": "^5.5.0",
     "pprof-format": "^2.2.1",
+    "pprof-to-md": "^0.1.0",
     "react-pprof": "^1.4.0"
   },
   "devDependencies": {
@@ -59,7 +60,7 @@
     "neostandard": "^0.12.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.6.0"
   },
   "pre-commit": [
     "lint",

preload.js

@@ -11,6 +11,7 @@ let isCpuProfilerRunning = false
 let isHeapProfilerRunning = false
 let sourceMapper = null
 const autoStart = process.env.FLAME_AUTO_START === 'true'
+const mdFormat = process.env.FLAME_MD_FORMAT || 'summary'
 
 // Initialize sourcemap support if enabled
 const sourcemapDirs = process.env.FLAME_SOURCEMAP_DIRS
@@ -215,6 +216,16 @@ function generateFlamegraph (pprofPath, outputPath) {
   })
 }
 
+async function generateMarkdown (pprofPath, outputPath, format = 'summary') {
+  const { convert } = await import('pprof-to-md')
+  const markdown = convert(pprofPath, {
+    format,
+    profileName: path.basename(pprofPath)
+  })
+  fs.writeFileSync(outputPath, markdown)
+  return { outputPath }
+}
+
 function stopProfilerQuick () {
   if (!isCpuProfilerRunning && !isHeapProfilerRunning) {
     return null
@@ -293,6 +304,16 @@ async function stopProfilerAndSave (generateHtml = false) {
         } catch (error) {
           console.error('Warning: Failed to generate CPU flamegraph:', error.message)
         }
+
+        // Generate markdown analysis
+        const mdFilename = cpuFilename.replace('.pb', '.md')
+        console.log('🔥 Generating CPU markdown analysis...')
+        try {
+          await generateMarkdown(cpuFilename, mdFilename, mdFormat)
+          console.log(`🔥 CPU markdown generated: ${mdFilename}`)
+        } catch (error) {
+          console.error('Warning: Failed to generate CPU markdown:', error.message)
+        }
       }
     }
 
@@ -319,6 +340,16 @@ async function stopProfilerAndSave (generateHtml = false) {
         } catch (error) {
           console.error('Warning: Failed to generate heap flamegraph:', error.message)
         }
+
+        // Generate markdown analysis
+        const mdFilename = heapFilename.replace('.pb', '.md')
+        console.log('🔥 Generating heap markdown analysis...')
+        try {
+          await generateMarkdown(heapFilename, mdFilename, mdFormat)
+          console.log(`🔥 Heap markdown generated: ${mdFilename}`)
+        } catch (error) {
+          console.error('Warning: Failed to generate heap markdown:', error.message)
+        }
       }
     }
 
@@ -350,6 +381,17 @@ function generateHtmlAsync (filenames) {
       .catch(error => {
         console.error(`Warning: Failed to generate ${profileType} flamegraph:`, error.message)
       })
+
+    // Generate markdown analysis
+    const mdFilename = filename.replace('.pb', '.md')
+    console.log(`🔥 Generating ${profileType} markdown analysis...`)
+    generateMarkdown(filename, mdFilename, mdFormat)
+      .then(() => {
+        console.log(`🔥 ${profileType} markdown generated: ${mdFilename}`)
+      })
+      .catch(error => {
+        console.error(`Warning: Failed to generate ${profileType} markdown:`, error.message)
+      })
   })
 }