fastify-sentry

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!

Table of contents

• Installation
• Migration guides
• Usage
  • using Sentry in a route handler
  • Benchmarks
• API
  • Configuration options
    • setErrorHandler
    • shouldHandleError
    • errorResponse
    • getTransactionName
    • extractRequestData
    • extractUserData
    • skipInit
  • utils
    • getTransactionName
    • extractRequestData
    • extractUserData
    • tryToExtractBody
    • extractPathForTransaction
    • shouldHandleError
    • errorResponse
• Compatibility
• Powered Apps
• Support & Contribute
• License

Installation

You can install it with npm

1# lastest stable version
2$ npm i -S @immobiliarelabs/fastify-sentry
3# latest development version
4$ npm i -S @immobiliarelabs/fastify-sentry@next

or yarn

1# lastest stable version
2$ yarn add @immobiliarelabs/fastify-sentry
3# latest development version
4$ yarn add @immobiliarelabs/fastify-sentry@next

Migration guides

Please check these migration guides if you are migrating from an older version of the plugin.

Usage

1const fastify = require('fastify')();
2
3fastify.register(require('@immobiliarelabs/fastify-sentry'), {
4    dsn: '<your sentry dsn>',
5    environment: 'production',
6    release: '1.0.0',
7});

using Sentry in a route handler

1const fastify = require('fastify')();
2
3fastify.register(require('@immobiliarelabs/fastify-sentry'), {
4    dsn: '<your sentry dsn>',
5    environment: 'production',
6    release: '1.0.0',
7});
8
9fastify.get('/user/:id', async function (req, reply) {
10    const user = await getUserFromStorage(req.params.id);
11    if (user.blocked) {
12        this.Sentry.captureMessage('Blocked user tried to get in');
13        ...
14    } else {
15        ...
16    }
17});

You can find more examples of usage in the examples folder :wink:.

Benchmarks

As for everything, using Sentry comes at a cost. You can see the benchmarks here

API

This module exports a plugin registration function.

The exported plugin adds the following decorators:

• fastify.Sentry: a reference to the Sentry instance
• reply.sentryEventId <string>: the id of a captured exception, accessible when defining a custom errorResponse handler in the plugin options
• reply.sentryTransaction: the current request transaction, accessible when enabling tracing in Sentry

and adds a custom error handler that reports to Sentry all the errors that have a 5xx status code.

Configuration options

The plugin extends the standard Sentry options object with the following properties:

setErrorHandler

Attach the default error handler to the fastify instance.

type: boolean

default: true

shouldHandleError

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

errorResponse

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

getTransactionName

Get the request transaction name.

type: function

parameters:

• request <FastifyRequest>

returns: string

extractRequestData

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:

1{
2    headers: {},
3    method: 'method,
4    protocol: 'https,
5    cookies: {},
6    query_string: {},
7    data: 'request body as string'
8}

extractUserData

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:

1{
2    id: '',
3    username: '',
4    email: '',
5}

skipInit

Skip the Sentry.init call that initializes the SDK. Useful if working in an environment that already initializes the Sentry SDK.

type: boolean

default: false

utils

The package has a /utils export that you can import

with CommonJS

1const utils = require('@immobiliarelabs/fastify-sentry/utils')

or ESM

1import 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.

getTransactionName

This is the default function used to build the transaction name.

extractRequestData

This is the default function used to extract the request metadata.

extractUserData

The default function used to extract the user metadata.

tryToExtractBody

The default function used to extract the body from the request.

extractPathForTransaction

An internal function used to get the transaction name and source.

shouldHandleError

The default function used to decide if an error event should be sent to Sentry.

errorResponse

The default function used to reply to a request that errored.

Compatibility

	Version
fastify	>=4.0.0
sentry	^7.0.0
Node.js	>=18

Powered Apps

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.

Support & Contribute

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.

License

fastify-sentry is licensed under the MIT license.
See the LICENSE file for more information.