# 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](https://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. | Product | What it answers | Backed by | |---|---|---| | **Issues** (Error Monitoring) | "What is broken, where, and for whom?" | Error & exception events, grouped into issues | | **Tracing / Trace Explorer** | "Why is this request slow, and what did it touch?" | Distributed traces (spans across services) | | **Insights** | "How healthy are my HTTP, DB, cache, queue, and frontend operations?" | Aggregated span metrics | | **Session Replay** | "What did the user actually do before it broke?" | DOM/console/network recordings | | **Profiling** | "Which functions burn CPU/wall-time?" | Sampled call stacks | | **Logs** | "What did the app log around this event?" | Structured log records | | **Crons** | "Did my scheduled job run on time?" | Check-in heartbeats | | **Uptime** | "Is my endpoint reachable?" | Periodic uptime probes | | **Releases & Release Health** | "Did this deploy make things better or worse?" | Release metadata, commits, session crash-free rates | | **Dashboards** | "Show me the metrics I care about, together." | Custom widgets over any dataset | | **Alerts** | "Tell me the moment something crosses a threshold." | Issue alerts + metric alerts | | **User Feedback** | "Let users tell me what went wrong." | Feedback widget + linked events | | **Seer** | "What is the root cause and how do I fix it?" | AI analysis over your events and source | > [!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](https://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. ```bash 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: ```python 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: ```javascript 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](https://docs.sentry.io/platforms/) > for your stack. Sentry ships official SDKs for the platforms in the table below. ### Official SDKs | Platform family | Examples | |---|---| | JavaScript / Node | Browser, React, Next.js, Vue, Angular, Svelte, Remix, Node (Express, Fastify, NestJS, Koa, Hono), Bun, Deno, Cloudflare, Electron | | Python | Django, Flask, FastAPI, Starlette, Celery, AWS Lambda, ASGI/WSGI, and 20+ framework integrations | | Mobile | Apple (iOS/macOS, Swift/ObjC), Android (Kotlin/Java), React Native, Flutter/Dart, Capacitor, Cordova, Ionic | | Backend | Java/Kotlin (Spring, Spring Boot, Logback, Log4j2), .NET (ASP.NET, MAUI, WPF, Xamarin), Go (Gin, Echo, Fiber, Iris, net/http), Ruby (Rails, Rack), PHP (Laravel, Symfony), Rust, Elixir | | Games & native | C/C++ (native), Unity, Unreal Engine, Godot, PlayStation, Xbox, Nintendo Switch | | Other | PowerShell, Perl, Clojure | 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: | Action | Effect | |---|---| | **Resolve** | Mark as fixed. Sentry reopens it (a *regression*) if it recurs, optionally only after a chosen release. | | **Archive** (Ignore) | Silence it — forever, until it escalates (volume spikes), or for a set time/occurrence count. | | **Assign** | Give the issue to a team member or team. Can auto-assign via ownership rules / suspect commits. | | **Merge** | Combine several issues you consider the same root cause. | | **Delete & Discard** | Remove and drop all future matching events. | > [!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. ```text is:unresolved environment:production browser:Chrome level:error ``` Useful building blocks: | Token | Meaning | |---|---| | `is:unresolved` / `is:resolved` / `is:ignored` / `is:archived` | Issue status | | `is:assigned` / `is:unassigned` / `assigned:me` / `assigned:[email removed]` | Assignment | | `environment:production` | Environment filter (also a global UI selector) | | `release:1.4.0` / `release:latest` | Release association | | `level:error` (`fatal`, `warning`, `info`, `debug`) | Severity | | `firstSeen:-24h` / `lastSeen:+30d` | Age windows | | `times_seen:>100` | Event-count thresholds | | `user.email:*@acme.com` | Affected-user attributes (supports `*` wildcards) | | `has:replay` / `has:profile` | Events that carry a linked replay/profile | | `transaction:"/checkout"` | Transaction name (performance/trace search) | | `!browser:Safari` | Negation with `!` | 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: | Insights area | Shows | |---|---| | **HTTP / API** | Outbound request throughput, duration, error rate by domain | | **Database / Queries** | Slowest and most-frequent DB queries, time spent | | **Caches** | Hit/miss rates and cache-operation latency | | **Queues** | Job throughput, processing time, backlog | | **Web Vitals** | LCP, FCP, CLS, INP and other frontend page-load metrics | | **Mobile / Screens** | App-start time, slow/frozen frames, screen load | | **Assets / Resources** | JS/CSS/image load performance | | **LLM / AI Agents** | Token usage, latency, and cost for AI-agent spans | > [!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. | Alert type | Fires on | Typical use | |---|---|---| | **Issue alerts** | Conditions about issues/events (a new issue, an issue seen *N* times in *T* minutes, a regression, an issue affecting > *N* users) | "Page me when a new error appears in production." | | **Metric alerts** | A metric crossing a threshold over a window (error rate, transaction duration percentile, failure rate, crash-free rate, custom span metrics) | "Alert when p95 checkout latency > 2 s." | 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**. | Category | Integrations | |---|---| | **Source code / Suspect commits** | GitHub, GitHub Enterprise, GitLab, Bitbucket, Bitbucket Server, Perforce (via Azure DevOps/VSTS too) | | **Issue tracking / project mgmt** | Jira, Jira Server, Azure DevOps (VSTS) | | **Chat & notifications** | Slack, Microsoft Teams, Discord | | **Incident / on-call** | PagerDuty, Opsgenie | | **Deploys / hosting** | Vercel, AWS Lambda | | **AI coding agents** | Claude Code, GitHub Copilot, Cursor (and the generic coding-agent framework) | | **Data forwarding** | Stream events to external data sinks | 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. ```bash 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](https://docs.sentry.io/api/)): | Area | Example endpoints | |---|---| | **Organizations** | `GET /api/0/organizations/{org}/`, `…/projects/`, `…/repos/`, `…/releases/` | | **Projects** | `…/projects/{org}/{project}/issues/`, `…/stats/`, `…/tags/{key}/values/`, `…/user-feedback/`, `…/hooks/` (service hooks) | | **Teams** | `…/teams/{org}/{team}/` and members/projects under it | | **Events / Issues** | List and update issues, fetch tag values, resolve/assign in bulk | | **Releases** | `…/releases/`, `…/releases/{version}/commits/`, `…/files/` (source maps), `…/commitfiles/` | | **Integration platform** | `…/sentry-app-installations/{uuid}/external-issues/` | | **SCIM** | User/group provisioning for SSO-managed orgs | 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. ```bash # 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 `), 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 | Command | What it does | |---|---| | `sentry createuser` | Create an account. `--email`, `--password`, `--superuser/--no-superuser`, `--staff`, `--org-id`, `--no-input`, `--force-update`. | | `sentry createorg --name "Acme" --owner-email [email removed]` | Create an organization (`--slug`, `--no-default-team`). | | `sentry createproject --name api --platform python --organization acme` | Create a project (`--team`). | | `sentry createteam` *(via `sentry django`)* | Team creation is generally done in the UI. | | `sentry config get