In our Fastify applications, no matter how good our code is sometimes errors happens, we may need to catch and send them to Sentry for further analysis! This plugin aim to do just that, as easily as possible!
Plug, add your Sentry's DSN and you're good to go!
This 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.
⚠️ Fastify 4 introduced some breaking changes, please refer to this version support table to find what works best for you!
You can install it with npm
# lastest stable version
$ npm i -S @immobiliarelabs/fastify-sentry
# latest development version
$ npm i -S @immobiliarelabs/fastify-sentry@nextor yarn
# lastest stable version
$ yarn add @immobiliarelabs/fastify-sentry
# latest development version
$ yarn add @immobiliarelabs/fastify-sentry@nextPlease check these migration guides if you are migrating from an older version of the plugin.
const fastify = require('fastify')();
fastify.register(require('@immobiliarelabs/fastify-sentry'), {
dsn: '<your sentry dsn>',
environment: 'production',
release: '1.0.0',
});const fastify = require('fastify')();
fastify.register(require('@immobiliarelabs/fastify-sentry'), {
dsn: '<your sentry dsn>',
environment: 'production',
release: '1.0.0',
});
fastify.get('/user/:id', async function (req, reply) {
const user = await getUserFromStorage(req.params.id);
if (user.blocked) {
this.Sentry.captureMessage('Blocked user tried to get in');
...
} else {
...
}
});You can find more examples of usage in the examples folder 😉.
As for everything, using Sentry comes at a cost. You can see the benchmarks here
This module exports a plugin registration function.
The exported plugin adds the following decorators:
-
fastify.Sentry: a reference to theSentryinstance -
reply.sentryEventId<string>: the id of a captured exception, accessible when defining a customerrorResponsehandler in the plugin options -
reply.sentryTransaction: the current request transaction, accessible when enabling tracing inSentry
and adds a custom error handler that reports to Sentry all the errors that have a 5xx status code.
The plugin extends the standard Sentry options object with the following properties:
Attach the default error handler to the
fastifyinstance.
type: boolean
default: true
Decide if the error should be sent to
Sentry
This function is called in the default error handler that the plugin adds.
type: function
parameters:
-
error<FastifyError> -
request<FastifyRequest> -
reply<FastifyReply>
returns:
boolean: true if the error should be sent, false otherwise.
default: a function that returns true if the status code of the error is 5xx
Custom handler to respond the client.
This 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.
type: function
parameters:
-
error<FastifyError> -
request<FastifyRequest> -
reply<FastifyReply>
returns: void
Get the request transaction name.
type: function
parameters:
-
request<FastifyRequest>
returns: string
Extract request metadata to attach the
Sentryevent.
type: function
parameters:
-
request<FastifyRequest> -
keys<string[]>the fields to extract from the request (headers,method,protocol,url,cookies,query_string,data)
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.
default: a function that returns an object like this:
{
headers: {},
method: 'method,
protocol: 'https,
cookies: {},
query_string: {},
data: 'request body as string'
}Extract user metadata to attach the
Sentryevent.
type: function
parameters:
-
request<FastifyRequest>
returns: object containing the extracted metadata.
default: a function that looks for a user object in the request and returns an object like this:
{
id: '',
username: '',
email: '',
}Skip the
Sentry.initcall that initializes the SDK. Useful if working in an environment that already initializes the Sentry SDK.
type: boolean
default: false
The package has a /utils export that you can import
with CommonJS
const utils = require('@immobiliarelabs/fastify-sentry/utils')or ESM
import utils from '@immobiliarelabs/fastify-sentry/utils'and has a set of utilities used internally that can be useful when implementing your custom functions to pass to the plugin initialization.
This is the default function used to build the transaction name.
This is the default function used to extract the request metadata.
The default function used to extract the user metadata.
The default function used to extract the body from the request.
An internal function used to get the transaction name and source.
The default function used to decide if an error event should be sent to Sentry.
The default function used to reply to a request that errored.
| Version | |
|---|---|
| fastify | >=4.0.0 |
| sentry | ^7.0.0 |
| Node.js | >=18 |
fastify-sentry was created by the amazing Node.js team at ImmobiliareLabs, the Tech dept of Immobiliare.it, the #1 real estate company in Italy.
We are currently using fastify-sentry in our products as well as our internal toolings.
If you are using fastify-sentry in production drop us a message.
Made with ❤️ by ImmobiliareLabs & Contributors
We'd love for you to contribute to fastify-sentry!
If you have any questions on how to use fastify-sentry, bugs and enhancement please feel free to reach out by opening a GitHub Issue.
fastify-sentry is licensed under the MIT license.
See the LICENSE file for more information.