Concepts

Words these docs use for ingest and triage. Skim once after Welcome.

SDK ──(DSN)──► Envelope / Store ──► Event ──► Issue (fingerprint)
                     │
                     └── scoped to a Project under an Organization

What is an organization?

An organization is the tenant. Projects, issues, and settings all sit under it.

Members sign in with email/password or Google OAuth. Dashboard queries use PostgreSQL RLS (app.current_org_id), so you never pass an org id in URLs.

What is a project?

A project is one app or service: frontend, API, worker. It owns DSN keys, retention, and an ingest cap.

Retention is 14 / 30 / 90 days; the default cap is 5000 events/hour. Switching projects changes :projectId in /p/:projectId/…. See Projects.

What is a DSN?

A DSN is the ingest URL for one project. Copy it from Settings → SDK connection.

http://{public_key}@{host}/{project_id}

Local seed example:

http://a1b2c3d4e5f6g7h8i9j0@localhost:8080/550e8400-e29b-41d4-a716-446655440000

Public key: safe in browser bundles
Project id: UUID on ingest routes
Secret: shown once, for server-side and legacy store auth

Revoked keys return 403. DSN keys cannot read issues or fire webhooks.

What is an envelope?

An envelope is POST /api/{project_id}/envelope/ with Content-Type: application/x-sentry-envelope.

POST /api/{project_id}/envelope/
Content-Type: application/x-sentry-envelope

Auth is X-Sentry-Auth or a sentry_key query param. Success is 202 { "id": "<uuid>" }. Legacy store returns the same 202 with JSON (or gzip/zlib). Body cap is 2 MB. Transaction items are discarded; exception events and breadcrumbs are kept.

What is an event?

An event is one occurrence: exception type and value, stack frames, breadcrumbs, tags, optional user.

Events live in monthly partitions. Retention drops old partitions and issue aggregates stay. Dashboard: Events. The HTTP read path needs a session, not a DSN.

What is an issue?

An issue is the group of events that share a fingerprint. The Issues list is the dashboard home.

The default fingerprint is SHA-256 of normalized exception type plus the top in-app stack frame (file + function + line). A custom fingerprint array on the event overrides it. See Issues.

Events that share a fingerprint:

Normalized exception type (or message)
Top in-app stack frame (file + function + line)

What are environment and release tags?

environment and release are event tags you set in Sentry.init. They are not credentials.

Tag	Role
`environment`	Header filter: `production`, `staging`, `local`
`release`	Version string; powers regressions and sourcemap match

What is the spike valve?

A per-fingerprint token bucket, about 100 raw events per minute.

When saturated, Epure still returns 202 and increments the counter, but drops duplicate bodies. The hourly project cap is separate: default 5000 events/hour, then 403 ingest_cap_exceeded. Details: API errors.

FAQ

Why 202 instead of 200?

Accept is non-blocking. Persist and JS/TS demangle run on a Tokio queue after the response. Treat 202 plus { "id": "<uuid>" } as success, then open Issues. If the row is missing, check the environment filter: Verify.

Is a DSN the same as a session?

No. The DSN authenticates ingest only; Issues and Events APIs need a login cookie. DSN headers on /api/v1/* return 401. A session cookie on envelope or store does nothing. See Authentication.

How does grouping work?

Default grouping is SHA-256 of normalized exception type plus the sanitized top in-app frame. Same type and frame land on one issue and the count goes up. An SDK fingerprint overrides it. Merge and split handle stacks that share a cause but differ slightly: Issues.