kuzzle-plugin-sentry v0.2.1
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 variableplugins.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 tokencontext.token.jwt
: authentication tokeninput.jwt
: authentication tokeninput.body.password
: password of thelocal
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://214284...@sentry.io/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
4 years ago