Docs

Coming from Sentry

How Sentry's concepts and calls map to Sypnia's, what to remove from your code, and an honest list of what has no equivalent yet.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Run both first
  2. Concepts
  3. Code
  4. Browser
  5. Node
  6. Next.js
  7. Source maps
  8. Other backends
  9. What to remove, when you are done
  10. What has no equivalent yet

This guide is for a team that uses Sentry on a web app and wants to try Sypnia, or move to it. It applies to Sypnia Cloud and to a self-hosted engine.

Sentry is excellent and broad. Sypnia is narrower on purpose: it is built to tell you in one sentence what is wrong, for whom and how to fix it, and to hand that to your coding agent. Some things Sentry does, Sypnia does not do, and this page says which.

At the end you will have: Sypnia running in your app, next to Sentry or instead of it, and a clear list of what you gain and what you give up.

Run both first

Nothing in Sypnia’s SDK conflicts with Sentry’s. Both can listen for errors, both can add trace headers (they use different headers besides the standard traceparent), and each sends to its own address. Install Sypnia, compare the two for a week or two on real traffic, and remove Sentry when you are satisfied.

Two things to know while both run:

  • Both record replays, so the page pays for two recorders. Turn replay off in one of them during the comparison.
  • If you use Sentry’s tunnel or a strict content security policy, add Sypnia’s address too. See Troubleshooting.

Concepts

In SentryIn SypniaDifference
Organization, team, memberThe same, on Sypnia Cloud onlyThe self-hosted engine has projects and tokens, no users.
ProjectProjectOne per app. Frontend and backend of the same app share a project, so their traces connect.
DSNIngest key (spk_…)Public and write-only, like a DSN. The address is separate: the option endpoint, only needed for a self-hosted engine.
Auth tokenAPI token (sps_…) with scopes read, replay, admin
EnvironmentEnvironmentAlerts cover production only by default.
ReleaseReleaseUse the short git commit.
IssueProblemA problem is told as a sentence: what happened, to whom, since when, the likely cause.
EventOccurrence of a problemIn Sypnia, «event» means anything the SDK sends: a click, a page view, an error.
BreadcrumbsThe session’s timelineRecorded without code: pages, clicks in words, requests, errors.
Session ReplayReplayTyped input is always masked, with no option to unmask.
Tracing, spansTraces, spansEvery request is traced; there is no trace sample rate.
Web VitalsPerformanceWith the element behind each value.
User Feedback, Crons, Profiling, Logs, MetricsNo equivalentSee the last section.
Seer, AutofixThe agent, the prompt, MCP, pull requestsPull requests are on Sypnia Cloud.

Code

Browser

src/main.ts
- import * as Sentry from '@sentry/browser';
+ import { init } from '@sypnia/browser';

- Sentry.init({
-   dsn: 'https://abc123@o123456.ingest.sentry.io/7890123',
-   environment: 'production',
-   release: '4f2a91c',
-   integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()],
-   tracesSampleRate: 0.2,
-   replaysSessionSampleRate: 0.1,
-   replaysOnErrorSampleRate: 1.0,
- });
+ init({
+   project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
+   environment: 'production',
+   release: '4f2a91c',
+ });

There are no integrations to list and no sample rates in code: errors, clicks, requests, performance and replay are on by default, and the share of sessions recorded is a project setting (10 % by default, plus every session where something goes wrong).

SentrySypniaNotes
Sentry.init({ dsn })init({ project })Every option.
Sentry.captureException(error)reportError(error)
Sentry.captureMessage(text)track(name, props), or reportError(new Error(text))A message that is not a failure is a custom event.
Sentry.setUser({ id, email, username })identify({ person: { id, email, name } })Plus an optional account. Sentry.setUser(null) is identify(null).
Sentry.addBreadcrumb(…)Usually nothing. track(name, props) for what Sypnia cannot see.Clicks, navigations and requests are already in the timeline.
Sentry.setTag, setContext, setExtra, withScopeNo equivalentSee below.
beforeSendbeforeSendCalled for every event, not only errors.
ignoreErrorsignoreErrors
denyUrls, allowUrlsappFramesErrors from scripts of other origins are dropped by default; appFrames names your CDN.
tracePropagationTargetstraceTargetsYour own origin is always included.
tunnelendpoint set to a path on your own domainYou write the forwarding route.
replayIntegration({ maskAllText, blockAllMedia })maskAllText, data-sypnia-mask, data-sypnia-blockPage text is recorded as shown by default; typed input never is. If you relied on Sentry’s default of masking all text, set maskAllText: true.
Sentry.ErrorBoundaryYour own boundary that calls reportError(error, { source: 'boundary' })Example.
Sentry.showReportDialogNo equivalent

