📦 @tezx/profiler

A lightweight, extensible profiling middleware for the TezX framework.
Track runtime performance, memory usage, CPU stats, with plugin support and rotating file storage.

Features

⏱️ Measure route execution time
💾 Monitor memory usage in MB
⚙️ Capture CPU usage in milliseconds
📊 System stats endpoint (/__profiler) with a clean UI
🔌 Plugin hooks (beforeProfile, afterProfile)
📁 Rotating file storage for logs
✅ Written in TypeScript with full type safety

Installation

npm install @tezx/profiler
# or
yarn add @tezx/profiler
# or
bun add @tezx/profiler

Usage Example

Basic Setup

import { TezX } from 'tezx';
import { profiler, createRotatingFileStorage } from '@tezx/profiler';

const app = new TezX();

app.use(
  profiler({
    route: '/__profiler',
    excludePaths: ['/favicon.ico'],
    metrics: ['time', 'memory', 'cpu'],
    storage: createRotatingFileStorage('./profiler.log', 1024 * 1024), // Rotate every 1MB
    plugins: [],
  })
);

app.get('/', (ctx) => ctx.json({ message: 'Hello World' }));

Profiler UI

Visit:

http://localhost:3000/__profiler

Displays:

✅ Uptime (seconds)
✅ Timestamp
✅ Memory Usage (rss, heapTotal, heapUsed, etc.) in MB
✅ CPU Usage (user, system) in ms

⚙️ Profiler Options

Option	Type	Default	Description
`route`	`string`	`/__profiler`	Path to view system stats
`excludePaths`	`string[]`	`[]`	Paths to ignore
`metrics`	`("time" \| "memory" \| "cpu")[]`	`['time','memory']`	Metrics to collect
`storage`	`StorageAdapter`	`undefined`	Save profile results
`plugins`	`ProfilerPlugin[]`	`[]`	Hook into profiling lifecycle

Plugins Example

const myPlugin = {
  beforeProfile: () => console.log('Starting profiling...'),
  afterProfile: (result) => console.log('Profile completed:', result),
};

app.use(profiler({ plugins: [myPlugin] }));

Rotating File Storage Example

const storage = createRotatingFileStorage('./profiler.log', 1024 * 1024); // 1MB rotation
app.use(profiler({ storage }));

Example Profile Output

{
  "name": "default",
  "duration": 6.25,
  "timestamp": "2025-07-06T19:25:47.753Z",
  "method": "GET",
  "path": "/",
  "memoryUsage": {
    "rss": 10485760,
    "heapTotal": 6291456,
    "heapUsed": 4194304,
    "external": 102400,
    "arrayBuffers": 51200
  },
  "cpuUsage": {
    "user": 1416,
    "system": 312
  }
}

System Stats Breakdown

Memory Usage

rss: Resident Set Size (total memory allocated for the process)
heapTotal: Total allocated heap size
heapUsed: Heap actually used
external: Memory used by C++ objects bound to JS
arrayBuffers: Memory allocated for ArrayBuffer

CPU Usage

user: Time spent in user mode (μs)
system: Time spent in kernel mode (μs)

tezx/profiler

On this page