TracePerf

Try it in 30 seconds, without changing your code

npm install traceperf
node --require traceperf/auto server.js

Every request becomes a call tree with its HTTP calls and database queries nested inside. Stop the server and you get per-route statistics and an explanation of what made requests slow:

└─ GET /users/:id: 84.112 ms
  ├─ pg SELECT users: 12.331 ms
  └─ fetch GET billing.internal/invoices: 70.950 ms

🔥 renderPdf ran 30 ms of synchronous code, blocking everything else in the process for that long
⏳ GET /users/:id waited ~60 ms while renderPdf in POST /export blocked the event loop
⇉ GET /dashboard awaited 3 calls one after another; Promise.all could save up to ~47 ms
🔁 GET /orders called pg SELECT prices 10 times; batching them into one call may help (N+1 pattern)

Features

Getting Started

Installation

npm install traceperf

Basic Usage

const { createTracePerf, TrackingMode } = require('traceperf');

// Create a tracker with default settings
const traceperf = createTracePerf();

// Track a synchronous function
const result = traceperf.track(() => {
  // Your function logic here
  return 'result';
}, { label: 'myFunction' });

// Track an asynchronous function
async function main() {
  const result = await traceperf.track(async () => {
    // Your async function logic here
    return 'async result';
  }, { label: 'asyncFunction' });
}

main();

Tracking Modes

const { createTracePerf, TrackingMode } = require('traceperf');

// Performance mode - minimal overhead for production
const performanceTracker = createTracePerf({
  trackingMode: TrackingMode.PERFORMANCE,
  silent: true,
  threshold: 100, // only track functions that take more than 100ms
  sampleRate: 0.1 // only track 10% of function calls
});

// Detailed mode - maximum information for development
const devTracker = createTracePerf({
  trackingMode: TrackingMode.DETAILED,
  trackMemory: true,
  enableNestedTracking: true
});

Memory Tracking

const { createTracePerf } = require('traceperf');

// Enable memory tracking
const tracker = createTracePerf({ trackMemory: true });

// Track memory usage for a memory-intensive operation
const result = tracker.track(() => {
  // Memory intensive operations
  const largeArray = new Array(1000000).fill(Math.random());
  return processArray(largeArray);
}, { label: 'memoryIntensiveOperation' });

Output:

└─ memoryIntensiveOperation: 25.005 ms 📊 +15335.69 KB

Nested Function Tracking

const { createTracePerf } = require('traceperf');
const traceperf = createTracePerf({ enableNestedTracking: true });

// Define some functions (call the *tracked* versions so they nest)
function processData(data) {
  return trackedTransformData(data);
}

function transformData(data) {
  return data.map(x => x * 2);
}

// Create trackable versions
const trackedProcessData = traceperf.createTrackable(processData, { 
  label: 'processData' 
});

const trackedTransformData = traceperf.createTrackable(transformData, { 
  label: 'transformData' 
});

// Execute with tracking
traceperf.track(() => {
  const data = [1, 2, 3, 4, 5];
  return trackedProcessData(data);
}, { label: 'mainOperation' });

Output:

└─ mainOperation: 0.580 ms 📊 +3.12 KB
  └─ processData: 0.330 ms 📊 +1.40 KB
    └─ transformData: 0.120 ms 📊 +0.75 KB

Browser Support

<script src="https://unpkg.com/traceperf/dist/traceperf.browser.min.js"></script>
<script>
  const { createTracePerf, BrowserLogger } = TracePerf;
  
  const browserTracker = createTracePerf({
    logger: new BrowserLogger({
      silent: false,
      trackMemory: true
    })
  });
  
  // Track a DOM operation
  browserTracker.track(() => {
    document.getElementById('output').textContent = 'Updated';
  }, { label: 'updateDOM' });

  // Track async operations
  await browserTracker.track(async () => {
    const response = await fetch('/api/data');
    return response.json();
  }, { label: 'fetchData' });

  // Create trackable functions
  const trackedFn = browserTracker.createTrackable(() => {
    // Function implementation
  }, { label: 'trackedBrowserFn' });
</script>

ES Modules Usage

import { createTracePerf, BrowserLogger } from 'traceperf/browser';

const browserTracker = createTracePerf({
  logger: new BrowserLogger({
    silent: false,
    trackMemory: true
  })
});

// Use the same API as in Node.js
browserTracker.track(() => {
  // Your browser-side code
});

Documentation

For complete documentation and examples, please visit the GitHub repository.

• Running traceperf in production: safe settings, measured costs, rollout
• Compared with clinic.js, --cpu-prof, OpenTelemetry and APM agents
• Overhead benchmarks
• API reference

View examples at examples directory.