Sentry plugin

✋ Caution

The content of this page has not been updated to Strapi v5 yet.

This plugin enables you to track errors in your Strapi application using Sentry.

By using the Sentry plugin you can:

• Initialize a Sentry instance upon startup of a Strapi application
• Send Strapi application errors as events to Sentry
• Include additional metadata in Sentry events to assist in debugging
• Expose a global Sentry service

Begin by first installing the Sentry plugin, and then configuring the plugin to enable your Strapi application to send events to the Sentry instance.

Installation

Install the Sentry plugin by adding the dependency to your Strapi application as follows:

yarn

yarn add @strapi/plugin-sentry

npm

npm install @strapi/plugin-sentry

Configuration

Create or edit your ./config/plugins.js file to configure the Sentry plugin. The following properties are available:

Property	Type	Default Value	Description
dsn	string	null	Your Sentry data source name.
sendMetadata	boolean	true	Whether the plugin should attach additional information (e.g. OS, browser, etc.) to the events sent to Sentry.
init	object	{}	A config object that is passed directly to Sentry during initialization. See the official Sentry documentation for all available options.

An example configuration:

JavaScript

./config/plugins.js

module.exports = ({ env }) => ({
  // ...
  sentry: {
    enabled: true,
    config: {
      dsn: env('SENTRY_DSN'),
      sendMetadata: true,
    },
  },
  // ...
});

TypeScript

./config/plugins.ts

export default ({ env }) => ({
  // ...
  sentry: {
    enabled: true,
    config: {
      dsn: env('SENTRY_DSN'),
      sendMetadata: true,
    },
  },
  // ...
});

Environment configuration

Using the env utility, you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your production environment:

JavaScript

config/plugins.js

module.exports = ({ env }) => ({
  // ...
  sentry: {
    enabled: env('NODE_ENV') === 'production',
  },
  // ...
});

TypeScript

./config/plugins.ts

export default ({ env }) => ({
  // ...
  sentry: {
    enabled: env('NODE_ENV') === 'production',
  },
  // ...
});

Global Sentry service access

After installing and configuring the plugin, you can access a Sentry service in your Strapi application as follows:

const sentryService = strapi.plugin('sentry').service('sentry');

This service exposes the following methods:

Method	Description	Parameters
sendError()	Manually send errors to Sentry.	error: The error to be sent. configureScope: Optional. Enables you to customize the error event. See the official Sentry documentation for more details.
getInstance()	Used for direct access to the Sentry instance.

Below are examples for each method.

sendError

try {
  // Your code here
} catch (error) {
  // Either send a simple error
  strapi
    .plugin('sentry')
    .service('sentry')
    .sendError(error);

  // Or send an error with a customized Sentry scope
  strapi
    .plugin('sentry')
    .service('sentry')
    .sendError(error, (scope, sentryInstance) => {
      // Customize the scope here
      scope.setTag('my_custom_tag', 'Tag value');
    });
  throw error;
}

getInstance

const sentryInstance = strapi
  .plugin('sentry')
  .service('sentry')
  .getInstance();