Perf Observer

A lightweight performance observer using native Node.js performance APIs for debugging and benchmarking.

Table of Contents

• Installation
• Quick Start
• API Reference
  • Core Methods
  • Types
    • ProcessStats
    • BenchmarkOptions
    • BenchmarkResult
• Usage Examples
  • Basic Timing
  • Function Tracking
  • Performance Statistics
  • Benchmarking
  • Finding Slow Processes
• Requirements
• Contributing
• License

Installation

npm install @neabyte/perf-observer

Quick Start

import perf from '@neabyte/perf-observer'

// Track a function automatically
const trackedFunction = perf.track(() => {
  // Your code here
  return 'result'
})

// Manual timing
perf.start('my-process')
// ... do work ...
const duration = perf.end('my-process')

// Run benchmarks
const result = perf.benchmark(() => {
  // Function to benchmark
}, { iterations: 1000 })

API Reference

Core Methods

Method	Description	Returns
start(name)	Start timing a process	void
end(name)	End timing and get duration	number (ms)
track(fn, name?)	Wrap function with automatic timing	Function
getStats(name?)	Get performance statistics	ProcessStats
findSlowProcesses(threshold?)	Find processes exceeding threshold	ProcessEntry[]
benchmark(fn, options?)	Run benchmark test	BenchmarkResult

Types

ProcessStats

Property	Type	Description
count	number	Number of processes
avgDuration	number	Average duration (ms)
minDuration	number	Minimum duration (ms)
maxDuration	number	Maximum duration (ms)
p95Duration	number	95th percentile (ms)
p99Duration	number	99th percentile (ms)

BenchmarkOptions

Property	Type	Default	Description
iterations	number	1000	Number of test iterations
warmup	number	min(100, iterations/10)	Warmup iterations
maxDuration	number	60000	Max test duration (ms)
outlierThreshold	number	3	Outlier detection threshold
trackMemory	boolean	false	Track memory usage
name	string	fn.name	Custom benchmark name

BenchmarkResult

Property	Type	Description
name	string	Benchmark name
iterations	number	Actual iterations completed
warmupIterations	number	Warmup iterations performed
totalTime	number	Total time (ms)
avgTime	number	Average time per iteration (ms)
minTime	number	Minimum iteration time (ms)
maxTime	number	Maximum iteration time (ms)
p95Time	number	95th percentile time (ms)
p99Time	number	99th percentile time (ms)
stdDev	number	Standard deviation
outliers	number	Number of outliers removed
memoryDelta	number?	Memory usage change (bytes)

Usage Examples

Basic Timing

// Manual timing
perf.start('database-query')

// Simulate database operation
await new Promise(resolve => setTimeout(resolve, 50))
const duration = perf.end('database-query')
console.log(`Query took ${duration}ms`)

Function Tracking

// Automatic timing
const expensiveOperation = perf.track(async () => {
  await new Promise(resolve => setTimeout(resolve, 100))
  return 'completed'
})

const result = await expensiveOperation()

Duplicate Name Behavior: Multiple functions with the same name will overwrite each other's performance data. Only the last function's data will be preserved in statistics. To avoid data loss:

• Use unique names: perf.track(fn, 'unique-name')
• Add hash suffixes: perf.track(fn, 'operation-' + crypto.randomBytes(4).toString('hex'))
• Use function names: function myOperation() {} then perf.track(myOperation)

Anonymous functions all use 'anonymous' name and will overwrite each other.

Performance Statistics

// Get stats for all processes
const allStats = perf.getStats()
console.log(`Average: ${allStats.avgDuration}ms`)

// Get stats for specific process
const queryStats = perf.getStats('database-query')
console.log(`95th percentile: ${queryStats.p95Duration}ms`)

Benchmarking

// Simple benchmark
const result = perf.benchmark(() => {
  return Math.random() * 1000
}, 10000)

console.log(`Average: ${result.avgTime}ms`)
console.log(`Standard deviation: ${result.stdDev}ms`)

// Advanced benchmark with options
const advancedResult = perf.benchmark(
  () => {
    // Simulate data processing
    return Array.from({ length: 1000 }, (_, i) => i * 2)
  },
  {
    iterations: 5000,
    warmup: 100,
    trackMemory: true,
    outlierThreshold: 2,
    name: 'data-processing'
  }
)

Finding Slow Processes

// Find processes taking longer than 1 second
const slowProcesses = perf.findSlowProcesses(1000)
slowProcesses.forEach(process => {
  console.log(`${process.name}: ${process.duration}ms`)
})

Requirements

• Node.js >= 22.0.0
• TypeScript (optional, for type definitions)

Contributing

Issues and pull requests are welcome on GitHub.

License

This project is licensed under the MIT license. See the LICENSE file for more info.