{"id":13526375,"url":"https://github.com/fastify/under-pressure","last_synced_at":"2025-05-14T13:05:52.510Z","repository":{"id":37768319,"uuid":"109049948","full_name":"fastify/under-pressure","owner":"fastify","description":"Process load measuring plugin for Fastify, with automatic handling of \"Service Unavailable\"","archived":false,"fork":false,"pushed_at":"2025-05-01T06:53:19.000Z","size":222,"stargazers_count":379,"open_issues_count":4,"forks_count":37,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-05-01T07:35:34.084Z","etag":null,"topics":["fastify","fastify-plugin"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@fastify/under-pressure","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2017-10-31T20:40:25.000Z","updated_at":"2025-05-01T06:53:15.000Z","dependencies_parsed_at":"2023-02-06T08:01:48.876Z","dependency_job_id":"a50c534e-e536-47f6-9cdd-4e8c2b55ee3a","html_url":"https://github.com/fastify/under-pressure","commit_stats":{"total_commits":198,"total_committers":45,"mean_commits":4.4,"dds":0.7828282828282829,"last_synced_commit":"fc463eb275166acb56fc68b14295650eee3d4e26"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Funder-pressure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Funder-pressure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Funder-pressure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Funder-pressure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/under-pressure/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149944,"owners_count":22022851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastify","fastify-plugin"],"created_at":"2024-08-01T06:01:28.766Z","updated_at":"2025-05-14T13:05:52.480Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# @fastify/under-pressure\n\n[![CI](https://github.com/fastify/under-pressure/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/under-pressure/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/@fastify/under-pressure.svg?style=flat)](https://www.npmjs.com/package/@fastify/under-pressure)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\nProcess load measuring plugin for Fastify, with automatic handling of *\"Service Unavailable\"*.\nIt can check `maxEventLoopDelay`, `maxHeapUsedBytes`, `maxRssBytes`, and `maxEventLoopUtilization` values.\nYou can also specify a custom health check, to verify the status of\nexternal resources.\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n## Install\n```\nnpm i @fastify/under-pressure\n```\n\n### Compatibility\n| Plugin version | Fastify version |\n| ---------------|-----------------|\n| `\u003e=9.x`        | `^5.x`          |\n| `\u003e=6.x \u003c9.x`   | `^4.x`          |\n| `^5.x`         | `^3.x`          |\n| `\u003e=2.x \u003c5.x`   | `^2.x`          |\n| `^1.x`         | `^1.x`          |\n\n\nPlease note that if a Fastify version is out of support, then so are the corresponding versions of this plugin\nin the table above.\nSee [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details.\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n## Usage\nRequire the plugin and register it into the Fastify instance.\n\n```js\nconst fastify = require('fastify')()\n\nfastify.register(require('@fastify/under-pressure'), {\n  maxEventLoopDelay: 1000,\n  maxHeapUsedBytes: 100000000,\n  maxRssBytes: 100000000,\n  maxEventLoopUtilization:0.98\n})\n\nfastify.get('/', (request, reply) =\u003e {\n  if (fastify.isUnderPressure()) {\n    // skip complex computation\n  }\n  reply.send({ hello: 'world'})\n})\n\nfastify.listen({ port: 3000 }, err =\u003e {\n  if (err) throw err\n  console.log(`server listening on ${fastify.server.address().port}`)\n})\n```\n`@fastify/under-pressure` will automatically handle for you the `Service Unavailable` error once one of the thresholds has been reached.\nYou can configure the error message and the `Retry-After` header.\n```js\nfastify.register(require('@fastify/under-pressure'), {\n  maxEventLoopDelay: 1000,\n  message: 'Under pressure!',\n  retryAfter: 50\n})\n```\n\nYou can also configure custom Error instance `@fastify/under-pressure` will throw.\n```js\nclass CustomError extends Error {\n  constructor () {\n    super('Custom error message')\n    Error.captureStackTrace(this, CustomError)\n  }\n}\n\nfastify.register(require('@fastify/under-pressure'), {\n  maxEventLoopDelay: 1000,\n  customError: CustomError\n})\n```\n\nThe default value for `maxEventLoopDelay`, `maxHeapUsedBytes`, `maxRssBytes`, and `maxEventLoopUtilization` is `0`.\nIf the value is `0` the check will not be performed.\n\nThanks to the encapsulation model of Fastify, you can selectively use this plugin in a subset of routes or even with different thresholds in different plugins.\n\n#### `memoryUsage`\nThis plugin also exposes a function that will tell you the current values of `heapUsed`, `rssBytes`, `eventLoopDelay`, and `eventLoopUtilized`.\n```js\nconsole.log(fastify.memoryUsage())\n```\n\n#### Pressure Handler\n\nYou can provide a pressure handler in the options to handle the pressure errors. The advantage is that you know why the error occurred. Moreover, the request can be handled as if nothing happened.\n\n```js\nconst fastify = require('fastify')()\nconst underPressure = require('@fastify/under-pressure')()\n\nfastify.register(underPressure, {\n  maxHeapUsedBytes: 100000000,\n  maxRssBytes: 100000000,\n  pressureHandler: (request, reply, type, value) =\u003e {\n    if (type === underPressure.TYPE_HEAP_USED_BYTES) {\n      fastify.log.warn(`too many heap bytes used: ${value}`)\n    } else if (type === underPressure.TYPE_RSS_BYTES) {\n      fastify.log.warn(`too many rss bytes used: ${value}`)\n    }\n\n    reply.send('out of memory') // if you omit this line, the request will be handled normally\n  }\n})\n```\n\nIt is possible as well to return a Promise that will call `reply.send` (or something else).\n\n```js\nfastify.register(underPressure, {\n  maxHeapUsedBytes: 100000000,\n  pressureHandler: (request, reply, type, value) =\u003e {\n    return getPromise().then(() =\u003e reply.send({ hello: 'world' }))\n  }\n})\n```\n\nAny other return value than a promise or nullish will be sent to the client with `reply.send`.\n\nIt's also possible to specify the `pressureHandler` on the route:\n\n```js\nconst fastify = require('fastify')()\nconst underPressure = require('@fastify/under-pressure')()\n\nfastify.register(underPressure, {\n  maxHeapUsedBytes: 100000000,\n  maxRssBytes: 100000000,\n})\n\nfastify.register(async function (fastify) {\n  fastify.get('/', {\n    config: {\n      pressureHandler: (request, reply, type, value) =\u003e {\n        if (type === underPressure.TYPE_HEAP_USED_BYTES) {\n          fastify.log.warn(`too many heap bytes used: ${value}`)\n        } else if (type === underPressure.TYPE_RSS_BYTES) {\n          fastify.log.warn(`too many rss bytes used: ${value}`)\n        }\n\n        reply.send('out of memory') // if you omit this line, the request will be handled normally\n      }\n    }\n  }, () =\u003e 'A')\n})\n```\n\n#### Status route\nIf needed you can pass `{ exposeStatusRoute: true }` and `@fastify/under-pressure` will expose a `/status` route for you that sends back a `{ status: 'ok' }` object. This can be useful if you need to attach the server to an ELB on AWS for example.\n\nIf you need the change the exposed route path, you can pass `{ exposeStatusRoute: '/alive' }` options.\n\nTo configure the endpoint more specifically you can pass an object. This consists of\n\n- *routeOpts* - Any Fastify [route options](https://fastify.dev/docs/latest/Reference/Routes/#routes-options) except `schema`\n- *routeSchemaOpts* - As per the Fastify route options, an object containing the schema for request\n- *routeResponseSchemaOpts* - An object containing the schema for additional response items to be merged with the default response schema, see below\n- *url* - The URL to expose the status route on\n\n```js\nfastify.register(require('@fastify/under-pressure'), {\n  maxEventLoopDelay: 1000,\n  exposeStatusRoute: {\n    routeOpts: {\n      logLevel: 'debug',\n      config: {\n        someAttr: 'value'\n      }\n    },\n    routeSchemaOpts: { // If you also want to set a custom route schema\n      hide: true\n    },\n    url: '/alive' // If you also want to set a custom route path and pass options\n  }\n})\n```\nThe above example will set the `logLevel` value for the `/alive` route to `debug`.\n\nIf you need to return other information in the response, you can return an object from the `healthCheck` function (see next paragraph) and use the `routeResponseSchemaOpts` property to describe your custom response schema (**note**: `status` will always be present in the response)\n\n```js\nfastify.register(underPressure, {\n  ...\n  exposeStatusRoute: {\n    routeResponseSchemaOpts: {\n      extraValue: { type: 'string' },\n      metrics: {\n        type: 'object',\n        properties: {\n          eventLoopDelay: { type: 'number' },\n          rssBytes: { type: 'number' },\n          heapUsed: { type: 'number' },\n          eventLoopUtilized: { type: 'number' },\n        },\n      },\n      // ...\n    }\n  },\n  healthCheck: async (fastifyInstance) =\u003e {\n    return {\n      extraValue: await getExtraValue(),\n      metrics: fastifyInstance.memoryUsage(),\n      // ...\n    }\n  },\n}\n```\n\n#### Custom health checks\nIf needed you can pass a custom `healthCheck` property, which is an async function, and `@fastify/under-pressure` will allow you to check the status of other components of your service.\n\nThis function should return a promise that resolves to a boolean value or an object. The `healthCheck` function can be called either:\n\n* every X milliseconds, the time can be\n  configured with the `healthCheckInterval` option.\n* every time the status route is called, if `exposeStatusRoute` is set\n  to `true`.\n\nBy default when this function is supplied your service health is considered unhealthy, until it has started to return true.\n\n```js\nconst fastify = require('fastify')()\n\nfastify.register(require('@fastify/under-pressure'), {\n  healthCheck: async function (fastifyInstance) {\n    // Do some magic to check if your db connection is healthy\n    return true\n  },\n  healthCheckInterval: 500\n})\n```\n\u003ca name=\"sample-interval\"\u003e\u003c/a\u003e\n#### Sample interval\n\nYou can set a custom value for sampling the metrics returned by `memoryUsage` using the `sampleInterval` option, which accepts a number that represents the interval in milliseconds.\n\nThe default value is different depending on which Node version is used. In version 8 and 10 it is `5`, while on version 11.10.0 and up it is `1000`. This difference is because from version 11.10.0 the event loop delay can be sampled with [`monitorEventLoopDelay`](https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_perf_hooks_monitoreventloopdelay_options) and this allows an increase in the interval value.\n\n```js\nconst fastify = require('fastify')()\n\nfastify.register(require('@fastify/under-pressure'), {\n  sampleInterval: \u003cyour custom sample interval in ms\u003e\n})\n```\n\n\u003ca name=\"additional-information\"\u003e\u003c/a\u003e\n## Additional information\n\n\u003ca name=\"set-timeout-vs-set-interval\"\u003e\u003c/a\u003e\n#### `setTimeout` vs `setInterval`\n\nUnder the hood, `@fastify/under-pressure` uses the `setTimeout` method to perform its polling checks. The choice is based on the fact that we do not want to add additional pressure to the system.\n\nIn fact, it is known that `setInterval` will call repeatedly at the scheduled time regardless of whether the previous call ended or not, and if the server is already under load, this will likely increase the problem, because those `setInterval` calls will start piling up. `setTimeout`, on the other hand, is called only once and does not cause the mentioned problem.\n\nOne note to consider is that because the two methods are not identical, the timer function is not guaranteed to run at the same rate when the system is under pressure or running a long-running process.\n\n\n\u003ca name=\"acknowledgments\"\u003e\u003c/a\u003e\n## Acknowledgments\n\nThis project is kindly sponsored by [LetzDoIt](https://www.letzdoitapp.com/).\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript","\u003ch2 align=\"center\"\u003eAwesome Fastify\u003c/h2\u003e"],"sub_categories":["\u003ch2 align=\"center\"\u003eEcosystem\u003c/h2\u003e"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Funder-pressure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Funder-pressure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Funder-pressure/lists"}