> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Sentry

> Reuse your existing Sentry SDK for Squasher error events by updating its DSN and disabling Sentry transaction sampling.

## Connect a Sentry organization

Use the Sentry App connection when you want to keep Sentry active while Squasher receives issue
events and reads selected incident context.

1. In Squasher, open **Integrations > Sentry** and select **Install Sentry App**.
2. Select the Sentry organization and projects to connect.
3. Approve read access for organizations, projects, teams, and events.
4. Use **Verify** to check the saved installation and webhook configuration.

The Sentry App must be registered and available to the customer organization. Squasher verifies
signed Sentry webhooks, de-duplicates deliveries, and marks the connection for repair when an
installation is removed.

**Verify** does not create a Sentry issue. Credential-gated live checks use a dedicated Sentry test
organization during release verification.

<Warning>
  Disconnecting in Squasher removes the stored grant and stops Squasher from processing new Sentry
  events. Sentry does not provide a public API that lets Squasher uninstall one organization
  installation. To stop Sentry from sending the installation webhooks, also uninstall the Squasher
  Sentry App in your Sentry organization settings.
</Warning>

The connected agent operations are typed, read-only Sentry actions. They do not expose a general
Sentry HTTP client. Use the DSN migration below when you want to send SDK errors directly to Squasher
instead of keeping the Sentry project as the event source.

***

Squasher is **compatible with Sentry SDK error events**. You can keep using your existing `@sentry/node`, `sentry-python`, `sentry-go`, `sentry-ruby`, or any other official Sentry SDK and point its error traffic at Squasher.

No new error SDK or capture-call rewrite is required. Update the DSN, disable Sentry transaction sampling if you enabled it, and your errors flow to Squasher with AI triage included on every plan.

## How It Works

