@platformatic/wattpm-pprof-capture 3.13.1 → 3.14.0

package/eslint.config.js

@@ -1,3 +1,5 @@
 import neostandard from 'neostandard'
 
-export default neostandard({})
+export default neostandard({
+  ignores: ['test/fixtures/**/dist/**']
+})

package/index.js

@@ -1,9 +1,63 @@
-import { time, heap } from '@datadog/pprof'
+import { time, heap, SourceMapper } from '@datadog/pprof'
 import { performance } from 'node:perf_hooks'
+import { workerData } from 'node:worker_threads'
 import { NoProfileAvailableError, NotEnoughELUError, ProfilingAlreadyStartedError, ProfilingNotStartedError } from './lib/errors.js'
 
 const kITC = Symbol.for('plt.runtime.itc')
 
+// SourceMapper for resolving transpiled code locations back to original source
+let sourceMapper = null
+let sourceMapperInitialized = false
+
+/**
+ * Wrapper around SourceMapper that fixes Windows path normalization issues.
+ *
+ * On Windows, V8 profiler returns paths like `file:///D:/path/to/file.js`.
+ * The @datadog/pprof library removes `file://` leaving `/D:/path/to/file.js`,
+ * but SourceMapper stores paths as `D:\path\to\file.js`.
+ *
+ * This wrapper normalizes Windows paths to match the internal format.
+ */
+class SourceMapperWrapper {
+  constructor (innerMapper) {
+    this.innerMapper = innerMapper
+    this.debug = innerMapper.debug
+  }
+
+  /**
+   * Normalize Windows-style paths from V8 profiler to match SourceMapper format.
+   * Handles paths like `/D:/path/to/file.js` -> `D:\path\to\file.js`
+   */
+  normalizePath (filePath) {
+    if (process.platform !== 'win32') {
+      return filePath
+    }
+
+    // Handle paths like /D:/path/to/file -> D:\path\to\file
+    // This happens because pprof removes 'file://' from 'file:///D:/path/to/file'
+    if (filePath.startsWith('/') && filePath.length > 2 && filePath[2] === ':') {
+      // Remove leading slash and convert forward slashes to backslashes
+      return filePath.slice(1).replace(/\//g, '\\')
+    }
+
+    // Also convert any forward slashes to backslashes on Windows
+    return filePath.replace(/\//g, '\\')
+  }
+
+  hasMappingInfo (inputPath) {
+    const normalized = this.normalizePath(inputPath)
+    return this.innerMapper.hasMappingInfo(normalized)
+  }
+
+  mappingInfo (location) {
+    const normalized = {
+      ...location,
+      file: this.normalizePath(location.file)
+    }
+    return this.innerMapper.mappingInfo(normalized)
+  }
+}
+
 // Track ELU globally (shared across all profiler types)
 let lastELU = null
 let previousELU = performance.eventLoopUtilization()
@@ -30,7 +84,8 @@ const profilingState = {
     eluThreshold: null,
     options: null,
     profilerStarted: false,
-    clearProfileTimeout: null
+    clearProfileTimeout: null,
+    sourceMapsEnabled: false
   },
   heap: {
     isCapturing: false,
@@ -40,7 +95,8 @@ const profilingState = {
     eluThreshold: null,
     options: null,
     profilerStarted: false,
-    clearProfileTimeout: null
+    clearProfileTimeout: null,
+    sourceMapsEnabled: false
   }
 }
 
@@ -99,7 +155,9 @@ function unscheduleProfileRotation (state) {
 }
 
 function startProfiler (type, state, options) {
-  if (state.profilerStarted) return
+  if (state.profilerStarted) {
+    return
+  }
 
   const profiler = getProfiler(type)
 
@@ -115,8 +173,18 @@ function startProfiler (type, state, options) {
     profiler.start(intervalBytes, stackDepth)
   } else {
     // CPU time profiler takes options object
-    options.intervalMicros ??= 33333
-    profiler.start(options)
+    const profilerOptions = { ...options }
+    profilerOptions.intervalMicros ??= 33333
+
+    // Enable line numbers to get file information in the profile
+    profilerOptions.lineNumbers = true
+
+    // Add sourceMapper if enabled and available for transpiled source resolution
+    if (state.sourceMapsEnabled && sourceMapper) {
+      profilerOptions.sourceMapper = sourceMapper
+    }
+
+    profiler.start(profilerOptions)
   }
 }
 
@@ -131,10 +199,12 @@ function stopProfiler (type, state) {
 
   if (type === 'heap') {
     // Get the profile before stopping
-    state.latestProfile = profiler.profile()
+    // Pass sourceMapper if enabled and available for transpiled source resolution
+    state.latestProfile = (state.sourceMapsEnabled && sourceMapper) ? profiler.profile(undefined, sourceMapper) : profiler.profile()
     profiler.stop()
   } else {
     // CPU time profiler returns the profile when stopping
+    // sourceMapper was already passed to start(), so it's applied automatically
     state.latestProfile = profiler.stop()
   }
 }
@@ -203,13 +273,62 @@ function startIfOverThreshold (type, state, wasRunning = state.profilerStarted)
   }
 }
 
