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!
- Installation
- Migrating from version 4
- Usage
- API
- Compatibility
- Powered Apps
- Support & Contribute
- License
Node.js |
fastify |
@immobiliarelabs/fastify-sentry |
---|---|---|
<14 |
3 |
3 |
>14 |
4 |
4 and 5 |
You can install it with npm
# lastest stable version
$ npm i -S @immobiliarelabs/fastify-sentry
# latest development version
$ npm i -S @immobiliarelabs/fastify-sentry@next
or yarn
# lastest stable version
$ yarn add @immobiliarelabs/fastify-sentry
# latest development version
$ yarn @immobiliarelabs/fastify-sentry@next
Please check this migration guide if you are migrating from the version 4 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 theSentry
instancereply.sentryEventId
<string>
: the id of a captured exception, accessible when defining a customerrorResponse
handler in the plugin optionsreply.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
fastify
instance.
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
Sentry
event.
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
Sentry
event.
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: '',
}
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 |
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.