https://github.com/thelastbackspace/traceperf
TracePerf: Advanced console logging & performance tracking for Node.js. Visualize execution flows with ASCII art, detect bottlenecks, and get optimization suggestions. Features structured logs, conditional modes, and memory tracking. Makes debugging faster and more intuitive.
https://github.com/thelastbackspace/traceperf
Last synced: 8 months ago
JSON representation
TracePerf: Advanced console logging & performance tracking for Node.js. Visualize execution flows with ASCII art, detect bottlenecks, and get optimization suggestions. Features structured logs, conditional modes, and memory tracking. Makes debugging faster and more intuitive.
- Host: GitHub
- URL: https://github.com/thelastbackspace/traceperf
- Owner: thelastbackspace
- License: mit
- Created: 2025-03-15T18:40:10.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-03-18T14:51:17.000Z (12 months ago)
- Last Synced: 2025-06-24T15:08:23.830Z (9 months ago)
- Language: TypeScript
- Size: 271 KB
- Stars: 117
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-repositories - thelastbackspace/traceperf - TracePerf: Advanced console logging & performance tracking for Node.js. Visualize execution flows with ASCII art, detect bottlenecks, and get optimization suggestions. Features structured logs, condit (TypeScript)
README
# TracePerf
Advanced performance tracking and execution monitoring for Node.js applications.
[](https://www.npmjs.com/package/traceperf)
[](https://opensource.org/licenses/MIT)
## 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
```bash
npm install traceperf
```
## Quick Start
```javascript
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:
```javascript
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
```javascript
// 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
```javascript
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
```javascript
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:
```javascript
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:
```html
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' });
```
## 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:
```javascript
// 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
```javascript
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
```javascript
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
```javascript
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:
```html
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' });
```
Or with ES modules:
```javascript
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
```javascript
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
```javascript
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
```