Sentry is an open-source application-monitoring platform that captures errors, performance traces, and session replays from your web, mobile, and backend apps in real time, then groups them into actionable issues and alerts your team. To set it up, create a project in Sentry (the hosted SaaS at sentry.io or a self-hosted instance) to get a DSN, install the modern sentry-sdk for your language, and call its init() with that DSN. From then on the SDK reports unhandled exceptions automatically, with no per-line instrumentation.
This guide is the broad, platform-level walkthrough: what Sentry is, its core concepts, SaaS vs self-hosted vs GlitchTip, how to create a project and DSN, and a quick wire-up in Python and JavaScript. One critical 2026 note up front: the old raven / raven-js / raven-python clients are deprecated — every example below uses the unified sentry-sdk family. If you specifically run Django, follow our companion post on monitoring a Django application with Sentry after the setup here.
Key takeaways
- Sentry = errors + performance tracing + session replay in one platform, with grouping, alerting, and release tracking on top.
- A DSN (Data Source Name) is the per-project key the SDK uses to send events; it identifies the project but is not a secret credential.
- Use the unified
sentry-sdk(Python) or the@sentry/*packages (JavaScript) — the legacyravenclients are deprecated and should be replaced. - Choose Sentry SaaS (zero ops) or self-hosted Sentry (
getsentry/self-hostedvia Docker Compose) for full data residency; GlitchTip is a lighter, Sentry-API-compatible open-source alternative. - Best practices: keep
traces_sample_ratelow in production, never send PII by default, and wire releases to your CI so regressions map to the exact deploy.
What is Sentry?
Sentry started as an error-tracking tool and is now a full application performance and reliability platform. Three pillars matter for most teams:
- Error & crash tracking — unhandled exceptions are captured automatically across the stack (server, browser, mobile), enriched with the stack trace, request data, and the trail of events that led up to the crash, then deduplicated into issues.
- Performance monitoring (tracing) — distributed traces and spans show where request time goes: slow endpoints, slow database queries, N+1 patterns, and slow front-end page loads. Sampling controls how much traffic is traced.
- Session replay — a privacy-aware, DOM-level recording of what the user did before an error, so you can reproduce front-end bugs without a repro case.
Unlike a raw log pipeline, Sentry aggregates and prioritises — 10,000 occurrences of the same exception become one issue with a count, a first/last-seen timestamp, and an assignee. That makes it complementary to log search tools such as an ELK stack for parsing your logs, not a replacement for them.
Core Sentry concepts
Learn these terms once and the rest of the product is obvious.
| Concept | What it means |
|---|---|
| Organization / Project | An org holds billing and members; a project maps to one app or service and owns its own DSN and issues. |
| DSN | The Data Source Name — the endpoint + public key the SDK sends events to. Identifies the project; safe to ship in front-end bundles. |
| Issue & grouping | Similar events are fingerprinted and merged into a single issue so you triage problems, not individual events. |
| Breadcrumbs | The timeline of logs, network calls, and UI actions captured before an event, giving you context. |
| Release | A version identifier (often the Git SHA) attached to events so Sentry can flag regressions and suspect commits. |
| Environment | A tag such as production, staging, or development to separate and filter events. |
| Sampling | traces_sample_rate / replaysSessionSampleRate decide what fraction of transactions or sessions are recorded, controlling volume and cost. |
| Alerts | Rules that notify Slack, email, or PagerDuty on new issues, regressions, or threshold breaches. |
Sentry SaaS vs self-hosted vs GlitchTip
Your first decision is where Sentry runs. The hosted SaaS is fastest to start; self-hosting gives you full data residency at the cost of operations; GlitchTip is a slimmer open-source option that speaks Sentry's SDK protocol.
| Aspect | Sentry SaaS (sentry.io) | Self-hosted Sentry | GlitchTip |
|---|---|---|---|
| Ops burden | None — fully managed | High — ~20 containers, you patch & scale | Low — a few containers |
| Data residency | US/EU regions offered | Wherever you host it | Wherever you host it |
| Feature coverage | Full (replay, profiling, cron, dashboards) | Full, but heavier infra | Core error tracking + basic uptime/perf |
| SDK compatibility | Official sentry-sdk / @sentry/* |
Same SDKs | Same SDKs (drop-in DSN swap) |
| Best for | Teams wanting zero maintenance | Strict residency / air-gapped needs | Small teams wanting cheap, simple, self-hosted |
Self-hosting is real infrastructure (Postgres, Redis, Kafka, ClickHouse, workers). If you do not have an SRE function, the SaaS or GlitchTip usually wins. If you self-host anything at scale, our server maintenance services team can run it for you.
Step 1 — Create a project and get your DSN
- Sign in to sentry.io (or your self-hosted instance) and open your organization.
- Click Create Project and pick the platform (Python, Node, React, etc.) — this only tailors the setup snippet; the DSN works for any SDK.
- Name the project after the service it monitors (e.g.
api-gateway,web-app). - Copy the DSN shown on the setup screen. It looks like
https://<public_key>@o123456.ingest.sentry.io/7654321. You can always find it later under Project Settings → Client Keys (DSN).
Store the DSN in an environment variable (e.g. SENTRY_DSN) rather than hardcoding it, so it differs per environment and never leaks into version control.
Step 2 — Install the SDK and initialise (Python)
Install the unified sentry-sdk into your virtual environment. Do not use the old raven package — it is deprecated and unmaintained.
pip install --upgrade sentry-sdkInitialise the SDK once, as early as possible in your app's startup. Pass the DSN plus the four options that make events useful: tracing rate, environment, release, and a PII switch (left off by default).
import os
import sentry_sdk
sentry_sdk.init(
dsn=os.environ["SENTRY_DSN"], # never hardcode the DSN
# Performance: fraction of requests traced (0.0-1.0). Start low in prod.
traces_sample_rate=0.2,
# Profiling: fraction of *traced* transactions that are profiled.
profiles_sample_rate=1.0,
# Tag every event with the deploy environment and the running version.
environment=os.environ.get("APP_ENV", "production"),
release=os.environ.get("GIT_SHA"), # CI sets this to the commit SHA
# Privacy: keep PII (IP, cookies, user data) off unless you have consent.
send_default_pii=False,
)
# Unhandled exceptions are now reported automatically. For handled errors:
try:
risky_operation()
except Exception as exc:
sentry_sdk.capture_exception(exc)Restart the app, trigger an exception, and the issue appears in your Sentry project within seconds. Most web frameworks (Django, Flask, FastAPI, Celery) are auto-instrumented once the SDK is installed — no per-view code needed. For the framework-specific options, our Django + Sentry monitoring guide goes deeper on integrations, Celery, and PII scrubbing.
Step 3 — Wire up the browser (JavaScript)
Front-end errors and slow page loads are reported by the browser SDK. Install @sentry/browser (or @sentry/react, @sentry/vue, etc. for a framework) — the deprecated raven-js client should be removed.
npm install @sentry/browser// sentry.js — initialise once, before the rest of your app loads.
import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN, // DSN is public-safe in the browser
environment: import.meta.env.MODE,
release: import.meta.env.VITE_GIT_SHA,
integrations: [
Sentry.browserTracingIntegration(), // performance / page-load tracing
Sentry.replayIntegration(), // session replay
],
tracesSampleRate: 0.2, // 20% of transactions traced
replaysSessionSampleRate: 0.1, // 10% of sessions replayed
replaysOnErrorSampleRate: 1.0, // always replay sessions that error
});
/**
* Report a handled error with extra context.
* @param {Error} error - the caught error to send to Sentry
* @param {Record<string, unknown>} [context] - extra tags/data
*/
export function reportError(error, context = {}) {
Sentry.captureException(error, { extra: context });
}For React, swap to @sentry/react and wrap your tree in an error boundary so render-time crashes are captured with component stacks.
// App.jsx
import * as Sentry from '@sentry/react';
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()],
tracesSampleRate: 0.2,
});
export default function App() {
return (
<Sentry.ErrorBoundary fallback={<p>Something went wrong.</p>}>
<Routes />
</Sentry.ErrorBoundary>
);
}Self-hosting Sentry with Docker Compose
If you need full data residency or an air-gapped deployment, run the official getsentry/self-hosted stack. It bundles Sentry plus Postgres, Redis, Kafka, and ClickHouse via Docker Compose. Plan for a sizeable host — roughly 16 GB RAM and 4+ CPUs minimum — and a current Docker Compose v2.
# Clone the official self-hosted repo and run the installer.
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
# Check out a stable calendar-versioned release, e.g. 25.x
git checkout 25.5.0
# Interactive installer: builds config, runs DB migrations,
# and prompts you to create the first admin user.
./install.sh
# Start the full stack in the background.
docker compose up -d
# Sentry is now on http://localhost:9000 — put it behind TLS + a reverse proxy.Point any SDK at your instance by using the DSN from its UI — the code above is otherwise identical. If you build and ship your own SDK-instrumented images, host them privately; our walkthrough on setting up a GitLab Container Registry on your own domain covers that. Self-hosting is genuine ops work: back up Postgres and ClickHouse, watch disk for event volume, and keep the stack patched.
Want something lighter? GlitchTip is an open-source, AGPL project that implements Sentry's ingest API, so the same sentry-sdk / @sentry/* clients work — you just swap the DSN. It covers core error tracking (plus basic uptime and performance) with far fewer moving parts than full self-hosted Sentry.
Releases & source maps in CI
Tying events to a release is what turns Sentry from a crash list into a regression detector: each issue shows the version that introduced it and suggests the suspect commit. Create the release and upload artifacts (minified JS source maps for the browser) from your pipeline using sentry-cli.
# In your CI job (set SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT as secrets)
export VERSION=$(git rev-parse --short HEAD)
# 1. Create and associate the release with its commits
sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
# 2. Inject + upload source maps so stack traces de-minify
sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload --release "$VERSION" ./dist
# 3. Finalise the release, then tell Sentry it was deployed
sentry-cli releases finalize "$VERSION"
sentry-cli releases deploys "$VERSION" new -e productionRun these steps as a stage in your existing pipeline — see our guide to continuous integration and delivery with GitLab and Docker for where this fits. Make sure the release value you pass to the SDK (GIT_SHA above) matches the release name you create here, or events will not link to a release.
Best practices
- Never send PII by default. Keep
send_default_pii=False, scrub emails/tokens withbefore_send, and mask text/inputs in session replay. - Sample tracing sensibly. Errors are sent at 100%, but traces are not — start
traces_sample_ratearound0.1-0.2in production and raise it only where you need detail. - Wire releases to CI (above) so every regression maps to a deploy and a suspect commit.
- Tame the noise. Use inbound filters and
ignore_errorsfor browser extensions and bot traffic; resolve and mute issues you cannot action so alerts stay meaningful. - Route alerts to where people look — Slack and email for most teams, PagerDuty for on-call. Alert on new and regressed issues, not every event.
- Set environments (
production,staging) so a flood from staging never pages production on-call.
Sentry vs alternatives at a glance
Feature-only comparison (no pricing — vendor tiers change, so verify current plans on each vendor's site).
| Tool | Error tracking | Performance / APM | Session replay | Self-host option |
|---|---|---|---|---|
| Sentry | Yes | Yes | Yes | Yes (getsentry/self-hosted) |
| GlitchTip | Yes | Basic | No | Yes (lightweight, Sentry-compatible) |
| Rollbar | Yes | Limited | No | No (SaaS) |
| Datadog | Yes (Error Tracking) | Yes (full APM) | Yes (RUM) | No (SaaS) |
| Honeybadger | Yes | Basic (uptime/checks) | No | No (SaaS) |
Sentry's edge is that error tracking, tracing, and replay share one SDK and one issue view, plus a credible self-hosting path. Datadog is broader observability (infra + logs + APM); GlitchTip wins on simple, cheap self-hosting.
Frequently Asked Questions
What is a DSN in Sentry?
A DSN (Data Source Name) is the connection string the SDK uses to send events to a specific Sentry project. It contains the ingest host and a public key, e.g. https://<public_key>@o123456.ingest.sentry.io/7654321. The DSN identifies the project but is not a secret credential — it is designed to be embedded in front-end bundles. You set it via an environment variable and pass it to sentry_sdk.init(dsn=...) or Sentry.init({ dsn }).
Is Sentry free to use?
Sentry is open source, so you can self-host it for free and pay only for the infrastructure you run it on. The hosted SaaS at sentry.io offers a free developer tier with monthly event/quota limits, plus paid tiers for more volume and features — quotas and plans change, so verify the current ones on sentry.io. For a low-cost self-hosted route, GlitchTip is a lighter open-source alternative that uses the same SDKs.
Should I use Sentry SaaS or self-host it?
Use SaaS if you want zero operational overhead and the full feature set (replay, profiling, dashboards) without managing infrastructure. Self-host when you have strict data-residency, compliance, or air-gapped requirements and an SRE function to run roughly 20 containers (Postgres, Redis, Kafka, ClickHouse, workers). If you want simple self-hosting without that weight, GlitchTip is the middle ground.
Is the raven SDK still supported?
No. The legacy raven, raven-python, and raven-js clients are deprecated and no longer maintained. Use the unified sentry-sdk for Python and the @sentry/* packages (e.g. @sentry/browser, @sentry/react, @sentry/node) for JavaScript. They support tracing, profiling, and session replay that the old clients never had — migrate any remaining raven code.
What should I set traces_sample_rate to?
traces_sample_rate controls the fraction of requests Sentry records as performance transactions (0.0 to 1.0). Errors are always sent at 100%, but tracing every request is expensive and noisy. In production, start around 0.1-0.2 (10-20% of traffic) and adjust by volume — raise it for low-traffic critical paths, lower it for high-traffic services. For per-route control, use traces_sampler (a callback) instead of a flat rate.
How is Sentry different from logging or an ELK stack?
Logging and an ELK stack give you a searchable stream of raw events; Sentry aggregates, groups, and prioritises errors — thousands of identical exceptions become one issue with a count, owner, release, and alert. They are complementary: keep your logs for forensic search and audit, and use Sentry as the triage and alerting layer for crashes and performance regressions. Sentry can even attach recent logs as breadcrumbs on each event.