TracePerf

Advanced performance tracking and execution monitoring for Node.js applications.

Features

• High-Performance Execution Monitoring: Track function execution time with minimal overhead
• Memory Usage Tracking: Monitor memory consumption of your functions and identify memory leaks
• Flexible Tracking Modes: Choose between performance, balanced, and detailed tracking based on your needs
• Execution Flow Visualization: Visualize execution flows with intelligent formatting
• Nested Function Tracking: Track function calls within other functions to understand complex flows
• Customizable Threshold Detection: Focus on functions that exceed specific execution time thresholds
• Sampling Control: Adjust sampling rates to minimize performance impact in production
• Universal Module Compatibility: Works with both CommonJS and ESM environments

Installation

npm install traceperf

Quick Start

const traceperf = require('traceperf');

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

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

Tracking Modes

TracePerf provides different tracking modes to balance performance with detail:

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

// Create a custom instance with performance-focused tracking
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
});

// Create a custom instance with detailed tracking for development
const devTracker = createTracePerf({
  trackingMode: TrackingMode.DETAILED,
  trackMemory: true,
  enableNestedTracking: true
});

Tracking Individual Functions

// Track a single function execution
const result = traceperf.track(() => {
  // Function body
  return someValue;
}, {
  label: 'functionName',
  threshold: 50, // ms
  trackMemory: true
});

// Create a trackable version of an existing function
const myFunction = (a, b) => a + b;
const trackedFunction = traceperf.createTrackable(myFunction, { 
  label: 'addition' 
});

// Now use it normally
const sum = trackedFunction(5, 3); // will be tracked

Tracking Methods in a Module

const userService = {
  getUser: async (id) => { /* implementation */ },
  updateUser: async (id, data) => { /* implementation */ },
  deleteUser: async (id) => { /* implementation */ }
};

// Register all methods for tracking
const trackedUserService = traceperf.registerModule(userService);

// Now all method calls will be tracked
const user = await trackedUserService.getUser(123);

Advanced Configuration

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

const customTracker = createTracePerf({
  // Tracking mode affects detail level and performance impact
  trackingMode: TrackingMode.BALANCED,
  
  // Enable or disable performance statistics in console
  silent: false,
  
  // Track memory usage (slight performance impact)
  trackMemory: true,
  
  // Enable tracking of nested function calls
  enableNestedTracking: true,
  
  // Minimum execution time to track (milliseconds)
  threshold: 50,
  
  // Percentage of function calls to track (0.0 to 1.0)
  sampleRate: 1.0
});

Browser Support

TracePerf provides a fully synchronized browser implementation that matches the Node.js API:

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

// Create a browser-optimized instance
const browserTracker = createTracePerf({
  logger: new BrowserLogger({
    silent: false,
    trackMemory: true
  })
});

// Track function execution
browserTracker.track(() => {
  // Your browser-side code
}, { label: 'browserOperation' });

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

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

You can also use it via script tag:

<script src="dist/traceperf.browser.js"></script>
<script>
  const { createTracePerf, BrowserLogger } = TracePerf;
  
  const browserTracker = createTracePerf({
    logger: new BrowserLogger({
      silent: false,
      trackMemory: true
    })
  });
  
  // Use the same API as in Node.js
  browserTracker.track(() => {
    // DOM operations or other browser-side logic
  }, { label: 'domOperation' });
</script>

Synchronized Features

TracePerf now provides a consistent API across Node.js and browser environments:

• Unified Tracking API: The same tracking methods work identically in both environments
• Consistent Configuration: Logger and tracker options are synchronized
• Memory Tracking: Both environments support memory usage tracking
• Performance Optimization: Browser-specific optimizations while maintaining API compatibility
• Execution Flow: Track complex execution flows consistently across environments

Example of cross-environment usage:

// Node.js
const { createTracePerf } = require('traceperf');
const nodeTracker = createTracePerf();

// Browser
import { createTracePerf } from 'traceperf/browser';
const browserTracker = createTracePerf();

// Both environments support the same API
async function trackOperation(tracker) {
  return await tracker.track(async () => {
    const result = await someAsyncOperation();
    return processResult(result);
  }, { 
    label: 'mainOperation',
    trackMemory: true
  });
}

Examples

TracePerf includes several example files to help you get started:

• examples/optimized-tracking-example.js: Demonstrates various ways to use the optimized tracking implementation
• examples/browser-example.js: Shows how to use TracePerf in browser environments

Tracking an Async Function

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

async function fetchData(url) {
  return traceperf.track(async () => {
    const response = await fetch(url);
    return response.json();
  }, { 
    label: 'fetchData',
    trackMemory: true
  });
}

Tracking Nested Functions

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

async function processData() {
  return await traceperf.track(async () => {
    // This function call will be automatically tracked as a child
    const data = await fetchData();
    return transformData(data);
  }, { 
    label: 'processData'
  });
}

async function fetchData() {
  return await traceperf.track(async () => {
    // Implementation
  }, { label: 'fetchData' });
}

function transformData(data) {
  return traceperf.track(() => {
    // Implementation
  }, { label: 'transformData' });
}

Optimizing for Production

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

// Development environment
const devTracker = createTracePerf({
  trackingMode: TrackingMode.DETAILED,
  silent: false,
  trackMemory: true,
  threshold: 0 // track everything
});

// Production environment
const prodTracker = createTracePerf({
  trackingMode: TrackingMode.PERFORMANCE,
  silent: true, // don't log to console
  trackMemory: false, // minimize overhead
  threshold: 100, // only track slow functions
  sampleRate: 0.01 // track only 1% of function calls
});

// Use based on environment
const traceperf = process.env.NODE_ENV === 'production' ? prodTracker : devTracker;

Browser Usage

To use TracePerf in the browser:

<script src="dist/traceperf.browser.js"></script>
<script>
  const { createTracePerf, TrackingMode } = TracePerf;
  
  const browserTracker = createTracePerf({
    trackingMode: TrackingMode.BALANCED,
    trackMemory: true
  });
  
  // Now use it to track your functions
  browserTracker.track(() => {
    // DOM operations or other browser-side logic
  }, { label: 'domOperation' });
</script>

Or with ES modules:

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

const browserTracker = createTracePerf({
  trackingMode: TrackingMode.BALANCED
});

// Track a DOM operation
browserTracker.track(() => {
  document.getElementById('output').textContent = 'Updated';
}, { label: 'updateDOM' });

Advanced Tracking Features

Tracking with Different Modes

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

// Performance mode - minimal overhead
const performanceTracker = createTracePerf({
  trackingMode: TrackingMode.PERFORMANCE
});

// Balanced mode - moderate detail with reasonable overhead
const balancedTracker = createTracePerf({
  trackingMode: TrackingMode.BALANCED
});

// Detailed mode - maximum information
const detailedTracker = createTracePerf({
  trackingMode: TrackingMode.DETAILED
});

Using Thresholds to Filter Results

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

// Only log functions that take more than 50ms
tracker.track(slowFunction, { threshold: 50 });

// Different thresholds for different functions
tracker.track(criticalFunction, { threshold: 10 }); // Low threshold for critical paths
tracker.track(backgroundTask, { threshold: 200 }); // Higher threshold for background tasks