Integrate Sentry with Strapi

These integration guides are not official documentation and the Strapi Support Team will not provide assistance with them.

What Is Sentry?

Sentry is a flight recorder for your application. It captures errors in real time and provides detailed insights into crashes. Sentry offers a comprehensive view of each issue, including full stack traces and essential context.

For Strapi projects built with JavaScript and Node.js, Sentry provides the following features:

• Automatic error capture: It automatically detects uncaught exceptions and API errors.
• Detailed context: Includes OS info, browser details, and API endpoint data.
• Performance metrics: Helps identify and resolve performance bottlenecks.
• Breadcrumb trails: Shows the sequence of events leading to errors.
• Code change links: Identifies the code changes that caused the errors.

What sets Sentry apart is its immediate alerts when problems occur—no more waiting for frustrated user emails. Sentry’s powerful search and filtering tools help you focus on the most critical issues.

For Strapi developers, integrating Sentry fills a crucial gap by shedding light on backend errors that might otherwise go unnoticed. In production environments where you can't simply check the console, Sentry provides essential visibility into issues.

Adding Sentry to your Strapi application allows you to identify and fix issues quickly, improving both your development workflow and user experience.

Why Integrate Sentry with Strapi

Integrating Sentry with Strapi provides continuous monitoring for your application, capturing errors in real-time and delivering comprehensive context for each issue.

With automatic error logging, you will be aware of problems before your users even report them. Every error in your Strapi backend is immediately captured and sent to Sentry, keeping you informed of your application's health.

Each error is accompanied by rich context, including user information, environment details, and the specific actions that triggered the issue. Sentry also creates a timeline of events leading up to each error, known as breadcrumb trails, helping you trace what happened step by step. This makes it easier for developers to resolve complex bugs.

When something breaks, Sentry shows you which code change caused it. The direct link between errors and commits reduces debugging time, allowing you to address problematic changes quickly.

For Strapi applications in production, Sentry serves as a robust monitoring system, providing visibility into live environments without requiring the reproduction of issues locally.

How to Integrate Sentry with Strapi

Setting up Sentry with Strapi gives you comprehensive visibility into your application errors. This section walks you through the entire process, from setup to verification. The steps work for both self-hosted Strapi and can be adapted for Strapi Cloud.

Prerequisites

Before starting, make sure you have:

• Strapi v4 or newer (the v3 plugin is no longer supported)
• Compatible Node.js version
• NPM or Yarn package manager
• Active Sentry account with a project set up
• Your Sentry project's DSN (Data Source Name)
• Permissions to edit your Strapi config files
• Network access from your server to Sentry

Remember to use @strapi/plugin-sentry for Strapi v4 and above, as recommended in the official documentation.

Installation

To integrate Sentry with Strapi, you will need to install the official Sentry plugin for Strapi. Here's how to install the plugin:

1. Add the plugin using your package manager:

yarn add @strapi/plugin-sentry

  or

npm install @strapi/plugin-sentry

2. Get your Sentry DSN from your Sentry dashboard.
3. Store your DSN in environment variables rather than hardcoding it in your files.

The plugin needs configuration before it will start tracking errors.

Configuration

Set up the Sentry plugin by following these steps:

1. Create or edit config/plugins.js with this Sentry config:

module.exports = ({ env }) => ({
  sentry: {
      dsn: env('SENTRY_DSN'),
    },
  },
});

2. These settings control:
   • enabled: Turns the plugin on or off
   • dsn: Connects to your Sentry project
   • sendMetadata: Includes extra debugging context
   • You can add more options for advanced use cases
3. Add your DSN to your .env file:

SENTRY_DSN=https://<your_public_key>@sentry.io/<your_project_id>

4. Restart your Strapi server to apply these changes.

Always follow security best practices with credentials. Check the official docs for more details.

Verification

Check if your setup works correctly:

1. Create a test error:

try {
  // Force an error for testing
  throw new Error('Test Sentry integration');
} catch (error) {
  strapi.plugin('sentry').service('sentry').sendError(error);
}

2. Check your Sentry dashboard for the error.
3. Confirm these details in the dashboard:
   • The error appears in your project
   • Stack trace shows correctly
   • Metadata is included (if enabled)
   • Environment info is present

Common issues include wrong DSN, network problems, or config mistakes in your plugins.js file.

