@rhinolabs/fastify-monitor

Performance monitoring plugin for Fastify applications. Automatically tracks request timing, identifies slow endpoints, and provides actionable insights for your applications.

Features

• 🐌 Spot Slow Endpoints - Automatically alerts you when requests take longer than 1000ms
• 🚨 Critical Issue Detection - Detailed analysis for requests over 3000ms that need immediate attention
• 🚀 Zero Setup - Just install and register - no configuration needed
• 🎯 Flexible Filtering - Exclude paths with exact matches, wildcards, or RegExp patterns
• ⚙️ Configurable - Customize thresholds and exclusion patterns

Installation

npm install @rhinolabs/fastify-monitor

# Or using other package managers
pnpm add @rhinolabs/fastify-monitor
yarn add @rhinolabs/fastify-monitor

Quick Start

Automatic Registration (Recommended)

import Fastify from 'fastify';
import performanceMonitor from '@rhinolabs/fastify-monitor';

const fastify = Fastify({
  logger: true
});

// Register the plugin
await fastify.register(performanceMonitor);

// Add your routes
fastify.get('/api/users', async (request, reply) => {
  // Your route logic here
  return { users: [] };
});

await fastify.listen({ port: 3000 });

Usage with Boilr Framework

If you're using @rhinolabs/boilr, performance monitoring is automatically included:

import { createApp } from '@rhinolabs/boilr';

// Performance monitoring is automatically included
const app = createApp({
  server: { port: 3000 },
  routes: { dir: './routes' }
});

await app.start();

Console Output Examples

Startup Summary

📊 Performance monitoring enabled
   Monitoring thresholds: >1000ms (slow), >3000ms (very slow)

Performance Logging

# Fast responses (< 1ms)
⚡ Fast response: GET /api/cache → 200 (0ms)

# Normal responses (no logging)
# GET /api/users → 200 (45ms)

# Slow requests (> 1000ms)
🐌 Slow request: GET /api/heavy-query → 200 (1502ms)

# Very slow requests (> 3000ms)
🚨 Very slow request detected!
   Route: GET /api/database-export
   Status: 200
   Duration: 4005ms

# Error responses
❌ Error: GET /api/nonexistent → 404 (1ms)
❌ Error: POST /api/users → 400 (25ms)

How It Works

The plugin uses Fastify's hook system to:

1. Track Request Start Time - Records timestamp when request begins
2. Measure Response Time - Calculates duration when response is sent
3. Categorize Performance - Applies thresholds to identify slow requests
4. Log Actionable Insights - Provides context-aware performance information

Performance Thresholds

| Category | Threshold | Description | |----------|-----------|-------------| | ⚡ Fast | < 1ms | Potentially cached or empty responses | | 🟢 Normal | 1ms - 1000ms | Acceptable performance (no logging) | | 🐌 Slow | 1000ms - 3000ms | May need optimization | | 🚨 Very Slow | > 3000ms | Critical performance issues |

Configuration

The plugin works out of the box with smart defaults, but you can customize its behavior:

Basic Configuration

import Fastify from 'fastify';
import performanceMonitor from '@rhinolabs/fastify-monitor';

const fastify = Fastify();

await fastify.register(performanceMonitor, {
  // Custom performance thresholds
  slowThreshold: 2000,        // Log slow requests after 2000ms (default: 1000ms)
  verySlowThreshold: 5000,    // Log very slow requests after 5000ms (default: 3000ms)
});

Path Exclusion

The plugin monitors all requests by default. You can exclude specific paths using various patterns:

await fastify.register(performanceMonitor, {
  exclude: [
    // Exact path matches
    '/health',
    '/favicon.ico',
    
    // Wildcard patterns
    '/docs/*',              // Excludes /docs/api, /docs/guide, etc.
    '/static/*',            // Excludes all files in /static/
    '/api/*/internal',      // Excludes /api/v1/internal, /api/v2/internal, etc.
    
    // RegExp patterns for complex matching
    /\.(js|css|png|jpg)$/,  // Excludes files with these extensions
    /^\/admin\//,           // Excludes all paths starting with /admin/
  ],
});

Wildcard Pattern Examples

| Pattern | Matches | Doesn't Match | |---------|---------|---------------| | /docs/* | /docs/api, /docs/guide | /docs/api/users, /docs | | /static/** | /static/js/app.js, /static/css/style.css | /api/static | | /api/*/internal | /api/v1/internal, /api/v2/internal | /api/v1/internal/users | | *.json | config.json, data.json | /api/config.json |

Note: Use * to match anything except slashes, ** to match anything including slashes.

Complete Configuration Example

await fastify.register(performanceMonitor, {
  // Performance thresholds
  slowThreshold: 1500,
  verySlowThreshold: 4000,
  
  // Path exclusions - mix of exact matches, wildcards, and RegExp
  exclude: [
    // Health and monitoring endpoints
    '/health',
    '/ready',
    '/metrics',
    
    // Documentation and admin panels
    '/docs/*',
    '/admin/*',
    '/swagger/*',
    
    // Static assets using wildcards
    '/static/*',
    '/assets/*',
    '/uploads/*',
    
    // API patterns
    '/api/*/internal',      // Internal APIs for any version
    '/api/v*/health',       // Health checks for versioned APIs
    
    // File extensions using RegExp
    /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|pdf|zip)$/,
    
    // Complex patterns
    /^\/webhooks\//,        // All webhook endpoints
  ],
});

Integration Examples

Express Migration

// Before (Express with morgan)
const express = require('express');
const morgan = require('morgan');
const app = express();
app.use(morgan('combined'));

// After (Fastify with performance monitor)
import Fastify from 'fastify';
import performanceMonitor from '@rhinolabs/fastify-monitor';

const fastify = Fastify();
await fastify.register(performanceMonitor);

Existing Fastify Apps

// Add to existing Fastify applications
import performanceMonitor from '@rhinolabs/fastify-monitor';

// Register alongside other plugins
await fastify.register(require('@fastify/cors'));
await fastify.register(require('@fastify/helmet'));
await fastify.register(performanceMonitor); // Add performance monitoring

// Your existing routes continue to work
fastify.get('/api/health', healthHandler);

TypeScript Support

Full TypeScript support with complete type definitions:

import type { FastifyInstance } from 'fastify';
import performanceMonitor, { 
  type PerformanceMonitorOptions 
} from '@rhinolabs/fastify-monitor';

// Fully typed configuration
const options: PerformanceMonitorOptions = {
  slowThreshold: 2000,
  verySlowThreshold: 5000,
  excludePaths: [
    '/health',
    /^\/api\/internal\//,
  ],
};

const fastify: FastifyInstance = Fastify();
await fastify.register(performanceMonitor, options);

Best Practices

Development Workflow

1. Start Your Server with the performance monitor enabled
2. Make Requests to your API endpoints
3. Review Console Output for performance insights
4. Optimize Slow Endpoints highlighted by the plugin
5. Repeat until all endpoints perform well

Performance Optimization Tips

• Fast Responses (< 1ms): Verify these are intentional (caching, simple responses)
• Slow Requests (> 1000ms): Consider database query optimization, caching, or pagination
• Very Slow Requests (> 3000ms): High priority for optimization - investigate database queries, external API calls, or heavy computations

Compatibility

• Fastify: 5.x and above
• Node.js: 18.x and above
• TypeScript: 5.x and above

Contributing

Contributions are welcome! Please read our contributing guide for details.