Get started with error monitoring
Guidely's error monitoring takes errors, traces, release health, cron check-ins and user feedback from Guidely's own SDKs, and from Sentry SDKs too, so apps that already use one can switch without code changes. Pick the path that fits, then follow the steps after it that you need. Everything lives under Monitor in the sidebar: Errors, Performance, Releases, Crons, Uptime and User feedback.
| You are… | Start with |
|---|---|
| Setting up a new app, or already using Guidely for guides or analytics | A. The Guidely SDK |
| Already sending to sentry.io or a self-hosted Sentry | B. Switching from Sentry |
| Setting up a new app and want a Sentry SDK (a platform Guidely has no SDK for, say) | C. A new app with a Sentry SDK |
You can mix them: a Sentry SDK on your servers and Guidely's SDK in the browser land in the same issues and the same traces.
A. The Guidely SDK
If the app already runs Guidely's SDK for guides, analytics or session replay, it already reports errors: uncaught errors and unhandled promise rejections are captured automatically, with breadcrumbs, and linked to the user and their session replay. New to Guidely? Install the SDK first (sdk.md for the web, mobile.md for iOS, Android, React Native and Flutter, server-sdks.md for Node, Java and PHP).
- Send your app's version (
appVersion: "2.4.1", ordata-app-versionon the script tag; mobile SDKs send it on their own) so errors, sessions and crash-free rates are tracked per release.
- Check error tracking is on: Settings → Privacy & data → error tracking (on by default).
- Report handled errors yourself with the same calls Sentry has:
guidely.captureException(error, { tags: { area: "checkout" } }); guidely.captureMessage("Checkout took 9 s", "warning"); guidely.setUser({ id: "u_42" });
- Framework helpers: React
<GuidelyErrorBoundary>, Next.jsonRequestError, SvelteKithandleErrorWithGuidely, ElectronsetupGuidelyMain({ errors: true }). Mobile SDKs report crashes on the next launch. - Tracing in the web SDK is off by default: Settings → Privacy & data → Performance.
Everything the SDKs capture, and how to tune it, is in sdks.md.
B. Switching from Sentry
Your code stays as it is; you change the DSN, one project at a time.
- Import your setup (optional): Settings → Sentry SDKs (DSN) → Import from Sentry brings alert rules (created turned off), cron monitors and releases (each created when you click Create monitors / Create releases), with members as invite suggestions.
- Swap the DSN in each app for the one in Settings → Sentry SDKs (DSN).
- Point sentry-cli and your bundler plugin at Guidely with
SENTRY_URL,SENTRY_ORG,SENTRY_PROJECTand agly_sk_key asSENTRY_AUTH_TOKEN(or move CI to the Guidely CLI,npx @guidelytech/sourcemaps: releases, source maps). - Turn the imported alert rules on in Errors → Alerts once the DSN is swapped.
The full walkthrough, with what carries over and what's different, is Switching from Sentry.
C. A new app with a Sentry SDK
- Get the DSN. A workspace admin opens Settings → Sentry SDKs (DSN). The project's Default key is created the first time the page opens. Copy its DSN; it looks like
https://<public key>@<your Guidely API host>/<project number>. The page has install snippets for the most used SDKs. - Install the SDK for your platform as Sentry's own docs describe (
@sentry/browser,@sentry/nextjs,sentry-sdkfor Python,sentry-cocoa…), and pass the DSN:```js import * as Sentry from "@sentry/browser";
Sentry.init({ dsn: "https://<public key>@<your Guidely API host>/<project number>", environment: "production", // prod → Production, stage → Staging, dev / local → Development release: "web@1.0.0", // optional: release health, source maps and "resolve in next release" tracesSampleRate: 0.2, // optional: performance tracing (0 turns it off) }); ```
Every Sentry SDK also reads
SENTRY_DSNfrom the environment. The full list of where each platform takes its DSN is in ingest.md. - Check it works: throw a test error (
Sentry.captureException(new Error("Hello from Guidely"))) and open Monitor → Errors. It shows up within seconds, in the environment picked in the header. - Continue with readable stack traces and alerts.
For browser apps, list your site under Allowed browser origins on the key once things work, so nobody else can send events with it. Servers send no origin and are always accepted.
Readable stack traces
Minified JavaScript and native crashes need their debug files to show your original code. The Guidely CLI (npx @guidelytech/sourcemaps) uploads them from CI with a key from Settings → Source maps, stored as GUIDELY_KEY:
- Source maps:
npx @guidelytech/sourcemaps upload --dir dist --release "$VERSION" --delete-after(key scopesourcemaps:write). See ingest.md. - iOS, Android and Flutter:
upload-diffor dSYMs and ELF symbols,upload-proguardfor ProGuard / R8 mappings (scopedebug-files:write). See sdks.md. - Using sentry-cli?
sentry-cli sourcemaps upload,debug-files uploadand the Sentry bundler plugins work too (path B).
Releases and deploys
Tell Guidely about each build from CI, so releases show their commits, suspect commits and deploys:
npx @guidelytech/sourcemaps releases new "$VERSION"
npx @guidelytech/sourcemaps releases set-commits "$VERSION" --auto
npx @guidelytech/sourcemaps releases deploys "$VERSION" new -e production
With a key that has releases:write (Releases → Create a CI key). See releases.md; sentry-cli works too.
Alerts
Errors → Alerts → New alert. A good first rule: a new issue is created or a resolved issue comes back, in Production, notifying your team's channel. Rules can email members, post to Slack, Microsoft Teams or Discord, open PagerDuty or Opsgenie incidents, call a webhook or open a Linear / Jira ticket. See alerts.md.
For Slack, add the Guidely Slack app (Integrations → Slack → Add to Slack) so alerts get buttons to resolve, ignore and assign issues from Slack, and you can get your own alerts as direct messages: Connect Slack. The buttons are off in workspaces that require two-step verification or enforce single sign-on (why); alerts still post. Each person picks which emails and Slack DMs they get in Settings → Notifications.
Next steps
| Want to… | Go to | Doc |
|---|---|---|
| Triage: search, assign, merge, ownership rules | Monitor → Errors | issues.md |
| See slow pages, endpoints and queries | Monitor → Performance | performance.md |
| Know whether a release made things better or worse | Monitor → Releases | releases.md |
| Hear when a scheduled job misses a run | Monitor → Crons | monitors.md |
| Hear when a URL goes down or its certificate is expiring | Monitor → Uptime | monitors.md |
| Collect bug reports from your users | Monitor → User feedback | feedback.md |
| Filter noise, scrub data, set rate limits | Settings → Sentry SDKs (DSN) | ingest.md |
| Ask Claude, ChatGPT or Cursor about an error | Settings → AI assistants | mcp.md |
| Know what it costs | Settings → Plan & usage | plans.md |