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

SentryGuidelyNotes
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, setContextsame namesApply 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 })sameThe last 100 breadcrumbs ride along with each error.
beforeSend(event), beforeBreadcrumb(crumb)same optionsReturn null to drop; may edit and return the object. Exceptions thrown in a hook are swallowed (the event is sent unchanged).
sampleRateerrors.sampleRate (0–1, default 1)Applies to errors only (crashes included).
ignoreErrors, denyUrls, allowUrlserrors.ignoreErrors, errors.denyUrls, errors.allowUrlsStrings 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

CategoryWebNodeMobileData
ui.clickClicks (CSS selector of the element, masked text never)Taps (the click selector)selector
navigationhistory.pushState/popstate/hashchangescreen()from, to
consoleconsole.warn / console.error (and log when enabled)samelevel, message, arguments
fetch / xhr (type: "http")Method, URL (query stripped), status, durationhttp/https requestsURLSession / OkHttp when replay network capture is wiredmethod, 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 waydb.system, db.name, duration_ms, rows, error
guideGuide shown / step / completed / dismissedsameguideId, stepIndex
app.lifecycleforeground / backgroundstate

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 (Guidely StackFrames, innermost first, ≤ 30), source, handled, level, platform, mechanism, release and 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 into ErrorEventDetail and keeps the ProductEvent row 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:

  • detail keys 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 of properties.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). Larger details are trimmed in that order: breadcrumbs, then frame vars, then threads other than the crashed one. A detail over 1 MB is dropped whole (the event is still stored).
  • properties.level / handled / fingerprintParts win over detail.level / mechanism / fingerprint; when properties omit them, the server fills them from detail. With detail.exception and no properties.frames, the server derives the frames from the thrown exception.
  • Credentials never leave the app: cookies, Authorization and similar headers, and keys matching password|secret|token|card|… are removed client-side and again on the server.
  • Server SDKs send the same object through POST /api/v1/sdk/server/batch as an exception message: { 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:

PlatformMechanism (properties.mechanism, detail…mechanism.type)
Browseronerror, onunhandledrejection (uncaught), generic (captureException), message
React / Next.js / SvelteKitreact.errorboundary, react (React 19 root handlers), nextjs.onRequestError, nextjs.route_handler, nextjs.server_action, nextjs.global-error, sveltekit.handleError
ElectronuncaughtException (main, fatal), render-process-gone / child-process-gone (fatal for crashed / oom / killed), minidump
NodeuncaughtException (fatal), unhandledRejection (fatal when it exits the process), express, fastify, koa
Javauncaught (default handler, fatal), request (servlet / Spring reporter)
PHPuncaught (set_exception_handler, fatal), fatal_error (shutdown, fatal), error_handler (warnings), request
iOSnsexception (uncaught NSException), signal (mechanism.meta.signal: { number, name, code }; SIGSEGV, SIGABRT, …), metrickit (MXCrashDiagnostic)
Androiduncaught (JVM Thread.UncaughtExceptionHandler), anr, exit_info (native crash from ApplicationExitInfo, no frames)
React Nativeonerror (ErrorUtils; fatal when RN reports it fatal), unhandledrejection; native crashes via the iOS/Android SDKs
FlutterFlutterError (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 exception event where handled = false is crashed (uncaught errors, unhandled rejections and native crashes; ANRs, mechanism: "anr", are not crashes);
  • a session with any other exception event is errored;
  • the release is the event's appVersion (properties.release when 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 by debug_id.
  • ProGuard / R8: Java frames (module = class, function = method, lineno) are retraced with the mapping whose UUID is in a debug_meta image { 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:9876 become app:///index.android.bundle line 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

FileMatched bySymbolizer
Mach-O / dSYMdebug_meta.images[].debug_id (LC_UUID); universal binaries by archllvm-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 versionbuilt 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, fetch and XMLHttpRequest once; 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 the detail of the oldest events when it would pass 1 MB of localStorage (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 (mach is 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.jsbundle with --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: setUser attributes later errors only (no identify message per request).

Code map

  • packages/shared/src/error-detail.ts: detail limits, trimExceptionDetail, errorFilterDrops; schema field in events.ts.
  • packages/sdk-core/src/error-monitoring.ts: web scope, breadcrumbs, cause chains; wired in client.ts.
  • apps/web/src/server/sentry/sdk-detail.ts: Guidely detail → 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.