Sentry User Guide

Sentry is an application-monitoring and debugging platform. Your applications send events — errors, performance traces, session replays, profiles, logs, and health checks — to Sentry through a lightweight SDK, and Sentry turns that raw telemetry into actionable, deduplicated issues with the full context you need to fix them: stack traces, breadcrumbs, the offending release, the affected users, and (with Seer) an AI-suggested root cause and fix.

This guide is for the people who use Sentry day to day — developers instrumenting an application, engineers triaging issues in the web UI, and operators running a self-hosted instance. It covers what each product does, how to drive it, the search and alerting surfaces, the public REST API, and the sentry command-line tool. Deployment architecture, the full configuration reference, and internals live in the companion Admin Guide.

Note

This guide documents the Sentry server (the getsentry/sentry codebase): the Django/React monolith that powers both sentry.io (SaaS) and self-hosted installations. The client SDKs (sentry-python, sentry-javascript, …) live in their own repositories; this guide covers how to wire an SDK to Sentry and what Sentry does with the data, and points to docs.sentry.io for per-language SDK API specifics.

1. What Is Sentry?

Sentry receives telemetry from your applications and helps you detect, trace, and fix problems faster. A single Sentry organization can monitor many projects across many platforms at once.

Sentry is not a single feature — it is a suite of monitoring products that share one event pipeline, one project model, and one UI. You can adopt any subset of them.

Tip

If you are just getting started, you only need Issues. Everything else layers on top of the same projects and SDKs you set up for error monitoring — usually by enabling one or two SDK options.

Core objects

You will see these terms throughout the UI and API:

• Organization — the top-level account boundary. Owns members, teams, projects, billing, and settings. URL slug appears in almost every path (/organizations/{org-slug}/…).
• Team — a group of members. Teams own projects and receive notifications.
• Project — one application or service you monitor. Each project has its own DSN, platform, alert rules, and issue stream.
• DSN (Data Source Name) — the per-project ingest URL/key your SDK uses to send events. Public; safe to ship in client code.
• Event — a single payload Sentry received (one error occurrence, one transaction, one replay, …).
• Issue (a.k.a. Group) — many similar events folded into one entity by Sentry's grouping algorithm. This is what you triage.
• Release — a named version of your code (often a git SHA), used to associate issues with deploys and to compute regression/health data.

2. Quick Start

There are two ways to get a Sentry you can send events to:

Sentry SaaS (sentry.io)

1. Create an account at sentry.io and an organization.
2. Create a project, choosing your platform (e.g. python, javascript-react).
3. Copy the project's DSN from Settings → Projects → [project] → Client Keys (DSN).
4. Install and initialize the SDK (next section).
5. Trigger an error and watch it appear under Issues.

Self-hosted Sentry

Run your own instance with Docker. This is the short path; see the Admin Guide for production deployment.

git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
./install.sh
docker compose up -d

The web UI is served on port 9000 by default. On first boot you create the initial owner account (or use sentry createuser — see §11). Then create a project and copy its DSN exactly as on SaaS.

Important

The self-hosted installer (getsentry/self-hosted) is a separate repository that orchestrates Sentry plus its required services (PostgreSQL, Redis, Kafka, ClickHouse/Snuba, Relay, Symbolicator) via Docker Compose. The getsentry/sentry repository documented here ships the application image and the sentry CLI it runs. Do not attempt to run the full platform from sentry alone.

Send your first event

After installing the SDK for your platform, initialize it with your DSN and trigger an error. A representative Python example:

import sentry_sdk

sentry_sdk.init(
    dsn="https://[email removed]/0",
    # Capture performance traces for 100% of transactions (lower in production).
    traces_sample_rate=1.0,
)

# Trigger an unhandled error to verify the integration.
division_by_zero = 1 / 0

A representative browser/JavaScript example:

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: "https://[email removed]/0",
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
});

Within a few seconds the error appears as a new Issue.

Note

The exact init call, option names, and available integrations differ per SDK. The two snippets above are representative; consult the canonical per-language reference at docs.sentry.io/platforms for your stack. Sentry ships official SDKs for the platforms in the table below.

