Error monitoring (Sentry replacement)
Guidely accepts data from any Sentry SDK. Point the SDK's dsn at Guidely and errors, performance traces, release health, cron check-ins and user feedback arrive here. Nothing else in your code changes. Guidely's own SDKs (web, mobile, server) report errors too (see product-analytics.md).
| Area | Dashboard | Doc |
|---|---|---|
| Errors and issues | Monitor → Errors | error-monitoring/issues.md |
| Performance and tracing | Monitor → Performance | error-monitoring/performance.md |
| Releases and release health | Monitor → Releases | error-monitoring/releases.md |
| Cron and uptime monitors | Monitor → Crons, Uptime | error-monitoring/monitors.md |
| User feedback | Monitor → User feedback | error-monitoring/feedback.md |
| Alerts and notifications | Errors → Alerts, Settings → Notifications | error-monitoring/alerts.md |
| Slack: alert buttons, DMs, link previews | Integrations → Slack | slack.md |
| Ingest, SDK compatibility, filters, scrubbing | Settings → Sentry SDKs (DSN) | error-monitoring/ingest.md |
| Guidely SDKs: capture API, crashes, debug files (dSYM, ProGuard, ELF) | Errors | error-monitoring/sdks.md |
| Moving from Sentry: DSN swap, sentry-cli, importer | Settings → Sentry SDKs → Import from Sentry | error-monitoring/switch-from-sentry.md |
| Prices: errors, spans, monitors, attachments | Settings → Plan & usage | plans.md |
New here? Get started walks through the three ways in: a new app with a Sentry SDK, switching from Sentry, or Guidely's own SDK. Coming from Sentry? Go straight to Switching from Sentry. For alerts in Slack with buttons to resolve, ignore and assign, see Connect Slack.
Client keys (DSNs)
Settings → Sentry SDKs (DSN) (admins). Each project gets a Default key the first time the page opens; add more to separate apps or rotate. A DSN looks like https://<publicKey>@<your Guidely API host>/<ingestId>:
publicKey(32 hex characters) isn't a secret. Browser SDKs embed it, like thepk_keys.ingestIdis numeric because Sentry SDKs refuse a DSN whose project id isn't a number.- Default environment: events go to the project environment whose key or name matches the SDK's
environment(prod→ production,stage→ staging,dev/local→ development). Anything else goes to the key's default environment. - Allowed browser origins: empty means any. Server SDKs send no
Originand are always allowed. - Revoke is permanent; SDKs using the DSN get
401.
Endpoints
| Path | Used by |
|---|---|
POST /api/<ingestId>/envelope/ | Every current Sentry SDK |
POST /api/<ingestId>/store/ | Older SDKs (single JSON event, or base64 zlib) |
POST /api/<ingestId>/security/ | CSP / Expect-CT / HPKP reports (ingest.md) |
POST /api/<ingestId>/minidump/ | Crashpad, Breakpad, Electron crash uploads (ingest.md) |
/api/0/organizations/<org>/chunk-upload/, …/artifactbundle/assemble/ | sentry-cli and the bundler plugins (ingest.md) |
- Auth:
X-Sentry-Auth: Sentry sentry_key=…, thesentry_keyquery parameter (browser SDKs), or the envelope header'sdsn(tunnels). The key must belong to theingestIdin the path. - Bodies:
Content-Encodinggzip, deflate, br and zstd; up to 40 MB per envelope, 1 MB per event. - Responses:
200 {"id": "<event_id>"}. A category over a limit (the key's rate limit, spike protection, the monthly allowance or billing limit) getsX-Sentry-Rate-Limits, e.g.3600:<categories>:organization:usage_exceeded, and429when every item was refused. More than 6,000 requests a minute from one sender IP for one key answers429withRetry-After: 60. Errors carryX-Sentry-Error. Limits, inbound filters and data scrubbing: ingest.md. - Trailing slash: Sentry SDKs post to
/envelope/.src/middleware.tsserves those paths as they are and keeps the usual 308 redirect for every other trailing-slash URL (skipTrailingSlashRedirect).
How an error is stored
An event item becomes a Guidely exception event (ProductEvent, properties.source = "sentry"), so grouping, source maps, plan allowances, excluded traffic, alerts, replays and app versions work as they do for the Guidely SDK. The full payload (exception chain, threads, breadcrumbs, tags, contexts, request without cookies or credential headers, user, debug images) is kept in ErrorEventDetail and expires with the events.
- Frames are converted to Guidely order (innermost first). Grouping uses the innermost in-app frame when the SDK marks frames (
in_app), else the innermost frame with a file or module. fingerprintfrom the SDK is honoured:{{ default }}stands for Guidely's own fingerprint.releasebecomes the event's app version, and selects source maps.user.idbecomes the user id (externalUserId), so a backend error links to the same person as their frontend sessions.- Issues get a short id per project (
ErrorIssue.shortId, shown as<PROJECT-SLUG>-<n>), alevel(fatal, error, warning, info, debug), aplatform, and acategory(error, performance, uptime, cron, feedback).
Code map
apps/web/src/server/sentry/: envelope parser, auth, normaliser, item handlers (handlers/<type>.ts, one per item type).apps/web/src/server/services/sentry-keys.ts: DSN keys.apps/web/src/app/api/[sentryProjectId]/: the ingest routes.apps/web/src/server/services/monitoring-usage.ts: allowances for spans, monitors (countActiveMonitor) and attachments; prices inapps/web/src/lib/plans.ts, Sentry's published prices for comparison inapps/web/src/lib/sentry-pricing.ts.apps/web/src/server/services/sentry-import/: Import from Sentry (client, pure translations, worker job);SENTRY_IMPORT_API_URLpoints it at a local mock (src/test/sentry-mock.ts).apps/web/src/server/mcp/: MCP tools for assistants (see mcp.md):error-monitoring-tools.ts(search, DSNs, ingest, the shared redaction helpers),issue-tools.ts,performance-tools.ts,release-tools.ts,monitor-tools.ts,user-feedback-tools.ts,alert-tools.ts.