Sentry.io
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.
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)
- Go to sentry.io and then click on Get Started
- Next, they ask you to create an account. You can do so using your email address, or you can connect via your account from a git provider. I chose GitHub (but feel free to click on Google or Azure DevOps if you already have such an account). I'm surprised they don't offer you to connect using GitLab or Bitbucket 😲) as I intended to connect my GitHub account at some point anyway, as there are some features like converting an error log into a ticket that I want to try out (I usually try not to connect too many accounts which each other as a breach into one of them could potentially give the attacker access to the services that are linked to it too, but in this case, I chose to because in the next step, we need to connect our GitHub account anyway and allow Sentry.io to create tickets on GitHub for me)
- for a guide about creating a GitHub account, check out my chapter Create a GitHub account (sign up) in the GitHub post
- next, a pop-up window will open, asking you to authorize Sentry.io; there is one request they do, which is called Act on your behalf, this means that Sentry.io will be able to do tasks on your repositories, this is needed so that Sentry.io can, for example, help open / update issues in your repositories
- click on Authorize Sentry.io, and you will get redirected to Sentry.io
- on the next page, they ask us if we already have a Sentry.io account; if you do follow their instructions in the message, however, if, like me, you don't have an account yet, click on New Account
- next, enter a user name for Sentry.io (you can either use your full name, or as I did, use your GitHub username, or use any display name you like, if already or later plan to work in a team, then I recommend you chose a name they will recognize)
- then you need to choose an organization name, and the placeholder of the field says company name; however, even if the name is required, it does NOT mean you can NOT sign up as an individual; organizations in Sentry.io are like organizations on GitHub, they don't solely represent companies but it can be any group you want, as I have no organization on GitHub either I just MY_USER_NAME-projects as name
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
- then check the mandatory terms checkbox
- for the email updates, choose whatever you prefer
- finally click on Continue / Create your Account
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:
- open your Sentry.io account
- in the navigation on the left click on Settings
- on the settings page there is now another navigation on the left, there click on Projects
- now, on the projects page, click on the name of your project
- you are now in the general settings of your project, scroll down a bit until you see the Client Security section
- in that section there is an option called Allowed Domains
- in that field enter all the domains you will use for your project
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:
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
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
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:
- visit Sentry.io and log in
- in the left navigation on the bottom, click on Settings
- then, in the Settings navigation on the left, click on Projects
- click on the project name
- then in navigation on the left, under PROCESSING, click on Inbound Filters
- on that page, there is an option called Filter out events coming from localhost. Either disable or enable that option. When enabled Sentry will filter reports coming from localhost and when disabled it will NOT
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:
- if you are using the sentry domain allowlist feature, meaning you don't just have an asterisk (
*
) set as default value, then you might want to have a look at the Allowed domains filter chapter and make sure the domain making the request is in the allowlist, maybe you are using a regex and the subdomain you are on is not covered by the regex - If you are on localhost, then maybe localhost request are blocked, in this case have a look at the Disable the "reports from localhost" filter chapter, and make sure that localhost is set to enabled
- Have a look at your inbound filters, maybe one of those is excluding the Issues
- Make sure the DSN you are using is correct, make sure the DSN (Sentry client key) that your project is using is correct, eventually it is wrong key from another project, or someone has disabled or even deleted a key that is still in use
- Have a look at the following chapter Using the Sentry.io API to debug issues which will show you how to make quick requests to the Sentry.io API to help you narrow down the cause of the missing Issues
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:
You will, however, need an auth token, which you can get to create a custom integration for your organization, like so:
- to get an auth token, go to "Settings", then in the section "Developer Settings," click on "Custom Integrations"
- then click on "Create New Integration", choose "Create Internal Integration", and click on "Next"
- then add a project name, and then under "Permissions" for "Issue & Event", choose "Read" then click on "Save Changes"
- then, on the Integration page, scroll down and click on "New Token", copy the token (you will need it later to make API requests), and then click on "Done"
- finally, click on save changes
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):
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
To make this feature happen Sentry needs to add a data attributes to components, this does usually not pose a problem except sometimes the Sentry Annotations on third party components will cause an error in those third party tools, like react-three-fiber which do NOT like those extra attributes at all
This means that React component annotations are great unless you use a package like React Three Fiber or setup your project using Vite, then you need to disable the feature
React three fiber (R3F) issue
For now if you use React three fiber (R3F) the only workaround is to turn the Sentry React component annotations option off, by setting the reactComponentAnnotation
variable to false
It is only after I had opened an Issue #13413 in the sentry-javascript repository that I found the Issue #530 (Cannot read properties of undefined (reading 'sentry') when using reactComponentAnnotation) in the sentry-javascript-bundler-plugins repository, which has a comment by one of the Sentry SDK maintainers, they mentioned that they consider adding more options in the future to let you exclude components
However as of now those options are not available yet (we can NOT enable React component annotations and exclude React three fiber), meaning the only option left is to disable the reactComponentAnnotation feature (if you chose to continue using R3F)
Vite issue
There is a similar issue when using Vite and the @sentry/vite-plugin as described in the Issue #492 which (as of dec. 2024) is also still open
Same as R3F, the only solution here is to NOT enable the annotations feature until the problem is fixed