Kuzzle Plugin Sentry

This plugin allows to send the errors encountered by Kuzzle to Sentry for further detailed analysis.

Installation

First, you have to get the Sentry DSN URL associated with the project you want to monitor.
Please refer to Sentry documentation to create a new Node.js project and get your DSN.

One you have it, you have to provide the DSN to the plugin using one of the following method.

• SENTRY_DSN environment variable
• plugins.sentry.dsn key in Kuzzle configuration file

Usage

This plugin adds a hook on the request:onError event triggered by Kuzzle each time a request fail.

Each error will be enriched with the authenticated user to allow Sentry to compute the number of user affected by an issue. (See Sentry documentation)

It will send the error to Sentry alongside with other useful informations like:

• input payload
• request context

Finally, is adds a Sentry tag containing the controller and action name to quickly identify related events.

Configuration

You can configure the plugin by using Kuzzle configuration file.

Sentry environment

It's possible to define the Sentry environment to bring even more context to catched errors.

You can either provide the KUZZLE_ENV environment variable or add the following key to the configuration:

 
{
  // kuzzle configuration file
  "plugins": {
    "sentry": {
      "environment": "staging"
    }
  }
}

Ignore errors

You can define errors that will be ignored and thus not send to Sentry.

By default the plugin will only send the PluginImplementationError.

If you add filters manually, then it will send every errors except those matching the filters.

You can filter errors either by status or by id.

Theses filters can be defined in the configuration file:

{
  // kuzzle configuration file
  "plugins": {
    "sentry": {
      "ignore": {
        "ids": [
          "security.token.verification_error",
          "security.token.expired"
        ],
        "statuses": [ 401, 403 ]
      } 
    }
  }
}

Filter sensitive values

Any sensitive information will be filtered in the Sentry report. This include password and authentication tokens.

By default, those values are:

• context.token._id: contain the authentication token
• context.token.jwt: authentication token
• input.jwt: authentication token
• input.body.password: password of the local strategy

You can add other value to be filtered automatically in the sensitiveValues array:

{
  // kuzzle configuration file
  "plugins": {
    "sentry": {
      "sensitiveValues": [
        "input.body.fbkeyid"
      ]
    }
  }
}

Exclude Sentry integrations

You can exclude default Sentry integration by providing their name in the configuration.

{
  // kuzzle configuration file
  "plugins": {
    "sentry": {
      "excludeIntegrations": [
        "Http",
        "Console"
      ]
    }
  }
}

Configuration example

{
  // kuzzle configuration file
  "plugins": {
    "sentry": {
      // DSN
      "dsn": "https://[e-mail]/214284..."
 
      // Sentry environment
      "environment": "staging",
 
      // ignore specific errors
      "ignore": {
        "ids": [
          "security.token.verification_error",
          "security.token.expired"
        ],
        "statuses": [ 401, 403 ]
      },
 
      // Exclude Sentry default integrations
      "excludeIntegrations": [
        "Http",
        "Console"
      ],
 
      // Additional sensitives values to filter before sending the error
      "sensitiveValues": [
        "input.body.fbkeyid"
      ]
    }    
  }
}

Extended API

admin:switch

This plugin also expose an API method in order to enable or disable sending events to Sentry.

JSON payload:

{
  "controller": "sentry/admin",
  "action": "switch",
  "state": "on"
}

HTTP route:

# enable plugin 
curl localhost:7512/_plugin/sentry/switch/on
 
# disable plugin 
curl localhost:7512/_plugin/sentry/switch/off

send:generic

Sends an error to sentry.

// Example usage in another plugin
 
this.context.accessors.sdk.query({
  controller: 'sentry/send',
  action: 'request',
  body: {
    error: new Error('failure'),
    tags: {
      tag1: 'gordon',
      tag2: 'alyx'
    },
    extras: {
      some: 'extra data',
      whatever: 'you want'
    },
    request: // Optional errored request
  }
})

Example of Sentry report