Sentry SDK ingest: DSNs, filters, scrubbing, attachments, source maps
Every Sentry SDK and sentry-cli can send to Guidely instead of sentry.io. This page covers what happens to data on the way in: where to point SDKs, which limits apply, what is filtered and scrubbed, how attachments, Session Replay, CSP reports and native crashes are stored, and how source maps are uploaded. Settings live under Settings → Sentry SDKs (DSN) (admins).
Switch from Sentry
Only configuration changes. In each app and in CI:
| Where | Sentry | Guidely |
|---|---|---|
| Every SDK | dsn / SENTRY_DSN (also NEXT_PUBLIC_SENTRY_DSN, VITE_SENTRY_DSN, PUBLIC_SENTRY_DSN, EXPO_PUBLIC_SENTRY_DSN, sentry.properties / Info.plist / AndroidManifest.xml io.sentry.dsn) | The DSN from Settings → Sentry SDKs, e.g. https://3f9a…@guidelytech.com/42 |
| sentry-cli, bundler plugins, Sentry Gradle / Xcode / Fastlane steps | SENTRY_URL (or none for sentry.io) | SENTRY_URL=<your Guidely API URL> (url: option of the Vite / webpack / Rollup / esbuild / Next.js plugins, defaults.url in .sentryclirc / sentry.properties) |
SENTRY_ORG | Your workspace slug (in the dashboard URL and Settings → Workspace) | |
SENTRY_PROJECT | The project's slug | |
SENTRY_AUTH_TOKEN (sntrys_…) | A project API key gly_sk_… (Settings → Source maps) with sourcemaps:write (plus releases:write for release commands, debug-files:write for native debug files and monitors:write for sentry-cli monitors run) | |
| CSP / Expect-CT headers | report-uri https://o0.ingest.sentry.io/api/<id>/security/?sentry_key=… | report-uri https://<your Guidely API host>/api/<ingestId>/security/?sentry_key=<publicKey> |
Crashpad / Breakpad / Electron crashReporter | submitURL …/api/<id>/minidump/?sentry_key=… | https://<your Guidely API host>/api/<ingestId>/minidump/?sentry_key=<publicKey> |
Nothing else changes: release, environment, tracesSampleRate, beforeSend, integrations, tunnel routes (they forward the envelope as is; the DSN in its header is honoured) and Sentry.replayIntegration() keep working. Issues start fresh in Guidely: history in sentry.io isn't imported.
DSN per platform
The same DSN works for every SDK. Common places to set it:
| Platform | Setting |
|---|---|
| Browser, React, Vue, Angular, Svelte | Sentry.init({ dsn }) |
| Next.js | dsn in instrumentation-client.ts, sentry.server.config.ts and sentry.edge.config.ts (or NEXT_PUBLIC_SENTRY_DSN); withSentryConfig({ org, project, authToken, sentryUrl }) for uploads |
| Node, Bun, Deno | Sentry.init({ dsn }) or SENTRY_DSN |
| Python, Ruby, PHP, Go, Rust, Elixir | sentry_sdk.init(dsn=…), config.dsn, \Sentry\init(['dsn' => …]), sentry.Init(sentry.ClientOptions{Dsn: …}), sentry::init(…), config :sentry, dsn: (or SENTRY_DSN) |
| Java, Kotlin, Spring Boot, .NET | options.setDsn(…), sentry.dsn= in application.properties, o.Dsn = … / appsettings.json Sentry:Dsn |
| iOS / macOS (Cocoa), Android | options.dsn = … in SentrySDK.start, io.sentry.dsn meta-data in AndroidManifest.xml |
| React Native, Flutter, Unity, Unreal | Sentry.init({ dsn }), options.dsn = … in SentryFlutter.init, the DSN field in the Sentry project settings of the engine |
| Native (sentry-native), Electron | sentry_options_set_dsn(…), Sentry.init({ dsn }) in main and renderer |
Endpoints
| Path | Used by |
|---|---|
POST /api/<ingestId>/envelope/ | Every current Sentry SDK |
POST /api/<ingestId>/store/ | Older SDKs (one JSON event, or base64 zlib). Goes through the same limits, filters and scrubbing. |
POST /api/<ingestId>/security/?sentry_key=… | Browsers sending CSP, Expect-CT and HPKP reports |
POST /api/<ingestId>/minidump/?sentry_key=… | Crashpad, Breakpad, Electron crashReporter |
GET, POST /api/0/organizations/<org>/chunk-upload/ | sentry-cli and the bundler plugins (chunked uploads) |
POST /api/0/organizations/<org>/artifactbundle/assemble/ | sentry-cli sourcemaps upload, bundler plugins |
Browser SDKs post with fetch (keepalive) and a text/plain body, so no CORS preflight is needed; responses allow any origin unless the key lists allowed origins, and expose X-Sentry-Rate-Limits, X-Sentry-Error and Retry-After so the SDK can read them.
Envelope items
| Item | What happens |
|---|---|
event | An error issue occurrence (issues.md) |
transaction, span | Performance (performance.md) |
session, sessions | Release health (releases.md) |
check_in | Cron monitors (monitors.md) |
feedback, user_report | User feedback (feedback.md) |
attachment | Stored with its event (below) |
client_report | Counted under Dropped events (below) |
replay_event, replay_recording | A Guidely recording (below) |
security | A CSP report (below) |
profile, profile_chunk, replay_video, statsd, log and unknown types | Acknowledged and dropped, so SDKs don't retry them |
Rate limits
Every item is checked, in this order, before it is stored:
- Requests per sender: at most 6,000 requests a minute per client key and IP address (more if the key's own limit is higher). Over it the whole request gets
429,Retry-After: 60. - Client key rate limit (optional, per key in Settings → Sentry SDKs): errors, transactions and security reports per minute this key accepts from all senders together.
- Spike protection (on by default): at most 3,000 errors a minute per project, and separately 3,000 transactions and 3,000 security reports. Change the number or switch it off under Spike protection. It caps a sudden flood (an error in a render loop) before it uses up the month.
- Plan allowance and billing limit: the month's errors, transactions, replays and attachments.
An item over a limit is dropped and the response says so per category, as Sentry does:
X-Sentry-Rate-Limits: 60:error;attachment:key:key_quota
X-Sentry-Rate-Limits: 60:error;attachment:project:spike_protection
X-Sentry-Rate-Limits: 3600:transaction:organization:usage_exceeded
SDKs stop sending those categories for that many seconds. When every item of a request was rate-limited the status is 429 with Retry-After; otherwise 200. An error's attachments are dropped with it.
Inbound filters
Events matching a filter are dropped on arrival and never count against your plan.
| Filter | Default | Drops |
|---|---|---|
| Browser extensions | on | Errors whose innermost frame is in an extension (chrome-extension://, moz-extension://, safari-web-extension://…) or a well-known injected script, and well-known extension messages (Extension context invalidated, top.GLOBALS, Cannot redefine property: ethereum…). Also CSP reports caused by extensions. |
| Localhost | off | Events whose request URL host is localhost, *.localhost, 127.0.0.1, ::1 or 0.0.0.0, or whose user IP is 127.0.0.1 / ::1. |
| Web crawlers | on | User-Agents of search engines, link previews, uptime checkers, scanners and AI crawlers (Googlebot, Bingbot, Slackbot, GPTBot, ClaudeBot, Pingdom, UptimeRobot…). |
| Legacy browsers | none | The ones you tick: Internet Explorer, Edge before 79, Safari before 12, Firefox before 67, Chrome before 69, Opera before 50, Opera Mini before 8, Android browser before Android 5. |
| Health check transactions | on | Transactions named *healthcheck*, *heartbeat* or ending in /health, /healthy, /healthz, /_health, /live, /livez, /ready, /readyz, /ping, /up. |
| Releases | none | Glob list (* any characters, ? one, case-insensitive, whole value): 1.0.*, *-canary. |
| Error messages | none | Glob list matched against Type: value of every exception and the message: *ResizeObserver loop*, TypeError: Failed to fetch. |
| IP addresses | none | Addresses and CIDR ranges (IPv4 and IPv6), matched against the user's IP (the sender's when the SDK sends {{auto}} or none). |
Releases, IP addresses, localhost, crawlers and legacy browsers also apply to transactions and Session Replay; browser extensions and error messages only to errors.
Data scrubbing
On by default, applied on the server before anything is stored (the occurrence payload, the event Guidely indexes and counts, transactions and replay metadata). It adds to what the SDK removes itself (beforeSend, sendDefaultPii: false).
- By field name (Use default scrubbers): the value of any key containing
password,passwd,pwd,secret,api_key/apikey,access_key,private_key,credential,token,bearer,session,cookie,csrf/xsrf,jwt,authorization,authentication,passphrase,card_number,cvv/cvc,iban,ssn, or exactlyauth,pass,pin,otp,sig,signature, becomes[Filtered]. This covers request bodies, headers, query strings and URLs (?token=[Filtered]), cookies,extra, contexts, tags, breadcrumbs (messages and data), frame variables, user data and transaction span data. - By value: card numbers (13–19 digits, Luhn-checked),
Bearer/Basic/Tokencredentials, passwords in URLs (https://user:[Filtered]@host), PEM private keys, AWS access keys, Stripe, GitHub, Slack and Guidely keys, and JWTs, in any string. - Additional sensitive fields: your own key fragments, matched like the built-ins.
- Safe fields: exact key names never scrubbed by name (value patterns still apply).
- Don't store IP addresses: drops
user.ip_address(including{{auto}}, which otherwise becomes the sender's address) and IP headers /REMOTE_ADDRin the request.
Structural fields (event ids, release, environment, SDK, debug images, exception types and mechanisms, frame files, functions and lines) are never scrubbed, so grouping and source maps still work. Switching the scrubber off stores events as the SDK sent them, except that cookies and credential headers are always dropped.
HIPAA workspaces (HIPAA mode) always scrub, whatever the project's switches say, and more strictly: frame variables, request bodies, cookies and query values are removed; the user keeps only id (email, username, name, IP and geo are dropped); keys containing email, phone, address, birth / dob, name fragments, patient, diagnosis, mrn, medical or insurance are scrubbed; and email addresses, US social security numbers and phone numbers in any text become [email], [ssn], [phone]. There is no safe-field list in HIPAA mode.
Dropped events
Settings → Sentry SDKs → Dropped events lists the last 30 days by where and why:
- Dropped by SDK: the client reports Sentry SDKs send (sampled out,
beforeSend, event processors, full queues or offline caches, backing off after a rate limit, network and send errors). - Filtered: inbound filters, recording turned off for the project, attachments turned off.
- Rate limited: client key limit, spike protection, plan allowance or billing limit.
- Discarded: invalid or too-large items.
Counts are per client key and data category and kept 90 days.
Attachments
attachment items (screenshots from attachScreenshot, view hierarchies, log files from scope.addAttachment, minidumps, Unreal crash contexts, user feedback screenshots) are stored with their event, whether they arrive in the same envelope or a later one with the same event_id.
- Up to 30 MB per file, 40 MB and 20 files per event. Bigger ones are dropped (Discarded).
- Counted in bytes against the attachments allowance; over it they are rate limited.
- Stored in Guidely's private bucket (
attachments/<project>/<event>/…) and deleted with the project's events (event retention). Turn storage off under Spike protection and attachments. - Never public: they are read through the dashboard API with a signed-in session.
GET /api/v1/projects/:id/errors/events/:eventId/attachmentslists them; eachurldownloads one (images, plain text and JSON open inline as inert content;?download=1forces a download). In HIPAA workspaces opening one is audit-logged (phi.error_attachment_view).
Session Replay
Sentry.replayIntegration() recordings become Guidely recordings: every segment (replay_recording, rrweb events, compressed by the SDK's worker or plain) is a chunk of a recording whose session id is the Sentry replay id. They appear on the Replays page with the user, browser, OS, URL and release, and an error with the replay's id (replayId tag or contexts.replay) links to the moment it happened. The project's recording settings apply (Settings → Privacy & data: recording off drops segments, counted under Dropped events) and new recordings count against the replays allowance. Masking is the Sentry SDK's (maskAllText, blockAllMedia are on by default there).
Security reports (CSP)
Point report-uri (or a report-to endpoint) at the security URL above. Optional &sentry_environment= and &sentry_release= set the environment and release. Each report becomes an error issue (type CSP violation, platform csp) titled like Sentry's ("Blocked 'script' from 'cdn.example.com'", "Blocked unsafe inline 'style'"), with tags for the directive, blocked URI and host, grouped by directive and blocked host. Both the application/csp-report format and Reporting API batches (application/reports+json) are read; Expect-CT and HPKP reports become Expect-CT failure / HPKP failure issues. Reports caused by extensions and browser internals are dropped by the browser-extensions filter. They count as errors against your plan, under the security rate-limit category.
Native crashes (minidumps)
- Minidump endpoint: a multipart upload with the dump in
upload_file_minidump. Event fields come from asentryfield holding JSON,sentry[…]fields (sentry[release]=1.2,sentry[tags][channel]=beta) and sentry-native's__sentry-event/__sentry-breadcrumb*files; other fields (Crashpad annotations) go toextra, other files become attachments. The response body is the event id. - In an envelope (sentry-native's Breakpad and in-process backends): an event with an
event.minidumpattachment.
The dump is stored as an attachment and read for what it tells cheaply: the crash reason (EXCEPTION_ACCESS_VIOLATION_READ, SIGSEGV, EXC_BAD_ACCESS…), the faulting address and module, the crashed thread, the OS and CPU, and the loaded modules with their debug ids. An event without an exception becomes an issue of type Minidump ("EXCEPTION_ACCESS_VIOLATION_WRITE at 0x0000000140001234 in app.exe"), level fatal, grouped by crash reason and module. Full stack walking with debug files isn't done yet.
Source maps
Errors are symbolicated with uploaded maps, found in this order:
- Debug id: the frame's file has a debug id (Sentry SDKs send them in
debug_metawhen the build was injected) and a map with that id was uploaded. Works whatever URL or release the file is served under. - Release + path: the event's
releaseand the script's URL path. - Path only: a map uploaded without a release (applies to every release), or, for events without a release, the newest upload for the path.
Guidely's CLI
@guidelytech/sourcemaps uploads by release + path, and also injects and sends debug ids (key with sourcemaps:write as GUIDELY_KEY):
npx @guidelytech/sourcemaps inject --dir dist
npx @guidelytech/sourcemaps upload --dir dist --release "$GIT_SHA" --delete-after
It also creates releases, sets their commits and records deploys (releases.md).
See the @guidelytech/sourcemaps README.
Using sentry-cli and the bundler plugins
export SENTRY_URL=https://guidelytech.com SENTRY_ORG=<workspace-slug> SENTRY_PROJECT=<project-slug> SENTRY_AUTH_TOKEN=gly_sk_…
npx @sentry/cli sourcemaps inject ./dist
npx @sentry/cli sourcemaps upload --release "$GIT_SHA" ./dist # --release is optional with debug ids
The Vite, webpack, Rollup, esbuild and Next.js plugins take the same values (url, org, project, authToken). They upload artifact bundles: sentry-cli asks which chunks are missing, uploads them (SHA-1 named, gzip, up to 8 MB each) and asks Guidely to assemble the bundle; each source map in it is stored with its debug id under the path of its minified file (~/ means any host). Repeat uploads of the same bundle are answered at once. Chunks that are never assembled are deleted after a day. Release-file uploads of sentry-cli 1.x aren't supported; use 2.x or later.
Limits
| Envelope | 40 MB (compressed and uncompressed) |
| Event / transaction item | 1 MB; stored payload 256 KB (breadcrumbs and frame variables trimmed first) |
| Security report request | 64 KB, up to 20 reports |
| Minidump | 30 MB |
| Attachment | 30 MB each; 40 MB and 20 files per event |
| Replay segment | 16 MB uncompressed |
| Chunk upload request | 33 MB, 4 chunks of 8 MB; assembled file 512 MB |
Code map
apps/web/src/server/sentry/ingest.ts: the envelope pipeline (limits, thenprepare.ts: user-agent contexts, minidumps,filters.ts,scrub.ts),outcomes.ts(rate-limit headers, dropped counts),settings.ts(per-project settings inProject.settings.sentryIngest).handlers/attachment.ts,client-report.ts,replay.ts,security.ts;security.ts,native.tsandminidump.tsfor the security and minidump endpoints.chunks.ts(chunk store shared by every assemble endpoint) andartifact-bundle.ts.apps/web/src/server/services/error-attachments.ts,sentry-ingest.ts,sourcemaps.ts.