Help Center›Integrations Setup (For Admins)›How to connect the Sentry integration

How to connect the Sentry integration

Last updated October 26, 2026

Who can use this feature?
Admins connect the integration. A developer adds the code to your app. Everyone can see the errors in the timeline and session recordings.

Overview

Sentry tracks the technical errors that happen in your app. When you connect it to Atlas, your support team sees those errors right where they work: in the customer's timeline and inside the session recording where the error happened. Agents no longer need to ask customers for screenshots or steps to reproduce the problem.

Think of it like this:

A customer runs into an error. An action fails in your app or website, and Sentry captures the error.
Your app identifies the customer in both Atlas and Sentry with the same user ID. Atlas links the error to the customer's profile and to the session where it happened.
The customer contacts support. Your agent opens the customer's timeline, sees the "Bug encountered" card and replays the exact moment the error happened.

Setup has two sides: an Admin connects Sentry in Atlas, and a developer adds a few lines of code to your app.

Related articles:
• How to install Atlas on your website or app: Add the Atlas snippet and identify your users.
• How to review customer sessions (session recording): Replay sessions and use the developer tools.
• How to configure session recording settings: Turn on session recording for your workspace.
• How to create and manage customers: Find a customer's timeline.

Key Features

Errors in the customer timeline: Each new Sentry issue a customer runs into appears as a "Bug encountered" card, with how many times it happened, how many users it affected and a "View in Sentry" link.
Errors inside session recordings: Turn on "Show developer tools" and open the "Sentry" tab to see each error with its file, event ID, message and time.
One click to the full error: Click the event ID or "View in Sentry" to open the issue and its stack trace in Sentry.
You choose what Atlas watches: Select the Sentry projects Atlas listens to in "Watched projects".
Read-only access: Atlas asks for read access to your Sentry projects, events and organization.

How the integration works

Five pieces work together. If one is missing, errors won't show up in Atlas.

Piece	Where you set it up	Why it matters
Atlas app in Sentry	Sentry: "Settings > Integrations > Atlas"	Lets Atlas read your Sentry errors.
Watched projects	Atlas: "App Configuration > Integrations > Sentry"	Tells Atlas which Sentry projects to listen to.
Atlas snippet and identify call	Your app's code	Records sessions and tells Atlas who the customer is.
Sentry SDK and setUser	Your app's code	Sends errors to Sentry with the same user ID.
atlasSupport.sessionId tag	Your app's code	Links each error to the exact session recording in Atlas.

Watch the full setup

This demo walks through the whole flow: connecting Sentry, the developer setup, a test customer hitting an error, and what your support team sees in Atlas.

How to connect Sentry to Atlas

Requirements:
• You must be an Admin in Atlas.
• You need the owner, manager or admin role in your Sentry organization to install the app.
• Atlas works with Sentry cloud (sentry.io). Self-hosted Sentry isn't supported.

Part 1: Install the Atlas app in Sentry (Admin)

In Atlas, click the main menu button and select "App Configuration" .
Click "Integrations" and select "Sentry" .
Optionally, click "Instructions" to open Sentry's guide for sending errors to Atlas, and share it with your developers.
Click "Connect to Sentry". Sentry opens the Atlas app page.
If you belong to more than one Sentry organization, check that you're in the right one. Then click "Accept & Install".
Sentry sends you back to Atlas. When the "Watched projects" field appears, the app is installed.
Open "Watched projects", select the Sentry project (or projects) for your customer-facing app, and click "Save". The message "Updated Sentry settings." confirms it.

Important:
Always start from "Connect to Sentry" in Atlas. This way Sentry sends you back to the right Atlas workspace and the installation finishes.

Part 2: Install Atlas in your app and identify users (developer)

Atlas can only link an error to a customer if it knows who that customer is. If Atlas is already installed in your app and you already identify your users, go to Part 3.

In Atlas, go to "App Configuration > Getting Started > Installation" .
Click the copy icon and paste the snippet before the </head> tag on every page where you want the chat widget or session recording. The snippet already includes your workspace's appId.
After the snippet, identify the signed-in user. Use the ID your app gives each user:

window.Atlas.call("identify", {
  userId: user.id,      // the same ID you send to Sentry
  name: user.name,
  email: user.email
});

For all the installation options, see: How to install Atlas on your website or app .

Part 3: Send Sentry errors to Atlas (developer)

In Sentry, go to "Settings > Projects" and open the project you selected in "Watched projects".
Select "Client Keys (DSN)" and click the copy icon next to "DSN". The DSN tells the Sentry SDK where to send your app's errors.
Add Sentry to your app, after the Atlas snippet, with the code below. Paste your DSN and use your own user values:

// 1. Connect the Sentry SDK to your project (paste your DSN)
Sentry.init({ dsn: "https://<key>@o000000.ingest.sentry.io/000000" });
 
// 2. Identify the same user in Sentry
Sentry.setUser({ id: user.id, email: user.email });
 
// 3. Tag every error with the Atlas session ID
Sentry.addEventProcessor((event) => {
  const sessionId = window.Atlas?.recording?.getSessionId();
  if (sessionId) {
    event.tags = { ...event.tags, "atlasSupport.sessionId": sessionId };
  }
  return event;
});

What each part does:

Sentry.init connects the Sentry SDK to your project.
Sentry.setUser identifies the same person in Sentry. Use the same ID you pass to Atlas as userId.
The event processor adds the atlasSupport.sessionId tag with the current Atlas session ID, so the error is linked to the right session recording.

Important:
• Use exactly the same user ID in Atlas (userId) and Sentry (id). If they don't match, the error won't appear in the customer's timeline.
• The tag name must be exactly atlasSupport.sessionId.

Errors from your backend: If your server also reports errors to Sentry, send the Atlas session ID with each request from your web app, and set the same tag on the server:

// In your web app: send the Atlas session ID with each request
const originalFetch = window.fetch;
window.fetch = (input, init = {}) => {
  const headers = new Headers(init.headers);
  headers.set("X-Atlas-Session-Id", window.Atlas?.recording?.getSessionId());
  return originalFetch(input, { ...init, headers });
};

Important:
For more details, see Sentry's guide.

How to see Sentry errors in Atlas

In the customer timeline

Click the main menu button and select "Customers" .
Search for the customer by name or email and open their profile.
In the timeline, find the "Bug encountered" card. It shows the error message, how many times it happened and to how many users.
Click "View in Sentry" to open the full issue in Sentry.

In the session recording

In the customer's timeline, click "Expand sessions" if their recordings are grouped.
Open the session recorded at the same time as the error.
Turn on "Show developer tools" at the bottom right of the player.
Select the "Sentry" tab. Each error shows its "Name", "File", "Event ID", "Message" and "Time".
Click the event ID to open the issue in Sentry, with its stack trace, user and tags.

Important:
An error appears only in the session where it happened. If the "Sentry" tab shows "No data", open another session from the same time as the error.

How to test the integration

Before you rely on it, send a test error and check that it reaches Atlas.

Sign in to your app as a test user, so Atlas and Sentry identify them.
Trigger a test error from your app, for example with this line:
In Sentry, open "Issues", open the new issue and check that "Tags" includes atlasSupport.sessionId and that the user is your test user.
In Atlas, open the test customer's timeline. The "Bug encountered" card appears within a couple of minutes.

Sentry.captureException(new Error("Atlas test error"));

Important:
Atlas adds a card when Sentry creates a new issue. If your test error matches an issue that already exists, Sentry groups it into that issue and you may not see a new card. To test again, change the error message.

How to disconnect Sentry

In Sentry, go to "Settings > Integrations" and open "Atlas".
Click "Uninstall" and then "Confirm".
The app shows "Pending Deletion" for a few minutes, then "Not Installed".

Warning:
After you uninstall the app, new Sentry errors stop appearing in Atlas. To connect again, start from "Connect to Sentry" in Atlas.

FAQs & Troubleshooting

Where do I see the Sentry errors?

In the customer's timeline, as a "Bug encountered" card, and in their session recording, in the "Sentry" tab of the developer tools.

The customer's timeline has no "Bug encountered" card.

Check that the Sentry project is selected in "Watched projects", that the Atlas snippet loads on the page where the error happened, and that your app sends the same user ID to Atlas (identify) and Sentry (setUser). Also check that the error created a new issue in Sentry.

The "Sentry" tab in the session recording shows "No data".

You may have opened a different session. Open the one recorded at the same time as the error. If it still shows no data, check that your Sentry code adds the atlasSupport.sessionId tag (Part 3).

Sentry shows the Atlas app as "Pending".

The installation didn't finish. In Sentry, uninstall the Atlas app, wait until it shows "Not Installed", then connect again from "Connect to Sentry" in Atlas. If it stays pending, contact Atlas support.

Do I need session recording turned on?

To see errors inside session recordings, yes. The timeline card only needs the integration and the user identification.

Can Atlas watch more than one Sentry project?

Yes. Select every project you need in "Watched projects" and click "Save".

Does it work with self-hosted Sentry?

No. The integration works with Sentry cloud (sentry.io).

Is the DSN a secret?

No. Sentry designs the DSN to be used in front-end code. It only allows sending errors to your project.

Was this article helpful?

Table of contents