Node

src/instrument.ts
- import * as Sentry from '@sentry/node';
+ import { init } from '@sypnia/node';

- Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.2 });
+ init({ project: process.env.SYPNIA_PROJECT_KEY, service: 'shop-api' });
SentrySypniaNotes
Sentry.setupExpressErrorHandler(app)One middleware that calls reportError(error) and next(error)Per framework.
Sentry.startSpan({ name }, fn)span(name, fn)
Sentry.flush(ms), Sentry.close(ms)flush(ms), shutdown(ms)
Automatic instrumentation of many librarieshttp, fetch, pg, Supabase and PostgREST at launchFor others use span(), or OpenTelemetry instrumentations with the OTLP intake.

Next.js

SentrySypnia
withSentryConfig(nextConfig, options)withSypnia(nextConfig, options)
sentry.client.config.ts / instrumentation-client.tsinstrumentation-client.ts, three lines
sentry.server.config.ts, sentry.edge.config.ts, instrumentation.tsinstrumentation.ts, one line. The Edge runtime is not covered at launch.
global-error.tsx with Sentry.captureExceptionThe same file with reportError(error, { source: 'boundary', digest: error.digest })
SENTRY_AUTH_TOKEN at buildSYPNIA_API_TOKEN at build

The full setup is in Next.js.

Source maps

Build script
- sentry-cli sourcemaps inject dist && sentry-cli sourcemaps upload --release "$RELEASE" dist
+ npx sypnia sourcemaps upload dist --release "$RELEASE" --delete-after

Sypnia does not inject ids into your files: it matches a stack frame to its map by the release and the file’s path. Remove the bundler plugins (@sentry/vite-plugin, @sentry/webpack-plugin) when you remove Sentry. See Source maps in CI.

Other backends

If your Python, Go, PHP, Rust or Java services report to Sentry with its SDKs, Sypnia’s answer today is OpenTelemetry: add the OpenTelemetry SDK of the language and point its exporter at Sypnia. Native Sypnia SDKs for these languages are Planned. See OpenTelemetry.

What to remove, when you are done

  1. The packages: @sentry/browser, @sentry/react, @sentry/node, @sentry/nextjs, the bundler plugins, @sentry/cli.
  2. Every Sentry. call. Most disappear rather than being replaced: addBreadcrumb, setTag, setContext, the integrations list.
  3. The config files sentry.*.config.ts and .sentryclirc, and withSentryConfig.
  4. The variables SENTRY_DSN, SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT from your host and CI.
  5. Sentry’s hosts from your content security policy, and the tunnel route if you had one.

What has no equivalent yet

Said plainly, so you can decide:

In SentryIn Sypnia
Tags, contexts, extra data and scopes on an errorNot at launch. An error carries its session, person, account, release, route and trace. Put your own facts in a track() event next to it, or change the event in beforeSend.
Search and saved views over arbitrary tags; Discover; dashboardsNot at launch. Custom metrics and dashboards are Planned.
Native SDKs: iOS, Android, React Native, Flutter, Unity, desktopPlanned for iOS and Android. Web views work with the browser SDK.
SDKs for Python, PHP, Go, Rust, Ruby, Java, .NETPlanned for Python, PHP, Go and Rust. Today: OpenTelemetry traces.
LogsPlanned
ProfilingNo.
Cron monitoringNo. Uptime checks tell you a URL stopped answering, not that a job did not run.
User feedback widgetNo.
Attachments, minidumps, native crash symbolicationNo.
Trace sampling in the SDKNo: every request is traced. Use ignoreRoutes to leave routes out; sampling of successful requests is Planned.
Alert rules with many conditions; integrations with chat and ticket toolsSypnia has a fixed set of alerts with thresholds you can tune. They arrive by e-mail and in the app on Sypnia Cloud, and by webhook on any engine. There are no chat or ticket integrations: build on the webhook.
Issue assignment, ownership rules, code ownersNo. A problem is open, resolved or ignored.
Single sign-onPlanned
Importing your history from SentryNo. Sypnia starts from the day you install it.

What you get in exchange is on What Sypnia is: problems as sentences, the element behind slow pages, rage and dead clicks, and the fix handed to your coding agent as a prompt, through MCP, or as a pull request.

The whole list of what is planned, without dates, is in Planned.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close