Official SDKs

The platform picker in the project-creation flow lists every supported platform; the value you choose (e.g. python-django, javascript-nextjs) is the project's platform and tailors the onboarding instructions Sentry shows you.

3. Issues — Error Monitoring

Issues is the heart of Sentry. When your app reports an error, Sentry fingerprints it and folds it together with every other occurrence of the same problem into a single issue, so a crash that happens 10,000 times is one row in your stream, not 10,000.

The issue stream

Open Issues to see the deduplicated list for the selected projects and time range. Each row shows the error type and value, the culprit (function/file), event count, affected-user count, and first/last-seen times.

Common triage actions on an issue:

Tip

Prefer Archive → until it escalates over permanent ignore for noisy-but-real issues. Sentry will resurface them automatically if their volume jumps.

What's inside an issue

Opening an issue gives you the full debugging context for a representative event:

• Stack trace with source context (and source maps / debug files applied, so you see original code, not minified output).
• Breadcrumbs — the trail of events (navigations, clicks, log lines, HTTP calls) leading up to the error.
• Tags — searchable key/value metadata (browser, OS, release, environment, server name, custom tags).
• Context — request data, runtime, device, user.
• Suspect commits — the commit(s) most likely to have introduced the issue, using your linked repository and release commit data.
• Linked replay / trace / profile, when those products are enabled.

Grouping

Grouping is what turns events into issues. Sentry groups by analyzing the stack trace, exception type, and message according to grouping strategies, with a fingerprint you can override:

• Set a custom fingerprint in the SDK to force events together or apart.
• Use Issue Grouping settings (per project) and fingerprint rules / stack-trace rules to tune how frames are weighted.
• Merge issues in the UI when grouping was too aggressive in splitting them.

Warning

Over-broad custom fingerprints (e.g. a constant string) collapse unrelated errors into one giant issue and hide real problems. Fingerprint on the stable, distinguishing part of the error only.

4. Search & Query Syntax

Nearly every product surface (Issues, Traces, Discover, Dashboards, Alerts) uses the same search query syntax: space-separated key:value tokens that are AND-ed together.

is:unresolved environment:production browser:Chrome level:error

Useful building blocks:

Combine free text with tokens; quote values that contain spaces. Search bars autocomplete keys and values, and you can save searches for reuse.

Tip

The environment and time-range selectors at the top of the UI apply on top of your query. If results look empty, widen the time range and check the environment dropdown before debugging the query.

5. Tracing, Trace Explorer & Insights

Enable performance/tracing in the SDK (set a traces_sample_rate) and your app starts sending transactions made of spans — a tree of timed operations (an HTTP request, the DB queries it ran, the cache lookups, the template render, downstream service calls). Spans propagate across services via trace headers, so a single trace can span your frontend, API, and workers.

Trace Explorer

Explore → Traces lets you query raw spans with the search syntax and pivot across them — find the slowest db spans, group by transaction, filter by any tag, and open a full trace view that visualizes the end-to-end waterfall of a request across every service it touched.

Insights

Insights turns spans into curated, per-domain dashboards so you don't have to build queries by hand:

Note

Tracing data powers Insights, the trace view, and span-based alerts. If Insights panels are empty, confirm your SDK has a non-zero traces_sample_rate and is on a recent version that emits spans.

6. Session Replay

Session Replay records a video-like reconstruction of the user's session — DOM mutations, clicks, navigations, console output, and network activity — so you can watch exactly what happened before an error.

• Enable it in the browser/mobile SDK (e.g. replaysSessionSampleRate and replaysOnErrorSampleRate in JavaScript).
• Replays are privacy-first: text and media are masked/blocked by default; you opt specific elements back in.
• From an issue or error event, jump straight to the linked replay to see the user's path to the failure. Conversely, Explore → Replays lists sessions you can filter by URL, error count, browser, and more.

Caution

Review masking before recording production traffic. Although Sentry masks input values and text by default, you are responsible for not un-masking elements that render sensitive data.

7. Crons & Uptime Monitoring

These two products watch things that are not events from your app code.

Crons (scheduled-job monitoring)

