Switching from Sentry

Guidely accepts events from Sentry's own SDKs, so moving an app over means changing its DSN. Your Sentry.init options, captureException calls, integrations, sample rates and beforeSend hooks stay as they are. This guide walks through moving one project, then the rest.

  1. Create a Guidely project for each Sentry project (or reuse one).
  2. Import from Sentry: alert rules, cron monitors, releases, open issues and who to invite.
  3. Swap the DSN in each app.
  4. Point sentry-cli and the bundler plugins at Guidely for source maps, debug files and releases.
  5. Move cron monitors and check your alerts.

You can move one project at a time: each has its own DSN, so a project can send to Guidely while the others still send to Sentry.

1. Create the project

Guidely's workspace is Sentry's organization, and a Guidely project is a Sentry project. A Guidely project also has environments (Production, Staging, Development, and any you add); events go to the environment matching the SDK's environment option (prod → Production, stage → Staging, dev or local → Development), and anything else to the key's default environment.

If the app also uses Guidely for guides or analytics, use that project, so errors, replays and analytics for the same users sit together.

2. Import from Sentry

Settings → Sentry SDKs (DSN) → Import from Sentry (workspace admins). You need a Sentry auth token: an organization token (Settings → Auth Tokens) or a personal token with the org:read, project:read, alerts:read and member:read scopes.

  1. Choose sentry.io (US), de.sentry.io (EU) or Self-hosted (your Sentry's URL, reachable from the internet on the standard HTTPS port), enter the organization slug (the acme in acme.sentry.io or sentry.io/organizations/acme/) and the token, and Connect.
  2. Choose the Guidely project each Sentry project goes into, or Skip it. Projects with the same name are matched for you.
  3. Choose what to bring and Import. It runs in the background; the page shows its progress and result.
From SentryBecomes in Guidely
Each project's DSNsListed next to the Guidely DSN that replaces them (a client key is created if the project has none)
Issue alert rulesError alert rules, created turned off (see Alerts)
Cron monitorsRead with their name, slug, schedule, timezone, check-in margin, max runtime and thresholds; Create monitors makes them in Monitor → Crons
ReleasesThe 100 newest per project; Create releases makes them in Monitor → Releases
Unresolved issuesA read-only list (the 100 seen most recently in 14 days) for reference
MembersInvitation suggestions with a matching role: owner, manager and admin → Admin, member → Editor, billing → Viewer. Nobody is invited until you click Invite

The token is stored encrypted only while the import waits or runs, and is deleted when it finishes, fails or is cancelled. Run the import again whenever you like: nothing is duplicated, and an alert rule imported before is never recreated or overwritten, even if you've changed or deleted it since. If the token can't read something (a missing scope, or a self-hosted version without that API), the rest is imported and the result says what was skipped.

Cron monitors and releases aren't created by the import itself. When it has finished, the result shows how many are ready, with a button for each (you need the Manage insights & alerts permission):

  • Create monitors makes each Sentry cron monitor a Guidely one in the project it was imported into, with its schedule (crontab or interval), timezone, check-in margin, max runtime, failure and recovery thresholds, and paused or muted state. Active monitors count towards your plan's monitor allowance: when it runs out, nothing more is created and the rest are listed with the reason, so you can raise the limit and click again. A monitor whose slug is already in the project is left as it is.
  • Create releases makes each release in its project, with Sentry's ref, link and start and release dates. A release Guidely already has (from events or sentry-cli) keeps its details and only gains what's missing. Commits stay in Sentry; send them with sentry-cli releases set-commits for new releases.

Both are safe to click again: each monitor and release is created once, and the result says how many were created, skipped (made before, or already there) and couldn't be created, and why.

3. Swap the DSN

Settings → Sentry SDKs (DSN) shows the project's DSN:

https://<public key>@<your Guidely API host>/<project number>

Put it where the Sentry DSN was. Every Sentry SDK reads SENTRY_DSN when init gets no dsn, so if you set it through the environment, change only the variable:

SENTRY_DSN=https://<public key>@<your Guidely API host>/<project number>
// Browser, React, Vue, Angular, Svelte, Next.js, Remix, Node…
Sentry.init({ dsn: "https://<public key>@<your Guidely API host>/<project number>" /* other options unchanged */ });
sentry_sdk.init(dsn="https://<public key>@<your Guidely API host>/<project number>")

The same goes for Go, Ruby, PHP, Java, .NET, Rust, Elixir, Android, iOS (Cocoa), React Native, Flutter and Unity: the dsn option (or SENTRY_DSN) is the only change. Next.js projects usually set it in instrumentation-client.ts, sentry.server.config.ts and sentry.edge.config.ts.

  • Browser origins: a DSN accepts any origin until you list Allowed browser origins on its key. Servers send no origin and are always accepted.
  • Several apps in one project: add a key per app (New client key) to rotate or revoke them separately, and set each key's default environment.
  • The Loader Script (js.sentry-cdn.com/<key>.min.js) loads its configuration from Sentry, so it can't be pointed at Guidely. Use the npm package or Sentry's CDN bundles with Sentry.init({ dsn }).

Tunnels

If you use Sentry's tunnel option, your tunnel forwards envelopes to the host in the DSN of the envelope header. Guidely accepts envelopes at POST https://<your Guidely API host>/api/<project number>/envelope/ and reads the key from the envelope header's dsn, the same way Sentry does, so a tunnel that builds the upstream URL from the DSN works unchanged. A tunnel that hard-codes sentry.io (or o123.ingest.sentry.io) needs that host changed, and one that checks the DSN host against an allowlist needs your Guidely API host added.

4. Source maps, releases and sentry-cli

sentry-cli and Sentry's bundler plugins (Vite, webpack, Rollup, esbuild, Next.js) talk to Guidely's Sentry-compatible API with four settings:

SENTRY_URL=https://<your Guidely API host>/
SENTRY_ORG=<workspace slug>
SENTRY_PROJECT=<project slug>
SENTRY_AUTH_TOKEN=gly_sk_…

The token is a project API key (gly_sk_…, Settings → Source maps) with the scopes you need: sourcemaps:write for source maps, releases:write for releases and debug-files:write for ProGuard mappings and dSYMs. A key only reaches its own project. The project slug is under Settings → General and the workspace slug under Settings → Workspace.

  • Source maps: keep running sentry-cli sourcemaps inject and sentry-cli sourcemaps upload, or the bundler plugin, in CI. Uploads are matched to errors by debug ID or by release. Guidely's own upload API works too (product-analytics.md).
  • Releases: the SDK's release option becomes the error's app version. sentry-cli releases new, set-commits and finalize create and complete releases as in Sentry.
  • Debug files: sentry-cli debug-files upload for dSYMs and sentry-cli upload-proguard for Android mappings.

Prefer one tool with Guidely's own names? The Guidely CLI (npx @guidelytech/sourcemaps) does the same jobs with the same key, stored as GUIDELY_KEY with GUIDELY_API_URL (the workspace and project come from the key): upload / inject for source maps, upload-dif / upload-proguard for debug files, and releases new, set-commits --auto | --local, finalize and deploys new for releases (releases.md). You can move one CI step at a time.

5. Cron monitors

Check-ins from the SDKs (Sentry.captureCheckIn, Sentry.withMonitor, sentry_sdk.crons.monitor, the Celery and other scheduler integrations) arrive through the DSN like errors do, so once a job's DSN is swapped its check-ins come to Guidely. Imported monitors keep their slugs, so check-ins match them. sentry-cli monitors run <slug> -- <command> works too, with the DSN set in SENTRY_DSN.

Each cron or uptime monitor counts once in any month it's active (5 free, then $0.50 a month each, see plans.md).

6. Alerts

Imported issue alerts become error alert rules, turned off so nobody is alerted twice while Sentry still runs. Open Errors → Alerts, check each rule's recipients and turn it on when the project's DSN is swapped. The import result lists, rule by rule, what didn't carry over:

SentryGuidely
A new issue is created; a new high-priority issueAlert on a new issue
The issue changes state from resolved to unresolved; escalatingAlert on a regression
The issue is seen more than N times in an intervalA spike: N occurrences in a window from 5 minutes to a day (other intervals are scaled to the nearest)
Action intervalThe cooldown between alerts for the same issue
EnvironmentThe project environment those events land in; no environment = all of them
Email to a memberThe member's email address
Email to a team or to suggested ownersA note to add the addresses
Slack, Microsoft Teams, Discord, PagerDuty, Opsgenie, webhooks, Jira, GitHubA note to add the destination to the rule
Filters (tags, level, age, occurrences, assignee, release), percent and unique-user conditionsA note: not carried over, so the rule may alert more often

Sentry's rules that need all conditions at once are noted too: Guidely alerts on each condition on its own.

What's different

  • Pricing: no plan fee and no seats. Each product has a free allowance every month and pay-as-you-go rates below Sentry's Team plan at every volume tier (errors and replays from December 2026, when their new prices start); a billing limit per product caps the bill. See Pricing and plans.md.
  • When an allowance runs out, the product pauses until the 1st (or a higher limit) and the SDK gets Sentry's own 429 and X-Sentry-Rate-Limits answers, so it stops sending instead of retrying.
  • Monitors are one product: cron and uptime monitors share the allowance and price.
  • Attachments are counted in MB (1 GB = 1,000 MB), added up over the month.
  • Issue history stays in Sentry. The import reads unresolved issues for reference, but issues in Guidely start with the first event it receives, with their own short ids (WEB-1, WEB-2, …). Keep Sentry readable for as long as you need its history.
  • Members and roles: Guidely has workspace roles (Owner, Admin, Editor, Viewer) and per-member permissions. The import suggests a role for each Sentry member.
  • Errors meet the rest of Guidely: an error links to the session replay it happened in and to the user, with their page views and account, when the same people use Guidely's SDK.

FAQ

Do I have to change my code? Only the DSN. Integrations, sampling, beforeSend, tags, contexts, user and breadcrumbs all work as before.

Can Sentry and Guidely run side by side? Yes, by project: swap the DSN in one app, check it in Guidely, then move the next. To send the same app to both while you compare, run a tunnel that forwards each envelope to both hosts.

Which SDK versions work? Current SDKs post to /api/<project>/envelope/; older ones post single events to /api/<project>/store/, which Guidely accepts too, gzipped, deflated, Brotli or zstd.

What about Sentry's Session Replay? Replays from the Sentry SDK are linked to the errors that happened in them. If you also use Guidely's SDK, its session replay works the same way.

Does Guidely keep my Sentry token? Only encrypted, while the import waits or runs. It's deleted when the import finishes, fails or is cancelled, and Cancel deletes it straight away.

Is the import repeatable? Yes. Running it again updates what it read and never duplicates rules, monitors or releases.

Where's Guidely's own SDK in this? If you already use Guidely's SDK for guides or analytics, it reports errors too (product-analytics.md). You can use either SDK, or both in the same project.