@fastify/under-pressure

Install the plugin using npm:

npm i @fastify/under-pressure

You can enable a /status route (or a custom path) that returns { status: 'ok' }. This is useful for load balancers like AWS ELB.

To customize the route, use the exposeStatusRoute option. You can provide an object to configure routeOpts (Fastify route options), routeSchemaOpts (request schema), routeResponseSchemaOpts (to merge custom response fields), and url (the path).

fastify.register(require('@fastify/under-pressure'), {
  maxEventLoopDelay: 1000,
  exposeStatusRoute: {
    routeOpts: {
      logLevel: 'debug',
      config: {
        someAttr: 'value'
      }
    },
    routeSchemaOpts: {
      hide: true
    },
    url: '/alive'
  }
})

Register @fastify/under-pressure to monitor system resources. You can set thresholds for event loop delay, heap usage, RSS memory, and event loop utilization.

If a threshold is set to 0 (the default), that specific check is disabled. When a threshold is exceeded, the plugin automatically handles the request by returning a Service Unavailable error. You can customize the error message and the retryAfter (in seconds) header.

const fastify = require('fastify')()

fastify.register(require('@fastify/under-pressure'), {
  maxEventLoopDelay: 1000,
  maxHeapUsedBytes: 100000000,
  maxRssBytes: 100000000,
  maxEventLoopUtilization: 0.98,
  message: 'Under pressure!',
  retryAfter: 50
})

Use the sampleInterval option (in milliseconds) to set how often metrics are sampled.

Note: The default value varies by Node.js version. In Node 8 and 10, it is 5ms; in Node 11.10.0 and above, it is 1000ms due to the availability of monitorEventLoopDelay.

fastify.register(require('@fastify/under-pressure'), {
  sampleInterval: 500
})

You can check the current pressure status within your route handlers using fastify.isUnderPressure(). This is useful for skipping complex computations or non-essential tasks when the system is under load.

fastify.get('/', (request, reply) => {
  if (fastify.isUnderPressure()) {
    // skip complex computation
  }
  reply.send({ hello: 'world'})
})

To include extra information (like database status or custom metrics) in the status route response, implement the healthCheck function and use routeResponseSchemaOpts to define the schema for the additional fields. Note that the status field will always be present.

fastify.register(underPressure, {
  exposeStatusRoute: {
    routeResponseSchemaOpts: {
      extraValue: { type: 'string' },
      metrics: {
        type: 'object',
        properties: {
          eventLoopDelay: { type: 'number' },
          rssBytes: { type: 'number' },
          heapUsed: { type: 'number' },
          eventLoopUtilized: { type: 'number' },
        },
      },
    }
  },
  healthCheck: async (fastifyInstance) => {
    return {
      extraValue: await getExtraValue(),
      metrics: fastifyInstance.memoryUsage(),
    }
  },
})

The plugin exposes a fastify.memoryUsage() method that returns the current values for heapUsed, rssBytes, eventLoopDelay, and eventLoopUtilized.

console.log(fastify.memoryUsage())

The healthCheck property accepts an async function used to verify external resources (e.g., database connectivity).

• The function should return a Promise resolving to a boolean or an object.
• By default, the service is considered unhealthy until this function returns true.
• The check is triggered either at a regular interval (configured via healthCheckInterval in ms) or every time the status route is called.

fastify.register(require('@fastify/under-pressure'), {
  healthCheck: async function (fastifyInstance) {
    // Check if db connection is healthy
    return true
  },
  healthCheckInterval: 500
})

By default, the plugin throws a standard error when thresholds are met. You can provide a customError class to change the error type thrown.

class CustomError extends Error {
  constructor () {
    super('Custom error message')
    Error.captureStackTrace(this, CustomError)
  }
}

fastify.register(require('@fastify/under-pressure'), {
  maxEventLoopDelay: 1000,
  customError: CustomError
})

You can expose a GET route that returns the current health status of the service. This is useful for load balancers or orchestrators (like Kubernetes).

exposeStatusRoute can be:

• A string: The URL path (e.g., '/status').
• An object: Allows customizing the route.

Object properties:

• url: The path for the route.
• routeOpts: Standard Fastify route options (e.g., prefix, schema).
• routeSchemaOpts: Customization for the response schema.
• routeResponseSchemaOpts: Customization for the properties of the successful response object.

fastify.register(require('@fastify/under-pressure'), {
  exposeStatusRoute: {
    url: '/health',
    routeOpts: {
      schema: { /* ... */ }
    }
  }
})