Tell Sentry the schedule a job should keep, and have the job send check-ins at start and finish. If a job is late, fails, or never reports, Sentry opens an issue.

• Define a monitor with a cron schedule (crontab or interval), a grace period, and a max runtime.
• Instrument the job to send check-ins (most SDKs offer a decorator/wrapper; you can also hit the check-in API directly).
• Missed, errored, and timed-out runs become alerts like any other issue.

Uptime monitoring

Configure an uptime monitor with a URL and interval; Sentry probes it on a schedule from its infrastructure and alerts you when it goes down or the assertion (status code / body) fails. Uptime checks appear alongside your other monitors and can feed alerts.

8. Releases & Release Health

A release ties issues and health metrics to a specific version of your code.

• Set the release option in the SDK (commonly your git SHA or a semver tag) and an environment.
• Connect a repository integration (GitHub, GitLab, Bitbucket…) and associate commits with each release to unlock suspect commits and commit-aware resolution (resolved in next release).
• Release Health (from session data) reports crash-free sessions / users, adoption, and regressions so you can tell whether a deploy improved or degraded stability.
• Upload source maps (JS) or debug information files (mobile/native) per release so stack traces are de-minified/symbolicated.

Tip

Always send a stable, unique release value per deploy. Without it, regression detection, release health, and "resolve in next release" cannot work.

9. Dashboards, Discover & User Feedback

Dashboards

Build custom dashboards of widgets (time series, tables, big-number, world map, …) over any dataset — errors, transactions/spans, releases, crons. Each widget has its own query and visualization. Dashboards can be shared across the org and filtered by environment and time range. Sentry also ships prebuilt dashboards you can clone and tweak.

Discover / Explore

Discover (and the newer Explore surfaces) is the ad-hoc query tool: pick a dataset, choose columns, filter with the search syntax, group and sort, and save the result as a query or pin it to a dashboard. Use it when no curated view answers your exact question.

User Feedback

Collect feedback directly from your users:

• The feedback widget (a button/embeddable form in your app) lets users describe what went wrong; submissions show up under User Feedback and can link to the related error event.
• You can also attach feedback to a specific event via the SDK after an error.

10. Seer — AI Debugging

Seer is Sentry's AI assistant. Given an issue, Seer analyzes the stack trace, event context, and (when you connect a code repository) your source to produce:

• A plain-language root-cause analysis,
• A concrete suggested fix, and — where enabled — an automated pull request with the proposed change,
• Issue scanning and triage assistance.

Seer is opt-in per organization/project and is configured under Settings → Seer. Repository access (via the GitHub/GitLab integration) dramatically improves the quality of its suggestions because it can read the actual code paths involved.

Note

Seer reads event data and connected source code to do its work. Review your organization's data-sharing and Seer settings (Admin Guide §10) before enabling it on sensitive projects.

11. Alerts & Notifications

Sentry has two complementary alert types.

Building an alert:

1. Go to Alerts → Create Alert and pick the alert type/dataset.
2. Define the conditions/threshold and the time window.
3. Add filters (environment, tags) with the search syntax.
4. Choose actions — who/what gets notified: email, Slack, Microsoft Teams, Discord, PagerDuty, Opsgenie, or a webhook.
5. Set the owner team and save.

The newer Automations / Workflow Engine (under Alerts) lets you build multi-condition, multi-action automations (detectors → conditions → actions) beyond a single rule — for example, route different issue categories to different on-call destinations.

Tip

Scope alerts to environment:production and a specific project/team. Org-wide, environment-less alerts are the most common cause of alert fatigue.

12. Integrations

Integrations connect Sentry to the rest of your toolchain. Configure them under Settings → Integrations.

What integrations unlock:

• Source-code integrations power suspect commits, stack-trace-to-source linking, and Seer's repo access, and let Sentry open PRs.
• Issue-tracking integrations create/link Jira (etc.) tickets from a Sentry issue and sync status both ways.
• Chat integrations deliver alerts to channels and let you resolve/assign/snooze from the message (e.g. Slack actions, /sentry slash commands).
• The Integration Platform (Sentry Apps / internal integrations) lets you build your own integration with a UI component, webhooks, and a scoped token — see §13 and the Admin Guide for the API.

