{"id":13524252,"url":"https://github.com/immobiliare/fastify-sentry","last_synced_at":"2025-05-16T13:05:59.473Z","repository":{"id":36985110,"uuid":"438297425","full_name":"immobiliare/fastify-sentry","owner":"immobiliare","description":"🚧  Sentry errors handler for fastify that just works! Install, add your DSN and you're good to go!","archived":false,"fork":false,"pushed_at":"2024-11-28T13:33:00.000Z","size":2620,"stargazers_count":90,"open_issues_count":20,"forks_count":13,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-15T13:19:42.957Z","etag":null,"topics":["crash-reporting","error-handling","error-logging","fastify","fastify-plugin","hacktoberfest","javascript","monitoring","nodejs","sentry"],"latest_commit_sha":null,"homepage":"","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/immobiliare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2021-12-14T15:08:23.000Z","updated_at":"2025-05-15T02:58:22.000Z","dependencies_parsed_at":"2023-12-19T15:08:15.857Z","dependency_job_id":"d3d991c3-0f8a-4f98-a06e-a62e384e4614","html_url":"https://github.com/immobiliare/fastify-sentry","commit_stats":{"total_commits":514,"total_committers":12,"mean_commits":"42.833333333333336","dds":"0.30544747081712065","last_synced_commit":"8996eb4d23ad8f1c78f56348b68c736fb2bb74ac"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Ffastify-sentry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Ffastify-sentry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Ffastify-sentry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immobiliare%2Ffastify-sentry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/immobiliare","download_url":"https://codeload.github.com/immobiliare/fastify-sentry/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535827,"owners_count":22087399,"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":["crash-reporting","error-handling","error-logging","fastify","fastify-plugin","hacktoberfest","javascript","monitoring","nodejs","sentry"],"created_at":"2024-08-01T06:01:08.414Z","updated_at":"2025-05-16T13:05:59.453Z","avatar_url":"https://github.com/immobiliare.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003efastify-sentry\u003c/h1\u003e\n\n[![Release](https://github.com/immobiliare/fastify-sentry/actions/workflows/release.yml/badge.svg)](https://github.com/immobiliare/fastify-sentry/actions/workflows/release.yml)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier?style=flat-square)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release)\n![npm (scoped)](https://img.shields.io/npm/v/@immobiliarelabs/fastify-sentry)\n![license](https://img.shields.io/github/license/immobiliare/fastify-sentry)\n\n\u003e In our [Fastify](https://www.fastify.io/) applications, no matter how good our code is sometimes errors happens, we may need to catch and send them to [Sentry](https://sentry.io/) for further analysis! This plugin aim to do just that, as easily as possible!\n\nPlug, add your Sentry's `DSN` and you're good to go!\nThis plugin standardize options and payload format then registers a default errorHandler that uses `Sentry` to report errors, it also decorates the `fastify` instance with the `Sentry` object so you can use it for your custom needs.\n\n\u003e ⚠️ Fastify 4 introduced some breaking changes, please refer to [this](#fastify-version-support) version support table to find what works best for you!\n\n## Table of contents\n\n\u003c!-- toc --\u003e\n\n- [Installation](#installation)\n- [Migration guides](#migration-guides)\n- [Usage](#usage)\n  * [using Sentry in a route handler](#using-sentry-in-a-route-handler)\n  * [Benchmarks](#benchmarks)\n- [API](#api)\n  * [Configuration `options`](#configuration-options)\n    + [setErrorHandler](#seterrorhandler)\n    + [shouldHandleError](#shouldhandleerror)\n    + [errorResponse](#errorresponse)\n    + [getTransactionName](#gettransactionname)\n    + [extractRequestData](#extractrequestdata)\n    + [extractUserData](#extractuserdata)\n    + [skipInit](#skipinit)\n  * [utils](#utils)\n    + [getTransactionName](#gettransactionname-1)\n    + [extractRequestData](#extractrequestdata-1)\n    + [extractUserData](#extractuserdata-1)\n    + [tryToExtractBody](#trytoextractbody)\n    + [extractPathForTransaction](#extractpathfortransaction)\n    + [shouldHandleError](#shouldhandleerror-1)\n    + [errorResponse](#errorresponse-1)\n- [Compatibility](#compatibility)\n- [Powered Apps](#powered-apps)\n- [Support \u0026 Contribute](#support--contribute)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## Installation\n\nYou can install it with `npm`\n\n```bash\n# lastest stable version\n$ npm i -S @immobiliarelabs/fastify-sentry\n# latest development version\n$ npm i -S @immobiliarelabs/fastify-sentry@next\n```\n\nor `yarn`\n\n```bash\n# lastest stable version\n$ yarn add @immobiliarelabs/fastify-sentry\n# latest development version\n$ yarn add @immobiliarelabs/fastify-sentry@next\n```\n\n## Migration guides\n\nPlease check these [migration guides](./MIGRATION_GUIDE.md) if you are migrating from an older version of the plugin.\n\n## Usage\n\n```js\nconst fastify = require('fastify')();\n\nfastify.register(require('@immobiliarelabs/fastify-sentry'), {\n    dsn: '\u003cyour sentry dsn\u003e',\n    environment: 'production',\n    release: '1.0.0',\n});\n```\n\n### using Sentry in a route handler\n\n```js\nconst fastify = require('fastify')();\n\nfastify.register(require('@immobiliarelabs/fastify-sentry'), {\n    dsn: '\u003cyour sentry dsn\u003e',\n    environment: 'production',\n    release: '1.0.0',\n});\n\nfastify.get('/user/:id', async function (req, reply) {\n    const user = await getUserFromStorage(req.params.id);\n    if (user.blocked) {\n        this.Sentry.captureMessage('Blocked user tried to get in');\n        ...\n    } else {\n        ...\n    }\n});\n```\n\nYou can find more examples of usage in the [examples](./examples/) folder :wink:.\n\n### Benchmarks\n\nAs for everything, using Sentry comes at a cost. You can see the benchmarks [here](./benchmarks/)\n\n## API\n\nThis module exports a [plugin registration function](https://github.com/fastify/fastify/blob/2.x/docs/Plugins-Guide.md#register).\n\nThe exported plugin adds the following decorators:\n\n* `fastify.Sentry`: a reference to the `Sentry` instance\n* `reply.sentryEventId` `\u003cstring\u003e`: the id of a captured exception, accessible when defining a custom `errorResponse` handler in the plugin options\n* `reply.sentryTransaction`: the current request transaction, accessible when enabling tracing in `Sentry`\n\nand adds a custom error handler that reports to Sentry all the errors that have a `5xx` status code.\n\n### Configuration `options`\n\n\u003e The plugin extends [the standard Sentry options object](https://docs.sentry.io/platforms/node/configuration/options/) with the following properties:\n\n\n#### setErrorHandler\n\n\u003e Attach the default error handler to the `fastify` instance.\n\n**type**: `boolean`\n\n**default**: `true`\n\n#### shouldHandleError\n\n\u003e Decide if the error should be sent to `Sentry`\n\nThis function is called in the default error handler that the plugin adds.\n\n**type**: `function`\n\n**parameters**:\n\n* `error` `\u003cFastifyError\u003e`\n* `request` `\u003cFastifyRequest\u003e`\n* `reply` `\u003cFastifyReply\u003e`\n\n**returns**:\n\n`boolean`: `true` if the error should be sent, `false` otherwise.\n\n**default**: a function that returns `true` if the status code of the error is `5xx`\n\n#### errorResponse\n\n\u003e Custom handler to respond the client.\n\nThis function is called in the dafult error handler right after the exception is captured, so the `reply` is decorated with event id assigned by the `Sentry` SDK.\n\n**type**: `function`\n\n**parameters**:\n\n* `error` `\u003cFastifyError\u003e`\n* `request` `\u003cFastifyRequest\u003e`\n* `reply` `\u003cFastifyReply\u003e`\n\n**returns**: `void`\n\n#### getTransactionName\n\n\u003e Get the request transaction name.\n\n**type**: `function`\n\n**parameters**:\n\n* `request` `\u003cFastifyRequest\u003e`\n\n**returns**: `string`\n\n#### extractRequestData\n\n\u003e Extract request metadata to attach the `Sentry` event.\n\n**type**: `function`\n\n**parameters**:\n\n* `request` `\u003cFastifyRequest\u003e`\n* `keys` `\u003cstring[]\u003e` the fields to extract from the request (`headers`, `method`, `protocol`, `url`, `cookies`, `query_string`, `data`)\n\n**returns**: `object` containing the extracted metadata. It can contain one or more properties named after the `keys` passed as parameter as well as other properties.\n\n**default**: a function that returns an object like this:\n\n```js\n{\n    headers: {},\n    method: 'method,\n    protocol: 'https,\n    cookies: {},\n    query_string: {},\n    data: 'request body as string'\n}\n```\n\n#### extractUserData\n\n\u003e Extract user metadata to attach the `Sentry` event.\n\n**type**: `function`\n\n**parameters**:\n\n* `request` `\u003cFastifyRequest\u003e`\n\n**returns**: `object` containing the extracted metadata.\n\n**default**: a function that looks for a user object in the `request` and returns an object like this:\n\n```js\n{\n    id: '',\n    username: '',\n    email: '',\n}\n```\n\n#### skipInit\n\n\u003e Skip the `Sentry.init` call that initializes the SDK. Useful if working in an environment that already initializes the Sentry SDK.\n\n**type**: `boolean`\n\n**default**: `false`\n\n\n### utils\n\nThe package has a `/utils` export that you can import\n\nwith `CommonJS`\n\n```js\nconst utils = require('@immobiliarelabs/fastify-sentry/utils')\n```\n\nor `ESM`\n\n```js\nimport utils from '@immobiliarelabs/fastify-sentry/utils'\n```\n\nand has a set of utilities used internally that can be useful when implementing your custom functions to pass to the plugin initialization.\n\n#### getTransactionName\n\n\u003e This is the default function used to build the transaction name.\n\n#### extractRequestData\n\n\u003e This is the default function used to extract the request metadata.\n\n#### extractUserData\n\n\u003e The default function used to extract the user metadata.\n\n#### tryToExtractBody\n\n\u003e The default function used to extract the body from the request.\n\n#### extractPathForTransaction\n\n\u003e An internal function used to get the transaction name and source.\n\n#### shouldHandleError\n\n\u003e The default function used to decide if an error event should be sent to Sentry.\n\n#### errorResponse\n\n\u003e The default function used to reply to a request that errored.\n\n## Compatibility\n\n|  | Version        |\n| ---     | ---            |\n| fastify | `\u003e=4.0.0`        |\n| sentry | `^7.0.0`        |\n| Node.js | `\u003e=18` |\n\n## Powered Apps\n\n`fastify-sentry` was created by the amazing Node.js team at [ImmobiliareLabs](https://github.com/immobiliare), the Tech dept of [Immobiliare.it](https://www.immobiliare.it), the #1 real estate company in Italy.\n\nWe are currently using `fastify-sentry` in our products as well as our internal toolings.\n\n**If you are using fastify-sentry in production [drop us a message](mailto://opensource@immobiliare.it)**.\n\n## Support \u0026 Contribute\n\nMade with ❤️ by [ImmobiliareLabs](https://github.com/immobiliare) \u0026 [Contributors](./CONTRIBUTING.md#contributors)\n\nWe'd love for you to contribute to `fastify-sentry`!\nIf you have any questions on how to use `fastify-sentry`, bugs and enhancement please feel free to reach out by opening a [GitHub Issue](https://github.com/immobiliare/fastify-sentry/issues).\n\n## License\n\n`fastify-sentry` is licensed under the MIT license.  \nSee the [LICENSE](./LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmobiliare%2Ffastify-sentry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimmobiliare%2Ffastify-sentry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmobiliare%2Ffastify-sentry/lists"}