@immobiliarelabs/fastify-sentry

Simple fastify plugin to integrates Sentry error reporting into your services

Usage no npm install needed!

<script type="module">
  import immobiliarelabsFastifySentry from 'https://cdn.skypack.dev/@immobiliarelabs/fastify-sentry';
</script>

README

fastify-sentry

release workflow code style: prettier semantic-release npm (scoped) license

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.

Table of contents

Installation

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

Usage

const fastify = require('fastify')();

fastify.register(require('@immobiliarelabs/fastify-sentry'), {
    dsn: '<your sentry dsn>',
    environment: 'production',
    release: '1.0.0',
});

Customization

overriding the allowed status codes

const fastify = require('fastify')();

fastify.register(require('@immobiliarelabs/fastify-sentry'), {
    dsn: '<your sentry dsn>',
    environment: 'production',
    release: '1.0.0',
    allowedStatusCodes: [404],
});

using a custom error handler

const fastify = require('fastify')();

fastify.register(require('@immobiliarelabs/fastify-sentry'), {
    dsn: '<your sentry dsn>',
    environment: 'production',
    release: '1.0.0',
    onErrorFactory: ({ environment, allowedStatusCodes, fastify }) => {
        return (error, request, reply) => {
            reply.send(error);
            if (environment === 'production' && reply.res.statusCode === 500) {
                fastify.Sentry.captureException(error);
            }
        };
    },
});

using Sentry outside the error handler

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 (req, reply) => {
    const user = await getUserFromStorage(req.params.id);
    if (user.blocked) {
        fastify.Sentry.captureMessage('Blocked user tried to get in');
        ...
    } else {
        ...
    }
});

Benchmarks

As for everything, using Sentry comes at a cost:

API

This module exports a plugin registration function.

The exported plugin decorates the fastify instance with a Sentry object and adds a custom errorHandler that reports to Sentry all the errors with a status code that is not in the allowedStatusCodes list.

Configuration options

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

key type description default
environment String Sentry SDK environment. Defaults to local (see environment 'local'
defaultIntegration Boolean Include the default SDK integrations (see node#default-integrations and default-integrations false
autoSessionTracking Boolean Enable automatic tracking of releases health (see health). false
allowedStatusCodes Number[] A list of status code that will not cause a report to Sentry. If you pass a list it not merged with the default one [400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 416, 416, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451]
onErrorFactory Function Custom onError factory function, see onErrorFactory. default factory which generates an handler that reports to Sentry all errors that haven't the status code listed in the allowedStatusCodes list

onErrorFactory(options)

The error handler factory which returns a function that will be passed to fastify.setErrorHandler.

options

Object

  • options.environment: the environment string passed to the plugin options
  • options.allowedStatusCodes: the allowedStatusCodes list passed to the plugin options
  • options.fastify: the fastify instance
returns

Function

Compatibility

Version
fastify >=3.0.0
sentry ^6.13.3

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.