13. Using the Sentry REST API

Sentry exposes a public REST API under the base path /api/0/. Everything the UI does is built on it, and you can automate org/project/release/issue management programmatically.

Authentication

Authenticate with a token in the Authorization: Bearer header:

• Organization auth tokens (Settings → Auth Tokens) — recommended for CI and automation; scoped to an organization.
• Internal integration tokens — for Sentry Apps you build.
• User auth tokens — tied to your account.

curl https://sentry.io/api/0/organizations/{organization_slug}/projects/ \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}"

Note

On self-hosted, replace https://sentry.io with your instance URL. On SaaS, the data-region host matters: the public API server is https://{region}.sentry.io where region is us or de (see your org's data storage location).

Endpoint families

The public API is organized by resource. Representative surfaces (full reference at docs.sentry.io/api):

Conventions:

• Responses are JSON; list endpoints are cursor-paginated via the Link header (rel="next"; cursor=…).
• Filter list endpoints with the same query= search syntax used in the UI.
• The API is rate-limited; honor 429 responses and the Retry-After header.

# List unresolved production issues for a project
curl "https://sentry.io/api/0/projects/{org}/{project}/issues/?query=is:unresolved+environment:production" \
  -H "Authorization: Bearer ${SENTRY_AUTH_TOKEN}"

14. The sentry Command-Line Tool

If you run a self-hosted instance, the sentry CLI is how you administer it. It ships inside the Sentry image and wraps the Django application. Run it inside the running container (e.g. docker compose run --rm web sentry <command>), or directly where Sentry is installed.

This section covers the commands a self-hosted operator-as-user reaches for most. The Admin Guide §8 documents every command group exhaustively.

Everyday operator commands

Starting Sentry services

In production these are run as long-lived processes (the self-hosted compose file wires them up for you), but the commands are:

Important

Run sentry upgrade (which applies migrations) before starting the new version's web/worker processes after an upgrade. The Admin Guide covers the full upgrade and backup/restore procedure.

15. Self-Hosting: What You Need to Know as a User

You do not need to be a platform engineer to run a small self-hosted Sentry, but you should understand its shape (full detail in the Admin Guide):

• Sentry is not a single process. A working install runs the web server, task workers, Kafka consumers, plus PostgreSQL, Redis, Kafka, ClickHouse + Snuba (analytics), Relay (event ingestion), and Symbolicator (native/mobile symbolication). The getsentry/self-hosted Docker Compose project assembles all of this.
• Configuration lives in two files in $SENTRY_CONF (default /etc/sentry): config.yml (YAML options like mail and file storage) and sentry.conf.py (Python/Django settings). Many options are also settable from the UI under Settings.
• A SENTRY_SECRET_KEY (≥ 32 chars) is required; generate it with sentry config generate-secret-key. Changing it invalidates all sessions.
• The default file storage backend is the local filesystem under /data; you can switch to S3.
• Email defaults to a dummy backend (nothing is sent) until you configure SMTP.

Warning

Self-hosted Sentry has real infrastructure requirements (multiple GB of RAM, several services). It is designed for a single organization. For large-scale or multi-tenant needs, Sentry's SaaS exists precisely because running this stack at scale is non-trivial.

16. Troubleshooting

Error: events never appear in the UI

Cause: The SDK can't reach Sentry, the DSN is wrong, or the event was rate-limited/filtered. Solution: Verify the DSN matches the project exactly. Enable SDK debug mode (debug=True / debug: true) and check its console output for transport errors. Confirm the project's Inbound Filters (Settings → Inbound Filters) aren't dropping the event and that you haven't exhausted the project's rate limit/quota. Prevention: Test with a deliberate error right after init, and keep the SDK up to date.

Error: stack traces show minified / unsymbolicated frames

Cause: Source maps (JS) or debug information files (mobile/native) weren't uploaded for the release. Solution: Upload source maps/debug files as part of your build, tagged to the same release value the SDK reports. For JS, use the Sentry bundler plugin or sentry-cli sourcemaps upload. For native/mobile, upload dSYM/ProGuard/debug files. Prevention: Wire artifact upload into CI so every release ships its symbols.