Customizing Your Sentry Integration with Strapi

Fine-tuning your Sentry setup in Strapi transforms basic error-tracking into a powerful diagnostic system. With custom tagging and advanced options, you'll identify issues faster and resolve them before they affect users.

Using Custom Tags

Custom tags work like labels that make your errors searchable and sortable in Sentry. Here's how to add them:

strapi.plugin('sentry').service('sentry').sendError(error, (scope, sentryInstance) => {
  scope.setTag('feature', 'content-manager');
  scope.setTag('api_endpoint', '/api/articles');
  scope.setTag('user_role', ctx.state.user?.role?.name || 'public');
});

These tags help you:

• Group errors by specific content types
• Find issues in particular API endpoints
• See which user roles experience problems

You can add even more context to make debugging easier:

scope.setUser({ id: user.id, username: user.username });
scope.setExtra('request_payload', ctx.request.body);

Advanced Configuration Options

For deeper customization, you can access the raw Sentry instance:

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

This gives you direct access to Sentry's lower-level features. You can also set advanced options in your config/plugins.js:

init: {
  environment: env('NODE_ENV'),
  release: env('RELEASE_VERSION', '1.0.0'),
  tracesSampleRate: 1.0, // For performance monitoring
  maxBreadcrumbs: 50,
}

These settings let you:

• Mark errors with specific environments
• Track issues across different releases
• Monitor performance metrics
• Control how much context gets captured with errors

You can also build custom middleware to add error context at any point in your request flow, which is perfect for global error handling or complex reporting logic.

If you're interested in further enhancing your Strapi application, consider exploring other must-have Strapi plugins that can improve functionality and streamline development.

With these customizations, you will build an error-tracking system that provides you with deep insights into your Strapi application, helping you identify and resolve issues before users encounter them.

An Example Project Integrating Sentry with Strapi

Let's see how Sentry works with Strapi in a real-world scenario. Meet "ShopEase"—a fictional e-commerce platform using Strapi to manage products, users, and orders.

Setting Up Sentry in ShopEase

The ShopEase team added Sentry to their Strapi backend like this:

1. Installed the official plugin:

npm install @strapi/plugin-sentry

2. Set up the configuration in config/plugins.js:

module.exports = ({ env }) => ({
  sentry: {
    enabled: true,
    config: {
      dsn: env('SENTRY_DSN'),
      sendMetadata: true,
      init: {
        environment: env('NODE_ENV'),
        release: 'shopease@1.0.0',
      },
    },
  },
});

3. Added the Sentry DSN to their .env file:

SENTRY_DSN=https://<your_public_key>@sentry.io/<your_project_id>

Custom Error Handling and Tagging

To make error tracking more useful, ShopEase built custom error handling:

1. They created middleware to capture and tag API errors:

module.exports = (config, { strapi }) => {
  return async (ctx, next) => {
    try {
      await next();
    } catch (error) {
      strapi.plugin('sentry').service('sentry').sendError(error, (scope) => {
        scope.setTag('endpoint', ctx.request.url);
        scope.setTag('method', ctx.request.method);
        scope.setUser({ id: ctx.state.user?.id || 'guest' });
      });
      throw error;
    }
  };
};

2. For their order processing system, they added detailed tags:

try {
  // Order processing logic
} catch (error) {
  strapi.plugin('sentry').service('sentry').sendError(error, (scope) => {
    scope.setTag('feature', 'order_processing');
    scope.setTag('order_id', order.id);
    scope.setExtra('order_details', order);
  });
}

Real Issues Identified and Resolved

This setup helped ShopEase catch and fix several major problems:

1. Payment Gateway Timeout: Sentry found errors tagged with feature:payment_processing showing timeouts during high traffic. They added retry logic and optimized their payment gateway code.
2. Inventory Problems: Errors tagged with feature:inventory_update revealed race conditions causing overselling. They fixed it with proper database locking.
3. Login Failures: Errors with endpoint:/api/auth/local tags exposed a bug in password resets, which they quickly patched.

Strapi Open Office Hours

If you have any questions about Strapi 5 or just would like to stop by and say hi, you can join us at Strapi's Discord Open Office Hours, Monday through Friday, from 12:30 pm to 1:30 pm CST: Strapi Discord Open Office Hours.

For more details, visit the Strapi documentation and the Sentry documentation.