Error monitoring in Guidely's own SDKs
Every Guidely SDK (web, React, Next.js, Svelte/SvelteKit, Electron, Node, Java, PHP, iOS, Android, React Native, Flutter) reports errors and crashes with the same capture API Sentry SDKs have, so an app can drop Sentry and keep its breadcrumbs, tags, contexts, linked errors and native crash reports. Apps that keep a Sentry SDK can point its DSN at Guidely instead (ingest.md); both kinds of event land in the same issues.
Capture API
| Sentry | Guidely | Notes |
|---|---|---|
Sentry.captureException(err, { tags, extra, level, fingerprint }) | guidely.captureException(err, { tags, extra, level, fingerprint, contexts }) | Any other key in the second argument is kept as an event property (the pre-existing captureException(err, props) form). |
Sentry.captureMessage(msg, level) | guidely.captureMessage(msg, level) | level defaults to info. Groups by message. |
setTag, setTags, setExtra, setExtras, setContext | same names | Apply to every later event of the installation. setContext(name, null) removes it. |
setUser({ id, email, username }) | guidely.setUser(...) / identify(id, traits) | setUser calls identify with the id and keeps email/username on errors. setUser(null) = reset(). |
addBreadcrumb({ category, message, level, data, type }) | same | The last 100 breadcrumbs ride along with each error. |
beforeSend(event), beforeBreadcrumb(crumb) | same options | Return null to drop; may edit and return the object. Exceptions thrown in a hook are swallowed (the event is sent unchanged). |
sampleRate | errors.sampleRate (0–1, default 1) | Applies to errors only (crashes included). |
ignoreErrors, denyUrls, allowUrls | errors.ignoreErrors, errors.denyUrls, errors.allowUrls | Strings match as substrings, RegExps as patterns; ignoreErrors against "<type>: <message>" and the message, the URL lists against the innermost frame's file. |
Options sit under errors (createGuidely({ errors: { sampleRate: 0.5, beforeSend } })) on the web and Node, and in the platform's options object elsewhere (GuidelyOptions.errors on iOS, Android and Flutter; errors={{ … }} on React Native; ErrorOptions on Java/PHP). captureErrors: false keeps working: it stops the automatic handlers, not manual captures.
Consent and analytics switches apply exactly as for every other event: nothing leaves the device before consent is granted, and a project with error tracking off stores nothing. Crash reports written while consent was pending are sent once it is granted, and deleted when it is denied.
Automatic breadcrumbs
| Category | Web | Node | Mobile | Data |
|---|---|---|---|---|
ui.click | Clicks (CSS selector of the element, masked text never) | Taps (the click selector) | selector | |
navigation | history.pushState/popstate/hashchange | screen() | from, to | |
console | console.warn / console.error (and log when enabled) | same | level, message, arguments | |
fetch / xhr (type: "http") | Method, URL (query stripped), status, duration | http/https requests | URLSession / OkHttp when replay network capture is wired | method, url, status_code, duration_ms |
query (type: "query") | SQL statements of pg, mysql2 and Prisma (literal values taken out), once instrumented; the PHP SDK records PDO and Laravel queries the same way | db.system, db.name, duration_ms, rows, error | ||
guide | Guide shown / step / completed / dismissed | same | guideId, stepIndex | |
app.lifecycle | foreground / background | state |
Requests to Guidely's own API are never recorded. URLs keep only origin and path.
Wire format
Guidely SDKs send exceptions as exception events. Two parts:
properties(inside the event's 8 KB property budget) index the occurrence:type,message,frames(GuidelyStackFrames, innermost first, ≤ 30),source,handled,level,platform,mechanism,releaseand any user properties.detail(new, optional, ≤ 64 KB of JSON) carries everything else in the Sentry event shape (https://develop.sentry.dev/sdk/data-model/event-payloads/), so one issue page renders Guidely and Sentry events alike. The server moves it intoErrorEventDetailand keeps theProductEventrow small.
{
"eventId": "…", "name": "exception", "occurredAt": "…", "anonymousId": "…", "sessionId": "…",
"userId": "u_42", "url": "https://app.example.com/checkout", "appVersion": "2.4.1",
"properties": {
"type": "TypeError", "message": "x is undefined",
"frames": [{ "fn": "pay", "file": "https://app.example.com/assets/app.js", "line": 1, "col": 3456, "inApp": true }],
"source": "onerror", "handled": false, "level": "error", "platform": "javascript", "mechanism": "onerror"
},
"detail": {
"level": "error",
"exception": { "values": [ /* causes first, the thrown exception LAST */
{ "type": "Error", "value": "socket hang up", "mechanism": { "type": "chained", "handled": true, "exception_id": 1, "parent_id": 0, "source": "cause" },
"stacktrace": { "frames": [ /* oldest call first, innermost LAST */ ] } },
{ "type": "TypeError", "value": "x is undefined", "mechanism": { "type": "onerror", "handled": false, "exception_id": 0 },
"stacktrace": { "frames": [{ "function": "pay", "abs_path": "https://app.example.com/assets/app.js", "lineno": 1, "colno": 3456, "in_app": true }] } }
] },
"breadcrumbs": { "values": [{ "timestamp": 1767000000.123, "type": "http", "category": "fetch", "level": "info", "data": { "method": "POST", "url": "https://api.example.com/pay", "status_code": 500 } }] },
"contexts": { "browser": { "name": "Chrome", "version": "131" }, "os": { "name": "macOS", "version": "15.2" }, "device": { "family": "Desktop" }, "runtime": { "name": "node", "version": "22.11.0" } },
"tags": { "area": "checkout" }, "extra": { "cartSize": 3 },
"user": { "id": "u_42", "email": "ana@example.com" },
"fingerprint": ["{{ default }}", "checkout"],
"threads": { "values": [{ "id": 1, "name": "main", "crashed": true, "current": true, "stacktrace": { "frames": [] } }] },
"debug_meta": { "images": [{ "type": "macho", "debug_id": "…", "code_file": "/…/MyApp", "image_addr": "0x104000000", "image_size": 81920, "arch": "arm64" }] },
"request": { "method": "POST", "url": "https://api.example.com/pay", "headers": { "user-agent": "…" } },
"transaction": "POST /pay", "server_name": "web-1", "logger": "checkout", "dist": "512"
}
}
Rules every SDK follows:
detailkeys use Sentry's names and orders: exception chain oldest cause first and the thrown exception last; frames oldest call first and the crashing frame last (the reverse ofproperties.frames). Unknown keys are kept but not relied on.- Limits (the server trims to them, SDKs trim first): 64 KB per
detail, 100 breadcrumbs (oldest dropped first), 20 exceptions in a chain, 250 frames per stack, 100 threads, 500 debug images, 50 tags (key ≤ 32, value ≤ 200 characters). Largerdetails are trimmed in that order: breadcrumbs, then framevars, then threads other than the crashed one. Adetailover 1 MB is dropped whole (the event is still stored). properties.level/handled/fingerprintPartswin overdetail.level/ mechanism /fingerprint; when properties omit them, the server fills them fromdetail. Withdetail.exceptionand noproperties.frames, the server derives the frames from the thrown exception.- Credentials never leave the app: cookies,
Authorizationand similar headers, and keys matchingpassword|secret|token|card|…are removed client-side and again on the server. - Server SDKs send the same object through
POST /api/v1/sdk/server/batchas anexceptionmessage:{ type: "exception", messageId, timestamp, userId?, anonymousId?, accountId?, appVersion?, properties, detail? }.
Crashes and sessions (release health)
A crash is an exception the app did not survive: properties.level = "fatal", handled: false, and a mechanism naming the handler:
| Platform | Mechanism (properties.mechanism, detail…mechanism.type) |
|---|---|
| Browser | onerror, onunhandledrejection (uncaught), generic (captureException), message |
| React / Next.js / SvelteKit | react.errorboundary, react (React 19 root handlers), nextjs.onRequestError, nextjs.route_handler, nextjs.server_action, nextjs.global-error, sveltekit.handleError |
| Electron | uncaughtException (main, fatal), render-process-gone / child-process-gone (fatal for crashed / oom / killed), minidump |
| Node | uncaughtException (fatal), unhandledRejection (fatal when it exits the process), express, fastify, koa |
| Java | uncaught (default handler, fatal), request (servlet / Spring reporter) |
| PHP | uncaught (set_exception_handler, fatal), fatal_error (shutdown, fatal), error_handler (warnings), request |
| iOS | nsexception (uncaught NSException), signal (mechanism.meta.signal: { number, name, code }; SIGSEGV, SIGABRT, …), metrickit (MXCrashDiagnostic) |
| Android | uncaught (JVM Thread.UncaughtExceptionHandler), anr, exit_info (native crash from ApplicationExitInfo, no frames) |
| React Native | onerror (ErrorUtils; fatal when RN reports it fatal), unhandledrejection; native crashes via the iOS/Android SDKs |
| Flutter | FlutterError (handled: true), PlatformDispatcher, runZonedGuarded |
properties.source is manual for manual captures and message for captureMessage (with type: "Message", no frames, and detail.message.formatted); for automatic captures it is the mechanism. Other unhandled errors keep level: "error". An Android ANR is type: "ApplicationNotResponding", mechanism: "anr", level: "error", handled: false (not a crash).
The crash's sessionId is the session that crashed (mobile SDKs write it into the crash report and send it on the next launch, which starts a new session). For release health:
- a session with an
exceptionevent wherehandled = falseis crashed (uncaught errors, unhandled rejections and native crashes; ANRs,mechanism: "anr", are not crashes); - a session with any other
exceptionevent is errored; - the release is the event's
appVersion(properties.releasewhen set).
Native frames and debug files
Native frames carry instruction_addr (hex string) and, when known, image_addr, symbol_addr, function (from dladdr), package (the image path) and in_app; debug_meta.images lists the loaded images with their debug_id (Mach-O LC_UUID; ELF build id as a little-endian GUID) and load address. properties.frames carries { fn: function ?? instruction_addr, module: image name, inApp } until the server symbolicates.
- iOS dSYMs and ELF symbols (Android NDK, Flutter
--split-debug-info) are matched bydebug_id. - ProGuard / R8: Java frames (
module= class,function= method,lineno) are retraced with the mapping whose UUID is in adebug_metaimage{ type: "proguard", uuid }, else the newest mapping uploaded for the event's app version. - React Native / Hermes: frames like
address at index.android.bundle:1:9876becomeapp:///index.android.bundleline 1, column 9876 and map through the uploaded (Hermes-composed) source map like any JS frame.
Symbolication runs at ingest, so issues group by the symbolicated innermost in-app frame (an event whose debug file exists but can't be read in time is deferred and the SDK retries, as with source maps), and again when an issue is opened, so files uploaded later still improve old events.
Uploading debug files
With the Guidely CLI (npx @guidelytech/sourcemaps, key with the debug-files:write scope, stored as GUIDELY_KEY):
export GUIDELY_KEY=gly_sk_… GUIDELY_API_URL=https://<your Guidely API>
npx @guidelytech/sourcemaps upload-dif build/MyApp.xcarchive/dSYMs # dSYM bundles, Mach-O, ELF, zips
npx @guidelytech/sourcemaps upload-dif build/app/outputs/symbols # Flutter --split-debug-info
npx @guidelytech/sourcemaps upload-proguard app/build/outputs/mapping/release/mapping.txt \
--app-version 2.4.1 --write-properties app/src/main/assets/guidely-debug-meta.properties
The same CLI creates releases and records deploys (releases new, set-commits, finalize, deploys new; scope releases:write), so CI needs no other tool.
Using sentry-cli
CI that already runs sentry-cli works unchanged (SENTRY_URL=<Guidely API URL>, SENTRY_ORG=<workspace slug>, SENTRY_PROJECT=<project slug>, SENTRY_AUTH_TOKEN=gly_sk_…):
sentry-cli debug-files upload --include-sources build/
sentry-cli upload-proguard app/build/outputs/mapping/release/mapping.txt
Both CLIs use chunked uploads (/api/0/organizations/{org}/chunk-upload/ and /api/0/projects/{org}/{project}/files/difs/assemble/); the legacy /api/0/projects/{org}/{project}/files/dsyms/ zip upload works too. Files are stored privately under debug-files/ and kept 180 days after their last use.
Symbolication on the server
| File | Matched by | Symbolizer |
|---|---|---|
| Mach-O / dSYM | debug_meta.images[].debug_id (LC_UUID); universal binaries by arch | llvm-symbolizer (server image; lines + inlined frames), else atos (macOS dev), else the symbol table (names only) |
ELF (NDK, Flutter --split-debug-info) | debug_id (build id as a little-endian GUID) or code_id (both byte orders, for Flutter iOS) | same |
ProGuard / R8 mapping.txt | { type: "proguard", uuid } image, else the newest mapping with the event's app version | built in (line ranges, inlined calls across classes, exception class names); matches R8's retrace |
Frame addresses are rebased onto the image (instruction_addr - image_addr + image_vmaddr, the __TEXT vmaddr from the file when the SDK sends none); return addresses look up the call instruction (- 1), the crashing frame doesn't. Symbolicated frames are marked symbolicated: true and keep their instruction_addr. Set LLVM_SYMBOLIZER to use a specific binary. Downloaded debug files are cached in the temp directory of each server process.
Platform notes
- Web: breadcrumbs wrap
console,fetchandXMLHttpRequestonce; uninstalling (or another library wrapping them later) makes the wrappers pass through. Guidely's own API calls never become breadcrumbs, and URLs keep only origin and path. The persisted event queue drops thedetailof the oldest events when it would pass 1 MB oflocalStorage(the in-memory queue keeps it). - iOS: stack overflows are caught on the main thread only (the alternate signal stack is installed there); there is no Mach exception handler (
machis a Sentry Cocoa mechanism Guidely understands but doesn't produce); with a debugger attached Xcode stops before the handlers run. MetricKit diagnostics carry no session id; one matching a crash record (same signal and app version, within the diagnostic's time window ± 5 minutes) is skipped. - Android: NDK native crash stacks aren't captured yet (Android 11+ reports that a native crash happened, through
ApplicationExitInfo). The ANR watchdog skips while a debugger is attached and reports once per freeze. - React Native: a fatal JS error in release kills the app right after the handler; the SDK persists the report first (synchronous storage such as MMKV always lands, AsyncStorage is best effort) and sends it on the next start. Upload Hermes-composed maps for
index.android.bundle/main.jsbundlewith--include .bundle.map(or.jsbundle.map) and--url-prefix /. - Flutter: Dart errors don't end the app, so they are
level: error; obfuscated builds keep the obfuscated exception class name (frames are symbolicated). - Server SDKs:
setUserattributes later errors only (noidentifymessage per request).
Code map
packages/shared/src/error-detail.ts: detail limits,trimExceptionDetail,errorFilterDrops; schema field inevents.ts.packages/sdk-core/src/error-monitoring.ts: web scope, breadcrumbs, cause chains; wired inclient.ts.apps/web/src/server/sentry/sdk-detail.ts: Guidelydetail→ErrorEventDetail(via the Sentry normaliser).apps/web/src/server/symbolication/: object parsing (objects.ts), retrace (proguard.ts), symbolizers (symbolizer.ts), payload symbolication (index.ts).apps/web/src/server/services/debug-files.ts+src/app/api/0/…/chunk-upload,difs/assemble,files/dsyms,src/app/api/v1/debug-files/…: uploads, storage (debug-files/<project>/), retention.