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

consttraceperf=require('traceperf');// Track a synchronous functionconstresult=traceperf.track(()=>{// Your code herereturn'result';},{label: 'myFunction'});// Track an asynchronous functionasyncfunctionmain(){constresult=awaittraceperf.track(async()=>{// Your async code herereturn'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 trackingconstperformanceTracker=createTracePerf({trackingMode: TrackingMode.PERFORMANCE,silent: true,threshold: 100,// only track functions that take more than 100mssampleRate: 0.1// only track 10% of function calls});// Create a custom instance with detailed tracking for developmentconstdevTracker=createTracePerf({trackingMode: TrackingMode.DETAILED,trackMemory: true,enableNestedTracking: true});

Tracking Individual Functions

// Track a single function executionconstresult=traceperf.track(()=>{// Function bodyreturnsomeValue;},{label: 'functionName',threshold: 50,// mstrackMemory: true});// Create a trackable version of an existing functionconstmyFunction=(a,b)=>a+b;consttrackedFunction=traceperf.createTrackable(myFunction,{label: 'addition'});// Now use it normallyconstsum=trackedFunction(5,3);// will be tracked

Tracking Methods in a Module

constuserService={getUser: async(id)=>{/* implementation */},updateUser: async(id,data)=>{/* implementation */},deleteUser: async(id)=>{/* implementation */}};// Register all methods for trackingconsttrackedUserService=traceperf.registerModule(userService);// Now all method calls will be trackedconstuser=awaittrackedUserService.getUser(123);

Advanced Configuration

const{ createTracePerf, TrackingMode }=require('traceperf');constcustomTracker=createTracePerf({// Tracking mode affects detail level and performance impacttrackingMode: TrackingMode.BALANCED,// Enable or disable performance statistics in consolesilent: false,// Track memory usage (slight performance impact)trackMemory: true,// Enable tracking of nested function callsenableNestedTracking: 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 instanceconstbrowserTracker=createTracePerf({logger: newBrowserLogger({silent: false,trackMemory: true})});// Track function executionbrowserTracker.track(()=>{// Your browser-side code},{label: 'browserOperation'});// Create trackable functionsconsttrackedFn=browserTracker.createTrackable(()=>{// Function implementation},{label: 'trackedBrowserFn'});// Track async operationsawaitbrowserTracker.track(async()=>{constresponse=awaitfetch('/api/data');returnresponse.json();},{label: 'fetchData'});

You can also use it via script tag:

<scriptsrc="dist/traceperf.browser.js"></script><script>const{ createTracePerf, BrowserLogger }=TracePerf;constbrowserTracker=createTracePerf({logger: newBrowserLogger({silent: false,trackMemory: true})});// Use the same API as in Node.jsbrowserTracker.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.jsconst{ createTracePerf }=require('traceperf');constnodeTracker=createTracePerf();// Browserimport{createTracePerf}from'traceperf/browser';constbrowserTracker=createTracePerf();// Both environments support the same APIasyncfunctiontrackOperation(tracker){returnawaittracker.track(async()=>{constresult=awaitsomeAsyncOperation();returnprocessResult(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');consttraceperf=createTracePerf();asyncfunctionfetchData(url){returntraceperf.track(async()=>{constresponse=awaitfetch(url);returnresponse.json();},{label: 'fetchData',trackMemory: true});}

Tracking Nested Functions

const{ createTracePerf }=require('traceperf');consttraceperf=createTracePerf({enableNestedTracking: true});asyncfunctionprocessData(){returnawaittraceperf.track(async()=>{// This function call will be automatically tracked as a childconstdata=awaitfetchData();returntransformData(data);},{label: 'processData'});}asyncfunctionfetchData(){returnawaittraceperf.track(async()=>{// Implementation},{label: 'fetchData'});}functiontransformData(data){returntraceperf.track(()=>{// Implementation},{label: 'transformData'});}

Optimizing for Production

const{ createTracePerf, TrackingMode }=require('traceperf');// Development environmentconstdevTracker=createTracePerf({trackingMode: TrackingMode.DETAILED,silent: false,trackMemory: true,threshold: 0// track everything});// Production environmentconstprodTracker=createTracePerf({trackingMode: TrackingMode.PERFORMANCE,silent: true,// don't log to consoletrackMemory: false,// minimize overheadthreshold: 100,// only track slow functionssampleRate: 0.01// track only 1% of function calls});// Use based on environmentconsttraceperf=process.env.NODE_ENV==='production' ? prodTracker : devTracker;

Browser Usage

To use TracePerf in the browser:

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

Or with ES modules:

import{createTracePerf,TrackingMode}from'traceperf/browser';constbrowserTracker=createTracePerf({trackingMode: TrackingMode.BALANCED});// Track a DOM operationbrowserTracker.track(()=>{document.getElementById('output').textContent='Updated';},{label: 'updateDOM'});

Advanced Tracking Features

Tracking with Different Modes

const{ createTracePerf, TrackingMode }=require('traceperf');// Performance mode - minimal overheadconstperformanceTracker=createTracePerf({trackingMode: TrackingMode.PERFORMANCE});// Balanced mode - moderate detail with reasonable overheadconstbalancedTracker=createTracePerf({trackingMode: TrackingMode.BALANCED});// Detailed mode - maximum informationconstdetailedTracker=createTracePerf({trackingMode: TrackingMode.DETAILED});

Using Thresholds to Filter Results

const{ createTracePerf }=require('traceperf');consttracker=createTracePerf();// Only log functions that take more than 50mstracker.track(slowFunction,{threshold: 50});// Different thresholds for different functionstracker.track(criticalFunction,{threshold: 10});// Low threshold for critical pathstracker.track(backgroundTask,{threshold: 200});// Higher threshold for background tasks