Error: "An issue is resolved" alert/automation does not fire

Cause: A known limitation has been reported where actions on alert rules with the "An issue is resolved" condition may not trigger as expected (getsentry/sentry#116677). Solution: Verify the rule's environment and filters match the resolved issue, and check the alert's activity log. Consider triggering downstream automation on a different condition while this is investigated. Prevention: Test new alert rules with a deliberately resolved test issue.

Issue: PII / emails appear in events despite scrubbing

Cause: Server-side data scrubbing or "Enhanced Privacy" settings did not match the data shape; inconsistent scrubbing of emails has been reported (getsentry/sentry#110838). Solution: Configure both client-side scrubbing (SDK before_send, send_default_pii=False) and server-side data-scrubbing rules (Settings → Security & Privacy). Add custom scrubbing rules for your specific fields. Prevention: Treat PII scrubbing as defense-in-depth — scrub at the SDK and configure server-side rules; never rely on a single layer.

Error: too many events / quota exhausted

Cause: High event volume relative to your plan/quota (or self-hosted storage). Solution: Apply inbound filters, lower traces_sample_rate / replaysSessionSampleRate, set spike protection, and use client-side sampling. Archive noisy issues. On self-hosted, run sentry cleanup and tune retention. Prevention: Sample aggressively in production and filter known-noise events at the SDK.

Issue: self-hosted UI loads but charts/search are empty

Cause: The Snuba/ClickHouse stack or the Kafka consumers aren't running, so aggregated/searchable data is never written. Solution: Confirm the snuba-* services and sentry run consumer … processes are healthy in docker compose ps/logs. Errors may still group (PostgreSQL) while search/stats stay empty if Snuba is down. Prevention: Monitor consumer lag and Snuba health (Admin Guide §9).

17. Frequently Asked Questions

Q: Is Sentry open source? Can I use it commercially? Sentry is source-available under the Functional Source License (FSL-1.1-Apache-2.0). You can read, modify, and self-host it; the license restricts offering it as a competing commercial product, and each version converts to Apache 2.0 two years after release. See LICENSE.md and the Admin Guide §10.

Q: Do I have to self-host, or can I use sentry.io? Either. sentry.io is the managed SaaS (US and EU data regions). Self-hosting runs the same application on your own infrastructure.

Q: What's the difference between an event and an issue? An event is one reported occurrence; an issue is the deduplicated group of similar events. You triage issues, not individual events.

Q: How do I stop a noisy error from paging me without losing the data? Archive the issue (optionally "until it escalates"), or add an inbound filter. Both keep history while silencing notifications; inbound filters also stop counting the event against quota.

Q: Why is my performance/Insights data empty? Tracing must be enabled in the SDK with a non-zero traces_sample_rate. Errors work without it, but spans/transactions (and therefore Insights and the trace view) do not.

Q: How are issues assigned automatically? Through Ownership Rules (path/URL/tag → team/user) and suspect commits (from your repo integration). Configure ownership under Settings → [project] → Ownership.

Q: Can I send custom (non-error) data? Yes — capture messages, set tags/context, add breadcrumbs, and record custom spans/metrics through the SDK API. See your SDK's reference on docs.sentry.io.

Q: How do I integrate Sentry with Slack/Jira/GitHub? Install the integration under Settings → Integrations and authorize it. Chat integrations deliver alerts; source integrations enable suspect commits and PRs; issue trackers create/sync tickets.

Q: What does Seer need to suggest a fix? The issue's event data and, ideally, read access to your source code via a connected GitHub/GitLab integration. With repo access it can analyze actual code paths and even open a PR.

Q: Where do I configure data retention / clean up old events on self-hosted? Use sentry cleanup --days N and configure retention settings; ClickHouse/Snuba handle event storage TTLs. See Admin Guide §9.

Q: Which port is the self-hosted UI on? Port 9000 by default (SENTRY_WEB_PORT). The getsentry/self-hosted compose project typically fronts it with Nginx.