fastify-statistics

A lightweight Fastify plugin that provides system statistics and metrics endpoints for monitoring your Node.js application, including memory usage and event loop utilization metrics.

Installation

npm install fastify-statistics

Usage

Add it to your project with register and you are done!

const fastify = require('fastify')({ logger: true })

// Register the plugin
await fastify.register(require('fastify-statistics'))

// Start the server
await fastify.listen({ port: 3000 })

API Endpoints

GET /uptime

Returns the application uptime in seconds.

Response:

{
  "uptime": 3600
}

GET /metrics

Returns memory usage metrics, event loop utilization, and timestamp.

Response (default - bytes):

{
  "memory": {
    "rss": "52428800",
    "heapTotal": "20971520",
    "heapUsed": "18874368",
    "external": "1089024"
  },
  "elu": {
    "raw": 0.05,
    "percentage": "5.00%"
  },
  "timestamp": "2025-07-25T10:30:00.000Z"
}

Response (MB format):

{
  "memory": {
    "rss": "50.00 MB",
    "heapTotal": "20.00 MB",
    "heapUsed": "18.00 MB",
    "external": "1.04 MB"
  },
  "elu": {
    "raw": 0.05,
    "percentage": "5.00%"
  },
  "timestamp": "2025-07-25T10:30:00.000Z"
}

GET /stats

Returns combined statistics including uptime, memory metrics, event loop utilization, and timestamp.

Response:

{
  "uptime": 3600,
  "memory": {
    "rss": "52428800",
    "heapTotal": "20971520",
    "heapUsed": "18874368",
    "external": "1089024"
  },
  "elu": {
    "raw": 0.05,
    "percentage": "5.00%"
  },
  "timestamp": "2025-07-25T10:30:00.000Z"
}

Configuration Options

await fastify.register(require('fastify-statistics'), {
  // Format memory values in MB instead of bytes
  metricsInMB: true,
  
  // Customize route paths
  uptimeRoute: '/api/uptime',
  metricsRoute: '/api/metrics'
})

Options

| Option | Type | Default | Description | |-----------------|-------------|--------------|------------------------------------------------| | metricsInMB | boolean | false | Format memory values in MB instead of bytes | | uptimeRoute | string | '/uptime' | Custom path for uptime endpoint | | metricsRoute | string | '/metrics' | Custom path for metrics endpoint |

Examples

Basic Usage

const fastify = require('fastify')({ logger: true })

await fastify.register(require('fastify-statistics'))

await fastify.listen({ port: 3000 })

// Test the endpoints
// GET http://localhost:3000/uptime
// GET http://localhost:3000/metrics
// GET http://localhost:3000/stats

Custom Configuration

const fastify = require('fastify')({ logger: true })

await fastify.register(require('fastify-statistics'), {
  metricsInMB: true,
  uptimeRoute: '/health/uptime',
  metricsRoute: '/health/metrics'
})

await fastify.listen({ port: 3000 })

// Endpoints are now available at:
// GET http://localhost:3000/health/uptime
// GET http://localhost:3000/health/metrics
// GET http://localhost:3000/stats (always available)

Metrics Explained

Memory Metrics

| Metric | Description | |-------------|----------------------------------------------------------------------| | rss | Resident Set Size - Total physical memory used by the process | | heapTotal | Total V8 heap size allocated | | heapUsed | V8 heap memory currently in use | | external | Memory used by C++ objects bound to JavaScript objects managed by V8 |

Event Loop Utilization (ELU)

Event Loop Utilization provides insights into how much time the event loop is spending on synchronous work vs. waiting for I/O operations.

| Field | Type | Description | |------------------|----------|------------------------------------------------------------------| | elu.raw | number | Event loop utilization as a decimal between 0 and 1 | | elu.percentage | string | Event loop utilization formatted as a percentage (e.g., "5.00%") |

Error Handling

The plugin follows Fastify's error handling patterns. If system metrics cannot be retrieved, errors will be thrown and handled by Fastify's default error handler.

License

MIT License