Node Profiler

A lightweight Node.js profiler to track CPU, memory, and response time for functions and APIs. Supports per-route aggregation, percentiles, async functions, and middleware.

Installation

npm install node-lite-profiler

Upgrade

npm install node-lite-profiler@latest

Quick Start

const { createProfiler, wrapFunction } = require('node-lite-profiler');

const profiler = createProfiler({
  enabled: true,
  sampleRate: 1,            // 1 for full sampling
  debug: true,              // optional: prints debug info
  onResult: (data) => {
    console.log('PROFILE RESULT:', data);
  },
  flushIntervalMs: 5000,    // optional: auto-flush every 5 seconds
  onFlush: (aggregates) => {
    console.log('Aggregated metrics:', aggregates);
  }
});

// Profile a standalone function
async function fetchUser() {
  await new Promise(r => setTimeout(r, 120));
  return { id: 1, name: 'Sunny' };
}

const profiledFetchUser = wrapFunction(profiler, 'fetchUser', fetchUser);

(async () => {
  await profiledFetchUser();
})();

Express Middleware

const express = require('express');
const { expressMiddleware } = require('node-lite-profiler');

const app = express();

// Add profiler middleware to all routes
app.use(expressMiddleware(profiler));

app.get('/users/:id', async (req, res) => {
  await profiledFetchUser();
  res.send({ id: req.params.id });
});

app.listen(3000, () => console.log('Server running on port 3000'));

• Automatically tracks per-route metrics
• Aggregates percentiles (p50, p90, p99) per route
• Handles concurrent requests with inFlight tracking

Wrapping Functions

const profiledFunction = wrapFunction(profiler, 'functionName', asyncFunction);

// Now calling profiledFunction will measure CPU, memory, and time
await profiledFunction();

• Works with sync and async functions
• Automatically handles errors and decrements in-flight counters

Aggregates & Flush

Manual flush:

profiler.flush();

• Computes percentiles per function/API
• Clears stored metrics for the next interval
• Can also use flushIntervalMs for automatic periodic flush

Example output:

{
  "function:fetchUser": { "count": 5, "p50": 120, "p90": 180, "p99": 200 },
  "api:GET /users/:id": { "count": 20, "p50": 30, "p90": 50, "p99": 80 }
}

Concurrency & Async

• Handles multiple async executions in parallel
• inFlight counter tracks concurrent executions per function/API
• Percentiles computed over all samples

Limitations

• CPU/memory are process-wide, not exact per async task
• Per-route aggregation assumes route path is stable
• Async_hooks tracking may add minor overhead

Next Steps / How to Experiment

1. Fork the repo and try profiling multiple functions/APIs
2. Experiment with different sampling rates
3. Try integrating profiler into a real Node.js server

This profiler is designed to help developers understand real performance metrics without much setup, while keeping the usage simple and minimal.