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).

AreaDashboardDoc
Errors and issuesMonitor → Errorserror-monitoring/issues.md
Performance and tracingMonitor → Performanceerror-monitoring/performance.md
Releases and release healthMonitor → Releaseserror-monitoring/releases.md
Cron and uptime monitorsMonitor → Crons, Uptimeerror-monitoring/monitors.md
User feedbackMonitor → User feedbackerror-monitoring/feedback.md
Alerts and notificationsErrors → Alerts, Settings → Notificationserror-monitoring/alerts.md
Slack: alert buttons, DMs, link previewsIntegrations → Slackslack.md
Ingest, SDK compatibility, filters, scrubbingSettings → Sentry SDKs (DSN)error-monitoring/ingest.md
Guidely SDKs: capture API, crashes, debug files (dSYM, ProGuard, ELF)Errorserror-monitoring/sdks.md
Moving from Sentry: DSN swap, sentry-cli, importerSettings → Sentry SDKs → Import from Sentryerror-monitoring/switch-from-sentry.md
Prices: errors, spans, monitors, attachmentsSettings → Plan & usageplans.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 the pk_ keys.
  • ingestId is 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 Origin and are always allowed.
  • Revoke is permanent; SDKs using the DSN get 401.

Endpoints

PathUsed 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=…, the sentry_key query parameter (browser SDKs), or the envelope header's dsn (tunnels). The key must belong to the ingestId in the path.
  • Bodies: Content-Encoding gzip, 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) gets X-Sentry-Rate-Limits, e.g. 3600:<categories>:organization:usage_exceeded, and 429 when every item was refused. More than 6,000 requests a minute from one sender IP for one key answers 429 with Retry-After: 60. Errors carry X-Sentry-Error. Limits, inbound filters and data scrubbing: ingest.md.
  • Trailing slash: Sentry SDKs post to /envelope/. src/middleware.ts serves 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.
  • fingerprint from the SDK is honoured: {{ default }} stands for Guidely's own fingerprint.
  • release becomes the event's app version, and selects source maps. user.id becomes 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>), a level (fatal, error, warning, info, debug), a platform, and a category (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 in apps/web/src/lib/plans.ts, Sentry's published prices for comparison in apps/web/src/lib/sentry-pricing.ts.
  • apps/web/src/server/services/sentry-import/: Import from Sentry (client, pure translations, worker job); SENTRY_IMPORT_API_URL points 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.