Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

kestrel-spike

Throwaway spike for Keen Kestrel, a small self-hosted, Sentry-compatible error tracker (Rust + SQLite). It is not product code. It answers two questions with real data:

  1. Can a tiny Rust server take a real iOS crash from the official sentry-cocoa SDK and dSYMs uploaded by the official sentry-cli, then symbolicate the crash with getsentry's symbolic crates? That means demangled Swift names, file and line, and inlined frames.
  2. Does that server build as a fully static musl binary in an Alpine/scratch image, given that the Swift demangler in symbolic-demangle is C++? How big is the image?

Layout

Path What
server/ Rust spike server (axum 0.8, tokio, symbolic 13.9.0) and its static Dockerfile
ios/ SwiftUI test app with sentry-cocoa 9.30.2, generated by XcodeGen from project.yml
ci/ Scripts used by the workflow (crash loop, assertions, Linux smoke test)
.github/workflows/spike.yml ios-e2e (macOS 15, simulator) and linux-musl (Ubuntu, Docker)

Server

Endpoint Purpose
POST /api/{project_id}/envelope[/] Sentry envelopes. Auth comes from X-Sentry-Auth or ?sentry_key=, and any key works. Handles gzip, deflate and br.
GET /api/0/ Auth info for sentry-cli
GET /api/0/organizations/{org}/chunk-upload/ Chunk upload options (sha1, gzip, 8 MiB chunks)
POST /api/0/organizations/{org}/chunk-upload/ Multipart chunks (file or file_gzip, file name = sha1)
POST /api/0/projects/{org}/{project}/files/difs/assemble/ Assembles a file from its chunks, then builds one SymCache per object
GET /healthz Health check
anything else Logged as unhandled. GET answers []

Every envelope request is written to $CAPTURE_DIR/<millis>-<n>.envelope (raw body, usually gzip) plus .headers.json. For each event item the server writes:

  • $CAPTURE_DIR/<event_id>.event.json: the decoded event
  • $CAPTURE_DIR/<event_id>.symbolicated.json: the report. Each frame has instruction_addr, image, function (demangled, Swift "simplified UI" form), function_full, symbol (raw mangled), filename/abs_path, line, inlined, symbolicated (true = resolved from an uploaded dSYM) and raw_function (what the SDK sent)

DIF storage lives in $DATA_DIR: chunks/, files/ and difs/<debug_id>/symcache.

For each frame, symbolication finds the image in debug_meta.images whose range contains the address. It then looks up the SymCache by the image's debug id and queries the offset from image_addr, which is relative to the object's own vmaddr, as SymCaches are. Return addresses get the usual caller adjustment (symbolic_common::InstructionInfo). The lookup then expands inlined frames (innermost last, in Sentry's caller-first order) and demangles Swift names. Frames from images without a SymCache keep the name the SDK sent.

kestrel-spike                 # serve (BIND_ADDR=127.0.0.1:9000, CAPTURE_DIR=captures, DATA_DIR=data)
kestrel-spike --version
kestrel-spike symbolicate <event.json | .envelope> [--dif <file|dir|.dSYM>]... [--data-dir DIR] [--out FILE]

How the workflow works

ios-e2e runs on macos-15 with Xcode 26.2 and the newest iOS simulator runtime, on a freshly created iPhone 16 simulator:

  1. Builds the server and starts it on 127.0.0.1:9000.

  2. Runs xcodegen generate and an xcodebuild Release build for the simulator with dwarf-with-dsym and stripping (DEPLOYMENT_POSTPROCESSING=YES, STRIP_STYLE=all). The job fails if nm still finds CrashPipeline, CrashSite or detonate symbols in the app binary.

  3. Runs sentry-cli debug-files upload --wait against the server. The job fails if there is no SymCache for the app's UUID(s).

  4. For each crash kind (fatal = fatalError, unwrap = force-unwrap of nil, nsexception = NSException.raise()), the job:

    • launches the app with -crash <kind>; it crashes 2 s after SentrySDK.start, with no debugger attached
    • waits until the process is gone
    • relaunches the app normally, so sentry-cocoa sends the stored crash report (plus a handled capture(error:) event)
    • runs ci/check_crash.py, which waits up to 3 min for the new crash event and its .symbolicated.json

    check_crash.py passes when the crashed stack has app frames resolved from the dSYM that include CrashSite.crash(_:), CrashPipeline.run(_:), CrashPipeline.Stage.detonate(_:) and trigger(_:depth:). They must be in CrashSite.swift with plausible line numbers, and trigger must be an inlined frame. The raw event must not contain those names for app frames.

  5. Writes a readable stack per crash and a table of all captured events to the job summary.

  6. Uploads the ios-e2e artifact: captures/ (envelopes, headers, events, symbolicated reports), KestrelSpike.app.dSYM.zip, the stripped app binary, difs/ (SymCaches) and logs/ (server log, app stdout/stderr, simulator log and crash reports on failure). These are meant to become test fixtures for Keen Kestrel.

linux-musl runs on ubuntu-24.04 after ios-e2e, even when that job failed:

  1. Runs docker build server. This is a rust:1.99.1-alpine3.24 builder with build-base (g++, static libstdc++) and a scratch runtime.
  2. Proves the binary is static with --version, file and ldd, and writes the image and binary size to the summary.
  3. Runs ci/linux-smoke.sh: real sentry-cli (Linux) uploads a small ELF with DWARF to the static binary, then a gzip envelope with a native event is symbolicated, including an inlined frame. This checks the protocol without iOS.
  4. If the ios-e2e artifact exists, runs kestrel-spike symbolicate inside the musl image on every captured iOS event with the uploaded dSYM. It then checks that the result is frame for frame identical to what the macOS server produced.

Reading the results

  • Job summary of ios-e2e: one section per crash kind with PASS/FAIL and a table that lists the most recent call first. A good result looks like libswiftCore / trigger(_:depth:) (inlined, CrashSite.swift:NN) / specialized CrashPipeline.Stage.detonate(_:) / CrashPipeline.run(_:) / static CrashSite.crash(_:) / SwiftUI and UIKit frames (unsymbolicated, no dSYM). The "raw app function names" line shows what sentry-cocoa itself sent for app frames. It should be none or names that don't come from the app.
  • Job summary of linux-musl: image size, binary size, file/ldd output and "identical" per re-symbolicated iOS event.
  • Artifact ios-e2e: open captures/<event_id>.symbolicated.json next to captures/<event_id>.event.json to compare raw and symbolicated frames. logs/server.log shows every request the SDK and sentry-cli made, including unhandled ones.

Local use

cd server && cargo run                      # serve on 127.0.0.1:9000
sentry-cli --url http://127.0.0.1:9000 --auth-token x debug-files upload --org spike --project spike --wait path/to/App.dSYM
cargo run -- symbolicate captures/<id>.event.json --dif path/to/App.dSYM
docker build -t kestrel-spike server && docker run --rm kestrel-spike --version

Notes and limits

  • sentry-cli 3.x only supports chunk upload for debug files. It no longer falls back to the legacy files/dsyms/ zip endpoint, so the spike has no legacy endpoint.
  • Assembly runs synchronously inside the assemble request, so the first poll after the chunks are uploaded already returns ok with the dif record.
  • symbolic-symcache depends on symbolic-debuginfo with default features, so every object format (ELF, PE/PDB, Breakpad, WASM, ...) gets compiled in. Trimming features on our side has no effect.
  • Nothing is persisted in a database. Everything is files. No auth checks.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages