# Concepts

> **For agents:** `get_issue` and `search_issues` return **exact** event and user counts from the issue record; `get_stats`, `query_performance`, and `get_release_health` return **sampled estimates** (treat as ≈). Example: `get_stats(org="acme", project="web", dataset="errors", since=24, interval=60)`.

## Events

An **event** is one item a Sentry SDK sends in an envelope: an error (`event`) or a transaction (`transaction`). Both count as exactly one event on the single meter. Sessions, spans (up to 20 per transaction), breadcrumbs, and client reports are free. Event ids are 32-hex UUIDs (Sentry format); an id seen twice within 24 hours is deduplicated.

Every event is written raw to R2 before ingest acknowledges it, then processed asynchronously: normalized, scrubbed, symbolicated, grouped, and stored as gzipped JSON in R2. R2 is the record of truth for bodies; nothing about an event body lives in the analytics index.

## Issues and fingerprints

An **issue** is a group of events that share a **fingerprint** — a 32-hex hash of the exception type and the ordered in-app frames (or, without a stack, the type and a normalized message). Variable parts such as ids, timestamps, and user data never enter the fingerprint, so `TimeoutError: request 8f3a… timed out` and `TimeoutError: request 91c2… timed out` are one issue. The algorithm is versioned (`v2` today) and the version is hashed in, so an algorithm change never splits existing issues. Details in [Issues](https://docs.bugwatch.io/product/issues.md).

Issues have a **short id** (`#42`, the number in the dashboard URL), a title, a culprit, a status (`unresolved`, `resolved`, `ignored`, `regressed`), and exact `eventCount` / `userCount` counters maintained by a per-project Durable Object and flushed to the control database.

## Releases and environments

A **release** is a version string you register (`create_release`, `sentry-cli releases new`, or implicitly by uploading artifacts) and set as `release` in the SDK. Releases carry an optional commit SHA and URL, a list of **deploys** (environment + time), and artifact bundles. Resolving an issue "in" a release means a later release that reproduces it is a **regression**; an event from the same or an older release is not.

**Environment** is a free-form SDK tag (`production`, `staging`). Alert rules can be scoped to one environment; deploys are recorded per environment.

## Sessions and release health

Mobile and browser SDKs send **sessions** (free). Bugwatch indexes them by release and status — `init`, `exited`, `errored`, `crashed`, `abnormal` — and reports **crash-free rate** = 1 − crashed/init over the last 7 days.

## Exact versus sampled

| Number | Source | Exactness |
|---|---|---|
| Issue event/user counts, first/last seen | Durable Object → D1 | Exact |
| Billing usage, quota, overage | `OrgQuota` Durable Object → D1 `usage_daily` | Exact |
| Charts, time series, throughput, percentiles | Analytics Engine | Sampled estimate (sampling-weighted; `SUM(_sample_interval)` and weighted quantiles) |
| Crash-free rate | Analytics Engine | Sampled estimate |

Analytics Engine keeps roughly three months of data; nightly rollups copy per-issue daily counts into the control database so longer trends survive.

## Tenancy

Organizations own projects, members, tokens, channels, releases, and billing. Projects own DSN keys, issues, alert rules, filters, and the store-IP flag. Every API route is scoped by organization slug; a token belongs to exactly one organization.