Chris.luChris.lu header image, displaying an 80s style landscape and sunset

Sentry.io

a robot with sentry.io written on his chest that is catching bugs with a huge net

Sentry.io is a cloud-based error monitoring service that helps developers capture and log errors (including stack traces and request information) in real-time (when they occur in production). They support a wide range of languages and frameworks through their "sentry-*" opensource SDKs that are hosted on GitHub (the error logging SDKs for javascript, React, Capacitor, Next.js, and many more have an MIT license, but not all sentry packages do, for example, the self-hosted version of sentry uses a license called FSL that is NOT an OSI-approved license).

Beyond error tracking, Sentry also offers performance monitoring features as well as a feature called Sessions Replays, which lets you capture and then replay the user interactions that happened before the error occurs, making it easier to reproduce an error and more.

Warning

Know that Sentry has open source SDKs but the SaaS service is a paid service. Sentry.io has a (free) Developer plan for developers who want to start a side project or just experiment with the service. The plan includes logs for up to 5000 errors, 10,000 performance metrics, and more. To learn more about the quotas for the free plan or check out the pricing of other plans, I recommend checking out their pricing page.

Next.js 14.x and 15.x tutorials

I have two separate tutorials about Next.js that each have a page dedicated to setting up and configuring Sentry for Next.js by using the Sentry wizard:

Create an account (sign up)

Tip

If your content is located in the EU (or for reasons related to GDPR), you may want to chose to store your Sentry data in the EU, so when asked about your preferred Data Storage Location make sure you chose European Union (EU); This is very important because once selected, your data storage location can't be changed

Next, we have finally arrived on their welcome page. You can either click on Start (which I recommend you do, but more on that in the next chapter) to get a guided tour on how to set up the sentry or your team, or you can click on the link below to skip the onboarding.

Create a Sentry.io project

If you just finished the previous chapter and clicked on Start, then you will have come to a page where you get asked to choose your main framework, else go to your Sentry.io account and on the left, click on Projects and then Create project

Choose whatever framework you like (during onboarding, you can only add one at a time. However, you will later be able to add more if you want. For example, add sentry for a PHP Backend API, sentry for React for your frontend code, and sentry for iOS and Android for your apps, if that's, is your technology stack)

Next, I chose an alert frequency. I kept the default value Alert me on every new issue (you can change this later)

Then you can Name your project and assign a team to it. I again kept the default values.

Finally, click on Create Project

Allowed domains filter

By default Sentry.io will accept reports from whatever domain they originate as long as the DSN is yours, you can however explicitly add domains that are allowed to send in reports, in which case Sentry will check the Origin and Referer headers and exclude reports from domains that you did not add to your allowlist

To specific domains instead of all, use the following steps:

Tip

The field for allowed domains is a textarea, meaning you don't add a comma separated list but instead you add one domain per row, let's assume you want to add the example.com domain to your allowlist as well as two subdomains foo.example.com and bar.example.com, then this would be what your allowlist looks like:

example.com  
*.example.com  

If you deploy on Vercel you might want to add a wildcard for the *.vercel.app domain, which is the domain that vercel uses for branch (preview) deployments

*.vercel.app
example.com
*.example.com

If after adding domains to the list, it will take a few minutes before the filter gets updated, so wait a little bit before testing your Sentry.io requests

Warning

If there is a problem with your allowed domains, then you might start seeing 403 errors (Failed to load resource: the server responded with a status of 403) for requests to sentry.io (or your tunnel URL)

To make sure the allowed domains are not the problem just replace the list with a single asterisk (*) to allow all requests from any domain and check if the error goes away, if that's the case then you know at least what the "real" problem is

Disable / Enable "reports from localhost" (filter)

If you want to disable (or re-enable) the Sentry.io reports from the localhost filter, do this:

Sentry v7 to v8 migration

If you had Sentry v7 already installed in your project and now want to upgrade to Sentry v8, I recommend you use the Sentry migration codemod which will automatize the upgrading process and hence simplify the migration process a lot

Investigation failed request / missing reports

If you have a feeling that something is wrong, you either get 403 responses from Sentry (or your tunnel URL), or you trigger an error but it won't show up, I recommend starting with the following steps:

Using the Sentry.io API to debug issues

When trying to log my CSP reports in Sentry.io, I could see that some reports got dropped, but the stats page did not give me the exact reason.

To find the exact reason why a request was dropped, you can use the Sentry.io API.

To get some data about the events, you can use Curl to make the following request:

curl https://sentry.io/api/0/organizations/{organization_slug}/stats-summary/ \
 -H 'Authorization: Bearer <auth_token>'

You will, however, need an auth token, which you can get to create a custom integration for your organization, like so:

Now that you have your auth token, you can make an API call like this (replace MY_ORGANIZATION with the name of your organization on Sentry.io and replace xxx111 at the end with your actual auth token):

curl 'https://sentry.io/api/0/organizations/MY_ORGANIZATION/stats-summary/?field=sum(times_seen)&statsPeriod=24h' -H 'Authorization: Bearer xxx111'

On Mac / Linux, use the terminal or your favorite command line tool to execute the command. On Windows, I recommend using Git Bash

This will hopefully help you understand if your requests got filtered, were invalid, or if there was another reason why they got dropped.

Sentry React Component Annotation(s) can be problematic

To enable Sentry reactComponentAnnotation configuration option is usually a good idea as it makes reports more readable by using component names instead of long selectors

Issues with Sentry Component Annotations

For the Sentry Component Annotation feature to work, Sentry adds a data-sentry data attribute to the DOM of React components.

This does usually not pose a problem except with some packages that are incompatible. For example if you enable Component Annotations and use @react-three/fiber then you might see the following error (Sentry Issue #530) popping up in your terminal:

TypeError: Cannot read properties of undefined (reading 'sentry')

A similar Issue #492 has impacted vite users

Option 1 (just a workaround): Is to disable the feature by setting the reactComponentAnnotation configuration option to false:

reactComponentAnnotation: {
    enabled: false,
},

Option 2 (only available in Sentry > 9):

The sentry-javascript-bundler-plugins PR #617 has added a new ignoredComponents configuration option, that lets you tell Sentry which components should get ignored, meaning for those components Sentry will not try to add extra attributes to their DOM

reactComponentAnnotation: {
    enabled: true,
    ignoredComponents: ['MY_COMPONENT_WHICH_BREAKS'],
},
Warning

The first sentry-javascript-bundler-plugins version with support for the Sentry ignoredComponents is version 2.23.0.

@Sentry/Next.js v8.45.0 still uses @sentry/bundler-plugin-core / @sentry/webpack-plugin v2.22.7

@Sentry/Next.js v9.0.1 has (@sentry/webpack-plugin) v3.1.2 as dependency, so this is the first version that has the new ignoredComponents feature merged