Sentry SDKs send error data to a configurable endpoint using the [Sentry envelope protocol](https://develop.sentry.dev/sdk/foundations/transport/envelopes/). Squasher implements the protocol's `event` envelope item for errors and messages.

1. **Keep your Sentry SDK** installed as-is
2. **Change the DSN** to point at `ingest.squasher.ai`
3. **Disable Sentry transaction sampling** and send APM telemetry through OpenTelemetry
4. **Errors flow to Squasher** — grouped, triaged by AI, and ready in your dashboard

## The DSN

Your Squasher-compatible DSN looks like this:

```
https://YOUR_API_KEY@ingest.squasher.ai/YOUR_PROJECT_ID
```

| Part              | Value                                        | Where to find it                                                              |
| ----------------- | -------------------------------------------- | ----------------------------------------------------------------------------- |
| `YOUR_API_KEY`    | Your Squasher API key (starts with `sq_pk_`) | [Dashboard > Settings > API Keys](https://app.squasher.ai/dashboard/settings) |
| `YOUR_PROJECT_ID` | Your Squasher project UUID                   | [Dashboard > Settings](https://app.squasher.ai/dashboard/settings)            |

<Warning>
  Use an **Ingest-only** API key for the DSN. This key can only send events — it cannot read your
  data or manage your project. This is safe to include in client-side code, just like Sentry's
  public key.
</Warning>

## Quick Start

<Tabs>
  <Tab title="Node.js">
    No package changes needed. Just update your `Sentry.init()`:

    ```typescript theme={null}
    import * as Sentry from "@sentry/node";

    Sentry.init({
      // Before: dsn: "https://abc123@o1.ingest.sentry.io/456"
      dsn: "https://sq_pk_your_key@ingest.squasher.ai/your-project-id",
      // Sentry transaction items are not ingested; send APM data with OTLP.
      tracesSampleRate: 0,
    });
    ```

    That's it. All `Sentry.captureException()` and `Sentry.captureMessage()` calls now send to Squasher.
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import sentry_sdk

    sentry_sdk.init(
        # Before: dsn="https://abc123@o1.ingest.sentry.io/456"
        dsn="https://sq_pk_your_key@ingest.squasher.ai/your-project-id",
        # Sentry transaction items are not ingested; send APM data with OTLP.
        traces_sample_rate=0.0,
    )
    ```

    Works with Django, Flask, FastAPI, Celery — any Sentry Python integration.
  </Tab>

  <Tab title="Browser (JavaScript)">
    ```typescript theme={null}
    import * as Sentry from "@sentry/browser";

    Sentry.init({
      dsn: "https://sq_pk_your_key@ingest.squasher.ai/your-project-id",
      tracesSampleRate: 0,
    });
    ```

    Also works with `@sentry/react`, `@sentry/vue`, `@sentry/angular`, and `@sentry/svelte`.
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import "github.com/getsentry/sentry-go"

    func main() {
        sentry.Init(sentry.ClientOptions{
            // Before: Dsn: "https://abc123@o1.ingest.sentry.io/456"
            Dsn: "https://sq_pk_your_key@ingest.squasher.ai/your-project-id",
            TracesSampleRate: 0.0,
        })
        defer sentry.Flush(2 * time.Second)
    }
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'sentry-ruby'

    Sentry.init do |config|
      # Before: config.dsn = 'https://abc123@o1.ingest.sentry.io/456'
      config.dsn = 'https://sq_pk_your_key@ingest.squasher.ai/your-project-id'
      config.traces_sample_rate = 0.0
    end
    ```

    Works with Rails, Sidekiq, and any Sentry Ruby integration.
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    \Sentry\init([
        // Before: 'dsn' => 'https://abc123@o1.ingest.sentry.io/456'
        'dsn' => 'https://sq_pk_your_key@ingest.squasher.ai/your-project-id',
    ]);
    ```

    Works with Laravel, Symfony, and plain PHP.
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import io.sentry.Sentry;

    Sentry.init(options -> {
        // Before: options.setDsn("https://abc123@o1.ingest.sentry.io/456");
        options.setDsn("https://sq_pk_your_key@ingest.squasher.ai/your-project-id");
        options.setTracesSampleRate(0.0);
    });
    ```

    Works with Spring Boot, Android, and any Sentry Java integration.
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    SentrySdk.Init(options =>
    {
        // Before: options.Dsn = "https://abc123@o1.ingest.sentry.io/456";
        options.Dsn = "https://sq_pk_your_key@ingest.squasher.ai/your-project-id";
        options.TracesSampleRate = 0.0;
    });
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import * as Sentry from "@sentry/react-native";

    Sentry.init({
      dsn: "https://sq_pk_your_key@ingest.squasher.ai/your-project-id",
      tracesSampleRate: 0,
    });
    ```
  </Tab>
</Tabs>

## What Gets Captured

Squasher extracts all the error data from Sentry envelopes:

| Sentry Feature                          | Squasher Support                                                              |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| `captureException()`                    | Full support — exception type, message, stack trace                           |
| `captureMessage()`                      | Full support — message text and level                                         |
| Stack traces                            | Full support — filename, function, line/col, source context, in-app marking   |
| Chained exceptions                      | Full support — cause chains preserved (most recent used for grouping)         |
| Breadcrumbs                             | Preserved as bounded structured JSON, including navigation, HTTP, and console |
| User context                            | Full support — id, email, username, IP address                                |
| Request context                         | Full support — URL, method, headers                                           |
| Tags                                    | Object and pair-array formats; filter with `sentry.tag.<key>`                 |
| Extra data                              | Preserved as bounded JSON in `sentry.extra_json`                              |
| Release tracking                        | Full support — release version used for source map resolution                 |
| Environment                             | Full support — production, staging, etc.                                      |
| Contexts (OS, browser, runtime, device) | Preserved as JSON and mapped to OpenTelemetry resource attributes             |
| Exception mechanism (handled/unhandled) | Mapped to `exception.mechanism.*` attributes                                  |
| SDK info                                | Mapped to `telemetry.sdk.name` and `telemetry.sdk.version`                    |

<Note>
  Squasher applies the same kind of safety bounds as Sentry: messages, tag keys and values,
  breadcrumbs, stack frames, contexts, and extra data are capped before storage. This prevents a
  malformed event from creating unbounded ClickHouse attributes while preserving the newest
  breadcrumbs and both ends of long stack traces. The complete envelope body is limited to 1 MiB.
</Note>

## What's Different (and Better)

| Feature              | Sentry                  | Squasher                                 |
| -------------------- | ----------------------- | ---------------------------------------- |
| **AI triage**        | Paid add-on             | Included on every Squasher plan          |
| **AI auto-fix PRs**  | Not available           | Available on Team and above              |
| **Error grouping**   | Built-in fingerprinting | Same fingerprinting + AI context         |
| **Transactions/APM** | Full APM suite          | Not supported (error monitoring focused) |
| **Session replay**   | Available               | Available                                |
| **Cron monitoring**  | Available               | Not supported                            |

Squasher is focused on **developer-first incident debugging** with AI, replay, logs, and uptime context in one workflow. If you use Sentry mainly for error monitoring and still need other products for the rest of the incident story, Squasher is built to consolidate that stack.

## Supported Sentry SDK Versions

| Platform                                             | Minimum Version |
| ---------------------------------------------------- | --------------- |
| JavaScript (`@sentry/node`, `@sentry/browser`, etc.) | 7.0.0           |
| Python (`sentry-sdk`)                                | 2.0.0           |
| Ruby (`sentry-ruby`)                                 | 4.0.0           |
| Java / Android (`sentry-java`)                       | 3.0.0           |
| Cocoa / iOS / macOS (`sentry-cocoa`)                 | 6.0.0           |
| .NET (`Sentry`)                                      | 3.0.0           |
| PHP (`sentry/sentry`)                                | 4.0.0           |
| Go (`sentry-go`)                                     | 0.1.0           |
| React Native (`@sentry/react-native`)                | 3.0.0           |

<Note>
  These versions correspond to Sentry SDKs that use the [envelope
  protocol](https://develop.sentry.dev/sdk/foundations/transport/envelopes/). Older SDKs that use
  the deprecated `/store/` endpoint are not supported.
</Note>

## Source Maps

If you're using source maps with Sentry, you can upload them to Squasher using our API:

```bash theme={null}
# Upload source maps for a release
curl -X POST "https://api.squasher.ai/v1/projects/YOUR_PROJECT_ID/sourcemaps" \
  -H "x-squasher-key: sq_pk_your_admin_key" \
  -F "release=your-release-version" \
  -F "files=@dist/app.js.map"
```

Squasher will automatically resolve minified stack traces against your uploaded source maps, just like Sentry does.

<Note>
  Source map uploads require an API key with `sourcemaps:write` permission, separate from the
  ingest-only key used in your DSN.
</Note>

## Running Both During Migration

You can send errors to both Sentry and Squasher simultaneously during migration. Most Sentry SDKs don't support multiple DSNs natively, but you can use a tunnel or proxy approach:

1. **Run Squasher alongside Sentry** for a week to verify parity
2. **Compare grouped issues** in both dashboards
3. **Switch the DSN** once you're confident

For an error-only Sentry setup, the DSN is the only setting you need to change. If anything goes wrong, restore the previous DSN.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to remove the Sentry SDK?">
    No. You keep the Sentry SDK installed. You're just changing where it sends data. Think of it like changing the database URL — same driver, different destination.
  </Accordion>

  <Accordion title="Will my Sentry integrations still work?">
    All Sentry SDK integrations (Express, Django, Flask, Rails, etc.) continue to work. They capture
    errors using the SDK's hooks. Sentry performance integrations and transaction envelope items are
    not part of this compatibility endpoint.
  </Accordion>

  <Accordion title="What about Sentry performance monitoring?">
    The Sentry-compatible endpoint ingests `event` envelope items only; it does not ingest Sentry
    `transaction` items. Leave Sentry performance tracing disabled (`tracesSampleRate: 0` in
    JavaScript SDKs, or the equivalent setting in other SDKs). Send traces, spans, and performance
    metrics to Squasher through the OpenTelemetry integration instead.
  </Accordion>

  <Accordion title="Is my API key safe in client-side code?">
    Yes, if you use an **Ingest-only** API key. This key can only send error events — it cannot read
    data, manage projects, or access any other resources. This is the same security model as Sentry's
    public DSN key.
  </Accordion>

  <Accordion title="What if I use sentry-cli for releases?">
    Squasher has its own source map upload API. You'll need to update your CI/CD pipeline to upload source maps to Squasher instead of (or in addition to) Sentry.
  </Accordion>
</AccordionGroup>

## Agent handoff

```text theme={null}
Migrate Sentry SDK error traffic to Squasher for project <project_id>. Change the DSN or tunnel destination, disable Sentry transaction sampling, upload matching source maps for the same release, compare one known error group, and ask before removing Sentry-specific alerting or release steps.
```