# Gatsby | Sentry for Gatsby

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#prerequisites)

You need:

* A Sentry [account](https://sentry.io/signup/) and [project](https://docs.sentry.io/product/projects.md)
* Your application up and running

## [Step 1: Install](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#step-1-install)

### [Install the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#install-the-sentry-sdk)

Run the command for your preferred package manager to add the Sentry SDK to your application:

```bash
npm install @sentry/gatsby --save
```

`@sentry/gatsby` is a wrapper around the `@sentry/react` package, with additional Gatsby-specific functionality. This means that you can import all methods available in the `@sentry/react` package from `@sentry/gatsby`.

### [Register the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#register-the-sentry-sdk)

Register `@sentry/gatsby` in your Gatsby configuration file (typically `gatsby-config.(js|ts)`).

`gatsby-config.(js|ts)`

```javascript
module.exports = {
  plugins: [
    {
      resolve: "@sentry/gatsby",
    },
  ],
};
```

## [Step 2: Configure](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#step-2-configure)

Choose the features you want to configure, and this guide will show you how:

Error Monitoring\[ ]Logs\[ ]Session Replay\[ ]Tracing\[ ]User Feedback

Want to learn more about these features?

* [**Issues**](https://docs.sentry.io/product/issues.md) (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
* [**Tracing**](https://docs.sentry.io/product/tracing.md): Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
* [**Session Replay**](https://docs.sentry.io/product/explore/session-replay/web.md): Get to the root cause of an issue faster by viewing a video-like reproduction of what was happening in the user's browser before, during, and after the problem.
* [**Logs**](https://docs.sentry.io/product/explore/logs.md): Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.

### [Initialize the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#initialize-the-sentry-sdk)

Initialize Sentry as early as possible in your application. For this, create a new file `sentry.config.(js|ts)` in your project root and add the following:

`sentry.config.(js|ts)`

```javascript
import * as Sentry from "@sentry/gatsby";

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/gatsby/configuration/options/#sendDefaultPii
  sendDefaultPii: true,

  integrations: [
    // ___PRODUCT_OPTION_START___ performance
    Sentry.browserTracingIntegration(),
    // ___PRODUCT_OPTION_END___ performance
    // ___PRODUCT_OPTION_START___ session-replay
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_END___ session-replay
    // ___PRODUCT_OPTION_START___ user-feedback
    Sentry.feedbackIntegration({
      // Additional SDK configuration goes in here, for example:
      colorScheme: "system",
    }),
    // ___PRODUCT_OPTION_END___ user-feedback
  ],
  // ___PRODUCT_OPTION_START___ logs

  // Enable logs to be sent to Sentry
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs

  // ___PRODUCT_OPTION_START___ performance
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
});
```

## [Step 3: Add Readable Stack Traces With Source Maps (Optional)](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#step-3-add-readable-stack-traces-with-source-maps-optional)

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your [source maps](https://docs.sentry.io/platforms/javascript/guides/gatsby/sourcemaps.md) to Sentry. The easiest way to do this is by using the Sentry Wizard:

```bash
npx @sentry/wizard@latest -i sourcemaps
```

## [Step 4: Avoid Ad Blockers With Tunneling (Optional)](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#step-4-avoid-ad-blockers-with-tunneling-optional)

You can prevent ad blockers from blocking Sentry events using tunneling. Use the `tunnel` option to add an API endpoint in your application that forwards Sentry events to Sentry servers.

To enable tunneling, update `Sentry.init` with the following option:

```javascript
Sentry.init({
  dsn: "___PUBLIC_DSN___",

  tunnel: "/tunnel",

});
```

This will send all events to the `tunnel` endpoint. However, the events need to be parsed and redirected to Sentry, so you'll need to do additional configuration on the server. You can find a detailed explanation on how to do this on our [Troubleshooting page](https://docs.sentry.io/platforms/javascript/guides/gatsby/troubleshooting.md#using-the-tunnel-option).

## [Step 6: Verify Your Setup](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#step-6-verify-your-setup)

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

### [Issues](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#issues)

To verify that Sentry captures errors and creates issues in your Sentry project, add the following test button to one of your pages:

`index.(jsx|tsx)`

```javascript
<button
  type="button"
  onClick={() => {
    throw new Error("Sentry Test Error");
  }}
>
  Break the world
</button>;
```

Open the page in a browser and click the button to trigger a frontend error.

##### Important

Errors triggered from within your browser's developer tools (like the browser console) are sandboxed, so they will not trigger Sentry's error monitoring.

### [Tracing](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#tracing)

To test your tracing configuration, update the previous code snippet and wrap the error in a custom span:

`index.(jsx|tsx)`

```javascript
<button
  type="button"
  onClick={() => {
    Sentry.startSpan({ op: "test", name: "Example Frontend Span" }, () => {
      throw new Error("Sentry Test Error");
    });
  }}
>
  Break the world
</button>;
```

Open the page in a browser and click the button to trigger a frontend error and trace.

### [View Captured Data in Sentry](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#view-captured-data-in-sentry)

Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?

1. Open the [**Issues**](https://sentry.io/issues) page and select an error from the issues list to view the full details and context of this error. For more details, see this [interactive walkthrough](https://docs.sentry.io/product/sentry-basics/integrate-frontend/generate-first-error.md#ui-walkthrough).
2. Open the [**Traces**](https://sentry.io/explore/traces) page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/sentry-basics/distributed-tracing/generate-first-error.md#ui-walkthrough).
3. Open the [**Replays**](https://sentry.io/explore/replays) page and select an entry from the list to get a detailed view where you can replay the interaction and get more information to help you troubleshoot.
4. Open the [**Logs**](https://sentry.io/explore/logs) page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/explore/logs.md#overview).

## [Next Steps](https://docs.sentry.io/platforms/javascript/guides/gatsby.md#next-steps)

At this point, you should have integrated Sentry into your Gatsby application and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

* Extend Sentry to your backend using one of our [SDKs](https://docs.sentry.io/.md)
* Continue to [customize your configuration](https://docs.sentry.io/platforms/javascript/guides/gatsby/configuration.md)
* Learn how to [manually capture errors](https://docs.sentry.io/platforms/javascript/guides/gatsby/usage.md)

Are you having problems setting up the SDK?

* Find various topics in [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/gatsby/troubleshooting.md)
* [Get support](https://sentry.zendesk.com/hc/en-us/)

## Pages in this section

- [ai-agent-monitoring-browser](https://docs.sentry.io/platforms/javascript/guides/gatsby/ai-agent-monitoring-browser.md)
- [best-practices](https://docs.sentry.io/platforms/javascript/guides/gatsby/best-practices.md)
- [configuration](https://docs.sentry.io/platforms/javascript/guides/gatsby/configuration.md)
- [data-management](https://docs.sentry.io/platforms/javascript/guides/gatsby/data-management.md)
- [enriching-events](https://docs.sentry.io/platforms/javascript/guides/gatsby/enriching-events.md)
- [feature-flags](https://docs.sentry.io/platforms/javascript/guides/gatsby/feature-flags.md)
- [logs](https://docs.sentry.io/platforms/javascript/guides/gatsby/logs.md)
- [metrics](https://docs.sentry.io/platforms/javascript/guides/gatsby/metrics.md)
- [migration](https://docs.sentry.io/platforms/javascript/guides/gatsby/migration.md)
- [profiling](https://docs.sentry.io/platforms/javascript/guides/gatsby/profiling.md)
- [sampling](https://docs.sentry.io/platforms/javascript/guides/gatsby/sampling.md)
- [security-policy-reporting](https://docs.sentry.io/platforms/javascript/guides/gatsby/security-policy-reporting.md)
- [session-replay](https://docs.sentry.io/platforms/javascript/guides/gatsby/session-replay.md)
- [sourcemaps](https://docs.sentry.io/platforms/javascript/guides/gatsby/sourcemaps.md)
- [tracing](https://docs.sentry.io/platforms/javascript/guides/gatsby/tracing.md)
- [troubleshooting](https://docs.sentry.io/platforms/javascript/guides/gatsby/troubleshooting.md)
- [usage](https://docs.sentry.io/platforms/javascript/guides/gatsby/usage.md)
- [user-feedback](https://docs.sentry.io/platforms/javascript/guides/gatsby/user-feedback.md)