-export function startProfiling (options = {}) {
+async function initializeSourceMapper () {
+  if (sourceMapperInitialized) {
+    return
+  }
+
+  sourceMapperInitialized = true
+
+  try {
+    // Get the application directory from workerData
+    const appPath = workerData?.applicationConfig?.path
+    if (!appPath) {
+      if (globalThis.platformatic?.logger) {
+        globalThis.platformatic.logger.debug('No application path available for sourcemap resolution')
+      }
+      return
+    }
+
+    // Create SourceMapper to search for .map files in the app directory
+    // Note: SourceMapper searches recursively for files matching /\.[cm]?js\.map$/
+    const debug = process.env.PLT_PPROF_SOURCEMAP_DEBUG === 'true'
+    const innerMapper = await SourceMapper.create([appPath], debug)
+
+    // Wrap the SourceMapper to fix Windows path normalization
+    sourceMapper = new SourceMapperWrapper(innerMapper)
+
+    if (globalThis.platformatic?.logger) {
+      const hasMappings = sourceMapper && typeof sourceMapper.hasMappingInfo === 'function'
+      globalThis.platformatic.logger.info(
+        { appPath, hasSourceMapper: !!sourceMapper, hasMappingInfo: hasMappings },
+        'SourceMapper initialized for profiling'
+      )
+    }
+  } catch (err) {
+    if (globalThis.platformatic?.logger) {
+      globalThis.platformatic.logger.warn(
+        { err: err.message, stack: err.stack },
+        'Failed to initialize SourceMapper'
+      )
+    }
+  }
+}
+
+export async function startProfiling (options = {}) {
   const type = options.type || 'cpu'
   const state = profilingState[type]
 
   if (state.isCapturing) {
     throw new ProfilingAlreadyStartedError()
   }
+
+  // Initialize source mapper if source maps are requested
+  state.sourceMapsEnabled = options.sourceMaps === true
+  if (state.sourceMapsEnabled) {
+    await initializeSourceMapper()
+  }
+
   state.isCapturing = true
   state.options = options
   state.eluThreshold = options.eluThreshold
@@ -233,6 +352,7 @@ export function stopProfiling (options = {}) {
   state.eluThreshold = null
   state.durationMillis = null
   state.options = null
+  state.sourceMapsEnabled = false
 
   // Return the latest profile if available, otherwise return an empty profile
   // (e.g., when profiler never started due to ELU threshold not being exceeded)
@@ -256,7 +376,8 @@ export function getLastProfile (options = {}) {
   // For CPU profiler, use the cached profile if available
   if (type === 'heap' && state.profilerStarted) {
     const profiler = getProfiler(type)
-    state.latestProfile = profiler.profile()
+    // Get heap profile with sourceMapper if enabled and available
+    state.latestProfile = (state.sourceMapsEnabled && sourceMapper) ? profiler.profile(undefined, sourceMapper) : profiler.profile()
   }
 
   // Check if we have a profile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/wattpm-pprof-capture",
-  "version": "3.13.1",
+  "version": "3.14.0",
   "description": "pprof profiling capture for wattpm",
   "main": "index.js",
   "type": "module",
@@ -20,11 +20,14 @@
     "undici": "^6.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "atomic-sleep": "^1.0.0",
     "eslint": "9",
     "neostandard": "^0.12.0",
-    "@platformatic/foundation": "3.13.1",
-    "@platformatic/service": "3.13.1"
+    "pprof-format": "^2.1.0",
+    "typescript": "^5.0.0",
+    "@platformatic/foundation": "3.14.0",
+    "@platformatic/service": "3.14.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/test/fixtures/minimal-sourcemap-worker.js

@@ -0,0 +1,38 @@
+import { parentPort } from 'node:worker_threads'
+import { time, SourceMapper } from '@datadog/pprof'
+import { resolve } from 'node:path'
+
+process.on('uncaughtException', (err) => {
+  parentPort.postMessage({ success: false, error: err.message })
+  process.exit(1)
+})
+
+process.on('unhandledRejection', (reason) => {
+  parentPort.postMessage({ success: false, error: String(reason) })
+  process.exit(1)
+})
+
+async function test () {
+  try {
+    const serviceDir = resolve(import.meta.dirname, 'sourcemap-test/service')
+    const sourceMapper = await SourceMapper.create([serviceDir], false)
+
+    time.start({
+      intervalMicros: 33333,
+      lineNumbers: true,
+      sourceMapper
+    })
+
+    await new Promise(resolve => setTimeout(resolve, 2000))
+
+    time.stop()
+
+    parentPort.postMessage({ success: true })
+    process.exit(0)
+  } catch (err) {
+    parentPort.postMessage({ success: false, error: err.message })
+    process.exit(1)
+  }
+}
+
+test()

package/test/fixtures/sourcemap-test/platformatic.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://schemas.platformatic.dev/@platformatic/runtime/2.0.0.json",
+  "entrypoint": "service",
+  "preload": "../../../index.js",
+  "autoload": {
+    "path": "./"
+  },
+  "server": {
+    "hostname": "127.0.0.1",
+    "port": 0
+  },
+  "logger": {
+    "level": "error"
+  }
+}

package/test/fixtures/sourcemap-test/service/platformatic.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://schemas.platformatic.dev/@platformatic/service/2.0.0.json",
+  "server": {
+    "logger": {
+      "level": "warn"
+    }
+  },
+  "plugins": {
+    "paths": [{
+      "path": "dist/plugin.js",
+      "encapsulate": false
+    }]
+  }
+}

package/test/fixtures/sourcemap-test/service/plugin.ts

@@ -0,0 +1,73 @@
+import { FastifyInstance } from 'fastify'
+
+// A function with a distinctive name that we can find in the profile
+// This function allocates significant memory to ensure heap profiler captures samples
+async function myTypeScriptFunction(value: number): Promise<number> {
+  let result = 0
+  const allocations: Array<{ data: number[], metadata: object }> = []
+
+  // Allocate memory in chunks larger than heap profiler sampling interval (512KB)
+  // Each iteration allocates ~1MB to ensure we trigger heap profiler sampling
+  for (let i = 0; i < 10; i++) {
+    // Allocate a large array (~800KB of numbers)
+    const largeArray = new Array(100000)
+    for (let j = 0; j < largeArray.length; j++) {
+      largeArray[j] = Math.sqrt(j * value)
+      result += largeArray[j]
+    }
+
+    // Allocate objects with metadata
+    const metadata = {
+      index: i,
+      timestamp: Date.now(),
+      value,
+      description: 'Memory allocation for heap profiling test'.repeat(10)
+    }
+
+    allocations.push({ data: largeArray, metadata })
+
+    // Small delay to allow heap profiler to sample
+    await new Promise(resolve => setTimeout(resolve, 10))
+  }
+
+  // Keep allocations alive until we're done computing
+  return result + allocations.length
+}
+
+export default async function (app: FastifyInstance) {
+  app.get('/', async () => {
+    return { message: 'Hello from TypeScript' }
+  })
+
+  app.get('/compute', async () => {
+    const result = await myTypeScriptFunction(42)
+    return { result }
+  })
+
+  app.get('/diagnostic', async () => {
+    const fs = await import('node:fs/promises')
+    const path = await import('node:path')
+    const url = await import('node:url')
+    const serviceDir = path.dirname(url.fileURLToPath(import.meta.url))
+    const pluginJsPath = path.join(serviceDir, 'plugin.js')
+    const pluginMapPath = path.join(serviceDir, 'plugin.js.map')
+
+    const diagnostics = {
+      serviceDir,
+      pluginJsExists: false,
+      pluginMapExists: false
+    }
+
+    try {
+      await fs.access(pluginJsPath)
+      diagnostics.pluginJsExists = true
+    } catch {}
+
+    try {
+      await fs.access(pluginMapPath)
+      diagnostics.pluginMapExists = true
+    } catch {}
+
+    return diagnostics
+  })
+}

package/test/fixtures/sourcemap-test/service/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./",
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": false
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/test/minimal-sourcemap.test.js

@@ -0,0 +1,49 @@
+import { test } from 'node:test'
+import { Worker } from 'node:worker_threads'
+import { resolve } from 'node:path'
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execAsync = promisify(exec)
+
+test.before(async () => {
+  const serviceDir = resolve(import.meta.dirname, 'fixtures/sourcemap-test/service')
+  try {
+    await execAsync('npx tsc', { cwd: serviceDir, timeout: 30000 })
+  } catch (err) {
+    throw new Error(`Failed to build TypeScript service: ${err.message}`)
+  }
+})
+
+// Test if SourceMapper works in a plain worker thread on Windows
+test('minimal SourceMapper test in worker thread', async (t) => {
+  await new Promise((resolve, reject) => {
+    const worker = new Worker(new URL('./fixtures/minimal-sourcemap-worker.js', import.meta.url))
+
+    const timeout = setTimeout(() => {
+      worker.terminate()
+      reject(new Error('Worker timed out after 10 seconds'))
+    }, 10000)
+
+    worker.on('message', (msg) => {
+      clearTimeout(timeout)
+      if (msg.success) {
+        resolve()
+      } else {
+        reject(new Error(`Worker reported error: ${msg.error}`))
+      }
+    })
+
+    worker.on('error', (err) => {
+      clearTimeout(timeout)
+      reject(new Error(`Worker error: ${err.message}`))
+    })
+
+    worker.on('exit', (code) => {
+      clearTimeout(timeout)
+      if (code !== 0) {
+        reject(new Error(`Worker exited with code ${code}`))
+      }
+    })
+  })
+})

package/test/sourcemap.test.js

@@ -0,0 +1,206 @@
+import assert from 'node:assert'
+import { resolve } from 'node:path'
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
+import test from 'node:test'
+import { request } from 'undici'
+import { Profile } from 'pprof-format'
+import { createRuntime } from '../../runtime/test/helpers.js'
+
+const execAsync = promisify(exec)
+
+// Helper to wait for a condition to be true
+async function waitForCondition (checkFn, timeoutMs = 5000, pollMs = 100) {
+  const startTime = Date.now()
+  while (Date.now() - startTime < timeoutMs) {
+    if (await checkFn()) {
+      return true
+    }
+    await new Promise(resolve => setTimeout(resolve, pollMs))
+  }
+  throw new Error('Timeout waiting for condition')
+}
+
+// Helper to verify TypeScript files are present in profile
+function verifyTypeScriptFilesInProfile (profile) {
+  let foundTypeScriptFile = false
+  const allFilenames = new Set()
+
+  for (const func of profile.function) {
+    const id = Number(func.filename)
+    const filename = profile.stringTable.strings[id] || ''
+    if (filename) {
+      allFilenames.add(filename)
+      if (filename.endsWith('.ts')) {
+        foundTypeScriptFile = true
+      }
+    }
+  }
+
+  const filenameList = Array.from(allFilenames).sort()
+  assert.ok(
+    foundTypeScriptFile,
+    `should contain .ts filenames. Found ${allFilenames.size} unique filenames:\n${filenameList.join('\n')}`
+  )
+}
+
+// Helper to decode and validate a profile
+function decodeAndValidateProfile (encodedProfile, checkLocations) {
+  assert.ok(encodedProfile instanceof Uint8Array, 'should be Uint8Array')
+  assert.ok(encodedProfile.length > 0, 'should have content')
+
+  const profile = Profile.decode(encodedProfile)
+  assert.ok(profile.function, 'should have functions')
+  assert.ok(profile.function.length > 0, 'should have at least one function')
+
+  if (checkLocations) {
+    assert.ok(profile.location, 'should have locations')
+    assert.ok(profile.location.length > 0, 'should have at least one location')
+  }
+
+  return profile
+}
+
+// Build TypeScript service once before all tests
+test.before(async () => {
+  const serviceDir = resolve(import.meta.dirname, 'fixtures/sourcemap-test/service')
+
+  // Build the TypeScript (dependencies are in parent package devDependencies)
+  try {
+    await execAsync('npx tsc', { cwd: serviceDir, timeout: 30000 })
+  } catch (err) {
+    throw new Error(`Failed to build TypeScript service: ${err.message}\nStdout: ${err.stdout}\nStderr: ${err.stderr}`)
+  }
+
+  // Verify build artifacts exist
+  const { access } = await import('node:fs/promises')
+  const pluginPath = resolve(serviceDir, 'dist/plugin.js')
+  const mapPath = resolve(serviceDir, 'dist/plugin.js.map')
+  try {
+    await access(pluginPath)
+    await access(mapPath)
+  } catch (err) {
+    throw new Error(`Build artifacts not found: ${err.message}. Plugin: ${pluginPath}, Map: ${mapPath}`)
+  }
+})
+
+async function createApp (t) {
+  const configFile = resolve(import.meta.dirname, 'fixtures/sourcemap-test/platformatic.json')
+
+  // Ensure tmp directory exists
+  const { mkdir } = await import('node:fs/promises')
+  const tmpDir = resolve(import.meta.dirname, '../../tmp')
+  await mkdir(tmpDir, { recursive: true })
+
+  const logsPath = resolve(tmpDir, `sourcemap-test-${Date.now()}.log`)
+
+  const app = await createRuntime(configFile, null, { logsPath })
+
+  t.after(async () => {
+    await app.close()
+  })
+
+  const url = await app.start()
+
+  // Wait for services and handlers to register
+  await new Promise(resolve => setTimeout(resolve, 200))
+
+  return { app, url }
+}
+
+test('sourcemaps should be initialized and profiling should work with TypeScript', async t => {
+  const { app, url } = await createApp(t)
+
+  // Verify service is running
+  const res = await request(`${url}/`)
+  const json = await res.body.json()
+  assert.strictEqual(res.statusCode, 200)
+  assert.strictEqual(json.message, 'Hello from TypeScript')
+
+  // Verify sourcemap files exist in service directory
+  const diagRes = await request(`${url}/diagnostic`, { headersTimeout: 10000, bodyTimeout: 10000 })
+  const diag = await diagRes.body.json()
+  assert.strictEqual(diag.pluginMapExists, true, `Sourcemap file should exist at ${diag.serviceDir}/plugin.js.map`)
+
+  // Start profiling with sufficient duration to ensure we capture samples
+  // Enable source maps to resolve TypeScript locations
+  await app.sendCommandToApplication('service', 'startProfiling', { durationMillis: 5000, sourceMaps: true })
+
+  // Wait for profiler to actually start
+  await waitForCondition(async () => {
+    const state = await app.sendCommandToApplication('service', 'getProfilingState')
+    return state.isProfilerRunning
+  }, 2000)
+
+  // Make requests spread over time to ensure continuous CPU activity during profiling
+  // Use shorter interval and add timeout to prevent hanging
+  let consecutiveFailures = 0
+  let intervalStopped = false
+  const requestInterval = setInterval(() => {
+    if (intervalStopped) return
+
+    request(`${url}/compute`, { headersTimeout: 30000, bodyTimeout: 30000 })
+      .then(() => {
+        consecutiveFailures = 0
+      })
+      .catch((err) => {
+        consecutiveFailures++
+
+        // If we get 3 consecutive connection failures, the service likely crashed
+        if (consecutiveFailures >= 3 && (err.message.includes('ECONNREFUSED') || err.message.includes('ECONNRESET'))) {
+          intervalStopped = true
+          clearInterval(requestInterval)
+          throw new Error(`Service crashed - ${consecutiveFailures} consecutive connection failures: ${err.message}`)
+        }
+      })
+  }, 300)
+
+  // Wait for profile to be captured
+  await waitForCondition(async () => {
+    const state = await app.sendCommandToApplication('service', 'getProfilingState')
+    return state.hasProfile
+  }, 10000)
+
+  clearInterval(requestInterval)
+
+  // Get the profile - this should succeed with SourceMapper initialized
+  const encodedProfile = await app.sendCommandToApplication('service', 'getLastProfile')
+  const profile = decodeAndValidateProfile(encodedProfile, true)
+
+  // Verify sourcemaps are working by checking for .ts file extensions
+  verifyTypeScriptFilesInProfile(profile)
+
+  await app.sendCommandToApplication('service', 'stopProfiling')
+})
+
+test('sourcemaps should work with heap profiling', async t => {
+  const { app, url } = await createApp(t)
+
+  // Start heap profiling with source maps enabled
+  await app.sendCommandToApplication('service', 'startProfiling', { type: 'heap', sourceMaps: true })
+
+  // Wait for heap profiler to actually start
+  await waitForCondition(async () => {
+    const state = await app.sendCommandToApplication('service', 'getProfilingState', { type: 'heap' })
+    return state.isProfilerRunning
+  }, 2000)
+
+  // Make many requests to ensure enough allocations for heap profiler to capture
+  // Heap profiler samples at 512KB intervals by default
+  // Each request allocates ~10MB of memory which should trigger multiple samples
+  for (let i = 0; i < 50; i++) {
+    await request(`${url}/compute`, { headersTimeout: 30000, bodyTimeout: 30000 })
+  }
+
+  // Wait a bit to ensure heap samples are taken
+  await new Promise(resolve => setTimeout(resolve, 1000))
+
+  // Get the heap profile - this should succeed with SourceMapper initialized
+  const encodedProfile = await app.sendCommandToApplication('service', 'getLastProfile', { type: 'heap' })
+  const profile = decodeAndValidateProfile(encodedProfile)
+
+  // Verify sourcemaps work for heap profiling
+  verifyTypeScriptFilesInProfile(profile)
+
+  await app.sendCommandToApplication('service', 'stopProfiling', { type: 'heap' })
+})