Errors

What it is

An app is one program that sends errors, made under Apps with its own keys. Events come from any Sentry SDK, @statoss/sdk or the Python statoss package; Send errors has each way in. An event is an error, thrown or caught, or a message.

Issues lists the events grouped, Explore searches single events, Releases lists what each release brought, and Dashboards holds the team's own charts. Passwords, tokens, cookies, keys and card numbers are stored as [Filtered]. A user's IP address is kept only when the event or a browser SDK sends one. Transactions, spans, sessions, replays, profiles and attachments are taken and not stored.

Issues

An issue is the events that group together, numbered per app as WEB-12. Its page has the latest event with its stack, breadcrumbs and tags, and why its events grouped.

• The tabs are Unresolved, For review (new or regressed in the last 7 days and not yet reviewed), Regressed, Archived and Resolved.
• An issue can be resolved, resolved in the next release, archived until a date or for good, assigned, commented on, and merged with others.
• An event after an issue was resolved reopens it as regressed.
• Priority follows the level until someone sets it: error and fatal are high, warning medium, the rest low.

Grouping

The first of these that applies decides an event's issue:

1. The SDK's fingerprint, when it sends one; {{ default }} in it stands for the rest of this list.
2. The exceptions' types and their in-app frames, each as file or module and function, without line numbers.
3. With no in-app frames, every frame that names a function.
4. With no frames, the exception's type and value.
5. A message: its template when the SDK sends one, else its text.

File names lose their query and hashes (main.8f3a2b1c.js reads main.js), and numbers, ids, email addresses and URLs are taken out of values. Source maps are applied first, so the same error from two builds lands in one issue.

Alert rules

On Hobby and Pro, an app's alert rules open on-call alerts, routed, repeated and escalated as any source's are. An app holds up to 20 rules. A rule has:

• When: a new issue, a regression, an escalation (an hour with at least 50 events and 10 times the issue's hourly average over the week before), or N events in 1, 5, 15, 60 or 1,440 minutes.
• If: the issue's priority, the event's level, environment, release, tags, and the issue's category.
• How often, per issue: once per release, at most every 30 minutes, at most every hour, at most once a day or at most once a week. A regression alerts once whatever the release.
• Then: the page's destinations or its own, an escalation policy (Pro), or nobody paged.

Each app starts with one rule, New and regressed issues: new and regressed high-priority issues, once per release, to the page's destinations. Resolving an issue's alert resolves the issue, and resolving or archiving the issue resolves its alerts. An issue can open an incident, internal by default.

On Free, new and regressed high-priority issues are emailed to the team's owner instead, once per release, up to 25 emails a month; issues found together go in one email. Each app's page has a switch for them.

Releases

A release exists once an event names it, from the SDK's release option, or once sentry-cli or the StatOSS CLI makes it. Releases, under Issues, lists each with its app, first and last seen, events, new issues, regressions, and the deploy marker of the same version.

"Resolve in the next release" keeps an issue open until a newer release of its app reports in without its events; it is then resolved in that release. Later events from an older release leave it closed.

Source maps

Minified JavaScript frames are mapped back to source before events are grouped, by the debug ID written into each file and its map. @statoss/sdk and Sentry's JavaScript SDKs send the debug IDs. Upload the maps with a write API key, from sentry-cli with the settings on Moving from Sentry:

sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload ./dist
sentry-cli releases new [email protected]
sentry-cli releases finalize [email protected]

Or from the StatOSS CLI, which adds the debug IDs itself and reads the key from STATOSS_API_KEY:

npx @statoss/cli sourcemaps upload ./dist --app web --release [email protected]
npx @statoss/cli releases new [email protected] --app web
npx @statoss/cli releases deploy [email protected] --app web --env production

• A deploy recorded either way is a deploy marker on each page of the release's apps.
• The app's page lists its bundles. An event that came before its maps stays as it came.
• A bundle is 64 MB at most. A team uploads up to 512 MB a day and keeps up to 1 GB of maps; maps are kept 90 days.

Levels, categories and fields

Each app has its own levels, categories and fields, set on its page under Levels, categories and fields. An event names them with two tags, statoss.level and statoss.category; its Sentry level stays the nearest of the five, so other tools read it as before. Values not seen before show as seen, and can be kept, renamed, recoloured, merged or hidden. A change reaches old events at once.

• A level ranks as fatal, error, warning, info, debug or trace, which sets its issues' priority and their alerts' severity.
• A category has a label, a colour, an order, an owner, and can be hidden.
• A field is a tag key with a label, a type (text or number), a unit, and whether it is a filter in Explore. Any field can be searched as key:value on Issues and in Explore.
• Rules sort events into a level or a category by a tag, the logger, the exception type, the culprit, the title or the message: is, starts with, or contains. An event's own tags win.
• An app holds up to 50 levels, 200 categories, 300 fields and 50 rules.

With @statoss/sdk the schema lives in code, and a wrong name fails to compile:

import { defineSchema, init } from "@statoss/sdk";

const schema = defineSchema({
  levels: { "payment-failed": { like: "error", label: "Payment failed" } },
  categories: { billing: { label: "Billing" } },
  fields: { route: { label: "Route", filterable: true } },
});

const statoss = init({ dsn: process.env.STATOSS_DSN, schema });
statoss.captureException(err, {
  level: "payment-failed",
  category: "billing",
  fields: { route: "/pay" },
});

With a Sentry SDK, set the tags:

Sentry.captureException(err, {
  tags: { "statoss.level": "payment-failed", "statoss.category": "billing" },
});

npx @statoss/cli schema shows what the code's schema would change on the server, and --apply applies it.

Limits

• The month is the calendar month in UTC, counted across the team's apps. Past it, events are refused with 429 until the month ends.
• An app may use half of the team's month unless its share is set from 1% to 100% under its Settings; past it, 429 for that app until the month ends, while the team's other apps go on.
• A key sends up to 1,200 events a minute, or less where its rate is set from 10 up; past it, 429. Feedback and cron check-ins have a separate bucket of the same size per key.
• A key can be limited to some websites: a request from another gets 403. A key in a web page is public, so Send errors has the three settings for it.
• A request is at most 8 MiB, before and after decompression. An event over 1 MiB is dropped.
• Strings are cut at 8 KiB, a stack keeps 250 frames, and an event its last 100 breadcrumbs.

API and MCP

The API has apps and their keys, issues, events, releases, source map bundles, alert rules, the schema and dashboards under /api/v1. A read key reads; changes need a write key. Merges and removals answer with what they would do until the request says "confirm": true.

The keyed MCP has the same as tools, such as list_issues, get_issue, update_issue, merge_issues, search_events, get_event, list_releases, list_sourcemaps, create_alert_rule and plan_schema_change. https://statoss.com/api/v1/mcp/apps/<app> holds one app's tools, the app by id or slug.