Sauron 👁️

Unified error reporting + product analytics — Sentry-style crash/error grouping and PostHog-style product events in one platform, on one timeline. When an error fires you can see the same person's events; when you look at a person you see their errors. One SDK emits both signals.

📖 Documentation: see the wiki. Jump to:

• Getting Started · Architecture — how it works under the hood · Ingest Wire Contract · Capabilities — the SDK feature-parity matrix (v0.3.0)
• SDKs: Browser · Flutter · Node · Python · C#
• Guides: Framework Integrations · Best Practices · Troubleshooting

This repository is a working MVP: a client SDK emits an error or event → the backend ingests, groups, and enriches it → the dashboard shows the grouped issue and the analytics. Session replay/video, ClickHouse/Kafka/object storage, SSO, and billing are intentionally out of scope for this cut (see plan.md for the full product vision).

 @edraj/sauron-browser  ┐                        ┌─────────────────────────────┐
 sauron_flutter   ├── gzip envelope ──────▶│ sauron-ingest (axum edge)   │
                  ┘  POST /api/{env_id}/    │  DSN auth → rate-limit →     │
                     envelope               │  validate → Redis stream     │
                                            │  → [co-located workers]:     │
                                            │    enrich → fingerprint →    │
                                            │    group into issues         │
                                            └──────┬────────────┬──────────┘
                                          Postgres │            │ Redis
                                            ┌───────▼──┐   ┌─────▼────┐
                                            │ Postgres │   │  Redis   │
                                            └───────▲──┘   └─────▲────┘
                        axios + JWT                 │            │
     dashboard (Svelte SPA) ────────────────▶ sauron-api (axum, JWT)

• Write path (SDK → ingest): authenticated by the non-secret DSN public key, rate-limited per app, fire-and-forget (202). Workers drain a Redis stream and write durable rows.
• Read path (dashboard → api): JWT auth, with fine-grained RBAC enforced per request.

Stack: Rust + axum + diesel-async + JWT · PostgreSQL + Redis · Svelte + axios · JS/TS + Flutter SDKs · Docker Compose.

Organization
  └─ Project        (grouping / product)
       └─ App       (app_type)
            ├─ Environments   (each with its own DSN — the ingest unit; every app
            │                  starts with one, `dev`, marked default)
            └─ Issues, Events, People   (keyed by app_id)

One product ("Project X") can hold many heterogeneous apps (e.g. 3 Flutter apps + 2 webapps). Every app is created with one environment named dev (marked default), and can hold more (e.g. dev, staging, production) — each with its own DSN, managed under Settings → Environments. app_type ∈ web · flutter · ios · android · react_native · node.

Fine-grained RBAC. Atomic permissions (issue:read, issue:write, event:read, app:*, env:*, project:*, member:*, role:manage, org:manage) are bundled into roles. Four presets ship — Owner ⊇ Admin ⊇ Developer ⊇ Viewer — plus custom roles. A user is granted a role at org, project, or app scope; permissions resolve as a union down the tree (an org grant covers everything; a project grant covers its apps but not siblings; an app grant is narrowest). So "Admin of Project X, Viewer of Project Y" is expressible. Grants and custom roles are guarded against privilege escalation (you can't grant permissions you don't hold). The dashboard reads GET /v1/orgs/{org}/access and hides actions the caller can't perform. See docs/audit-2026-07-12-rbac.md.

backend/          Rust Cargo workspace
  crates/
    sauron-core       envelope wire contract, fingerprint algorithm, config
    sauron-db         diesel schema/models, async pool, repositories, migrations
    sauron-redis      DSN cache, rate limiter, ingest stream, HLL counters
    sauron-auth       argon2, JWT, axum extractor + authorization helpers
    sauron-pipeline   enrich → fingerprint → issue upsert; the worker loop
    sauron-telemetry  tracing setup
  bins/
    sauron-ingest     SDK edge + co-located worker pool
    sauron-api        JWT dashboard API
    sauron-migrate    one-shot migration runner
    crebain           load/benchmark generator (isolated ephemeral stack)
dashboard/        Vite + Svelte 5 (runes) + TypeScript + axios SPA
sdks/
  js/             @edraj/sauron-browser (TypeScript, tsup)
  flutter/        sauron_flutter (Dart)
examples/
  svelte-web/     runnable demo webapp wired to @edraj/sauron-browser
  flutter-app/    runnable demo app wired to sauron_flutter
docs/             design specs + the RBAC security/performance audit

Deploying rather than evaluating? INSTALL.md covers all three install paths — Docker, Fedora/RHEL, Debian/Ubuntu — and the environment variables that matter.

cp .env.example .env        # then set JWT_SECRET and NOTIFY_SECRET_KEY
docker compose up --build

• Dashboard → http://localhost:10002
• API → http://localhost:10000
• Ingest → http://localhost:10001

Compose publishes on the 10000 range on purpose: inside their containers the services still bind :8080 / :8081 / :80, but remapping on the host leaves 3000/8080/8081 free for a local dev stack (below) to run alongside. .env.example ships the matching API_BASE_URL / INGEST_BASE_URL / CORS_ALLOWED_ORIGINS; if you change the ports: mappings, change those too.

Register in the dashboard, create a project → an app (it starts with one environment, dev), copy that environment's DSN from Settings → Environments into an SDK, and watch the first event land. The environment an event belongs to is proven by the ingest key it arrived with, so it cannot be spoofed by a client.

First build compiles the Rust workspace three times (one per service image); subsequent builds are cached.

For a Docker-less deployment Sauron ships as four native packages — sauron, sauron-server, sauron-dashboard, sauron-cli — driven by systemd. Postgres and Redis/Valkey are external and are neither installed nor configured for you.

Fedora / RHEL family (RPM):

./packaging/rpm/build-rpm.sh                 # needs rust, cargo, node, rpm-build
sudo dnf install ~/rpmbuild/RPMS/$(uname -m)/sauron-*.rpm

Debian / Ubuntu (.deb, built for Debian 12 and Ubuntu 22.04 separately — glibc 2.36 vs 2.35, so the two are not interchangeable):

./packaging/deb/build-deb.sh                 # needs rustup + NodeSource; distro rustc/node are too old
cd build/deb && sudo apt-get install ./sauron_*.deb ./sauron-server_*.deb ./sauron-dashboard_*.deb ./sauron-cli_*.deb

The two differ in one operator-visible way: the RPM enables the daemons but starts nothing, while the .deb follows Debian policy and starts them on install — so a fresh, unconfigured Debian host shows failed units until you set DATABASE_URL. The install itself still succeeds.

Full instructions: INSTALL.md — all three install paths plus the environment variables that matter and where each one lives. Per-format detail in packaging/rpm/INSTALL.md and packaging/deb/INSTALL.md; day-two operations in packaging/rpm/SETUP.md (provision DB/Redis, migrate, enable services, dashboard).

Migrations run automatically on an RPM host: every sauron-* daemon unit carries Requires=sauron-migrate.service, so starting or restarting one applies pending migrations first and the daemon refuses to start if that fails. The trade is that a Postgres outage longer than MIGRATE_WAIT_SECS (default 120) leaves the daemons down until someone starts them by hand — systemd never retries a failed start job. The Compose stack is unaffected; run make migrate there.

Upgrading to this release is one-way for notification channels. The first sauron-api boot encrypts every channel's config into config_enc and blanks the legacy plaintext config to '{}' (migration 2026-08-09-000046, a security fix — webhook URLs and Authorization headers were previously stored in cleartext). A downgraded binary reads the empty column and every notification delivery silently goes nowhere. dnf downgrade does not run down.sql, so recovery is to roll forward; a manual diesel migration revert of that migration is unrecoverable. See SETUP.md section 11.

make dev-infra                                   # just Postgres + Redis
export DATABASE_URL=postgres://sauron:sauron@localhost:5432/sauron
export REDIS_URL=redis://localhost:6379
export JWT_SECRET=dev-secret-change-me
make migrate                                     # apply migrations
make api        # terminal 1   (:8080)
make ingest     # terminal 2   (:8081)
cd dashboard && npm install && npm run dev       # terminal 3 (:3000, matches API CORS)

Every backend service is configured purely from the environment — no config file, no config crate. The parser lives in backend/crates/sauron-core/src/config.rs and is deliberately hand-rolled so the env-var → field mapping stays predictable in a container. A variable that is unset or blank falls back to its default, and an unparseable value silently falls back too, so a typo'd number is never fatal.

All binaries share one Config struct but read only the subset they need. Used by below names the services that actually consume each variable: api (sauron-api), ingest, monitor, alerts, tier, inspector (sauron-inspector), migrate, dashboard.

Docker Compose reads these from a .env file at the repo root — copy .env.example and edit. RPM installs read them from /etc/sauron/*.env, split per service (see packaging/rpm/SETUP.md).

The Default column is the built-in fallback compiled into the binary — what you get with the variable unset. Each deployment mode ships its own values on top: Compose remaps the browser-facing URLs to the 10000 range (see the quick start above), and the RPM /etc/sauron/*.env files pin the direct-bind ports. Where a table default and your deployment disagree, the deployment's env file wins.

Upgrading a Compose deployment: four ingest variables now take effect that previously did not. INGEST_MAX_BODY_BYTES, INGEST_BACKLOG and INGEST_DB_POOL had no entry in the ingest service, so setting them in .env did nothing; they are now passed through. INGEST_RATE_LIMIT_PER_MIN changed from a hard-coded 6000 to a pass-through, so a value in your .env now wins where it was previously ignored. The shipped .env.example values equal the binary's defaults, so a stock deployment behaves identically — but if you ever set one of these in .env believing it worked, it becomes live at your next docker compose up. Check those four lines before upgrading.

Eight of these are not settable through Compose. The general rule above — "Compose reads these from a .env file at the repo root" — does not hold for every row, because docker-compose.yml's ingest service has no env_file: key. A variable reaches that container only if the service lists it explicitly. Measured against the shipped file, the service lists INGEST_PORT, INGEST_BACKLOG, WORKER_CONCURRENCY, INGEST_DB_POOL, INGEST_RATE_LIMIT_PER_MIN, INGEST_MAX_BODY_BYTES, INGEST_TRUST_FORWARDED_HEADERS, INGEST_METRICS_ADDR and INGEST_METRICS_SAMPLE_SECS. It does not list INGEST_BATCH_SIZE, INGEST_BATCH_ITEMS, INGEST_STREAM_MAXLEN, INGEST_UDS_PATH, INGEST_DLQ_MAXLEN, INGEST_DLQ_RETENTION_HOURS, INGEST_FAILURE_PAYLOAD_CAP or INGEST_FAILURE_RETENTION_DAYS — putting any of those in .env is silently inert under Compose. They work on RPM and bare metal, where the process reads its own environment. To use one under Compose, add it to the ingest service's environment: block first.

WORKER_CONCURRENCY and INGEST_BATCH_SIZE cannot be swept one at a time. From the 3×3 grid in docs/benchmarks/2026-08-04-tier3-envelope-fold.html, measured 2026-08-04. Each cell is items written/s · peak ingest RSS, from one 60 s run; the bold cell is the shipped pair:

Read the batch-50 column downward: going from 4 workers to 16 measured 22% slower (7,845 → 6,141). At 50-entry batches the workers contend on commits rather than amortizing them, so a one-dimensional sweep of WORKER_CONCURRENCY would have concluded the concurrency knob was already optimal.

INGEST_BATCH_SIZE has never been pinned in any shipped config, so its default of 200 was already in force. The worker count was pinned to 4, so the effect of unpinning it is the batch-200 row: 12,910 → 18,987 items/s, +47% — a pinned deployment was running at 68% of the tuned rate. Do not quote the report's +142% for this change alone; that figure bundles the batch 50 → 200 move, which had already shipped via the code default.

Three caveats travel with these numbers:

• The shipped cell is not the largest number in the table. The top four points fall within 1.6% of each other and are all demand-limited — 19,029 items/s essentially is the offered rate of 19,199 items/s. The honest reading is "these four are indistinguishable", so the gap over the old default is a floor, not a measured ceiling.
• 8 workers at batch 200 was chosen on memory, not throughput — 184 MB where 16/500 needs 405 MB at the same rate.
• One 60 s run per cell, which the report itself says justifies changing a default and not much more. The grid was also swept on the pre-envelope-fold build; the report's section 08 flags it as deserving a re-sweep.

Raising WORKER_CONCURRENCY above 8 requires raising INGEST_DB_POOL with it. Note also that nothing logs the effective worker count or pool size, so neither value can be confirmed from a running host's journal.

Daily install and uninstall counts pulled from Google Play and the Apple App Store by sauron-storesync, shown on Overview when the app's designated store environment is selected.

Neither store offers a plain API for this. Google Play's numbers come from the Play Console's Cloud Storage reports bucket (monthly CSV per package, read with a service account); Apple's come from the App Store Connect Analytics Reports API, which must be requested once and then takes roughly 24–48 hours before it publishes anything — that wait shows in the dashboard as pending, not as an error. Both lag one to three days and are keyed to a package or bundle id, so the numbers are app-wide and have no environment dimension.

What each number counts, since the two stores do not agree by default:

Apple's updates are excluded because Play reports upgrades separately and this connector ignores that column — dropping both is what makes the two halves of the chart comparable. Unique Devices is used in preference to Apple's Counts for the same reason: it is device-based, like Play's figure, whereas Counts counts a redownload on one device twice. All of this lives in named constants at the top of backend/crates/sauron-store/src/apple.rs if you want it counted differently.

Monitor up/down alerts fire inline from sauron-monitor; only the metric rules need the sauron-alerts service. Without it those rules are creatable in the UI but never evaluate.

Back up NOTIFY_SECRET_KEY. Losing it is unrecoverable.

It is the only thing that can decrypt notification_channels.config_enc and secret_enc. There is no escrow, no recovery, and no derivation from any other value — deliberately, because the old behaviour (derive it from JWT_SECRET whenever it was unset) meant a routine JWT rotation silently destroyed every stored channel credential, and nothing surfaced it until an alert failed to deliver. If the key is lost or changed, the only remedy is to delete and re-create every notification channel; the API will report config_error: true on the ones it can no longer read, and deliveries will fail with secret decrypt failed.

Upgrading from a build that had the JWT_SECRET fallback? Set NOTIFY_SECRET_KEY to that deployment's existing JWT_SECRET value before restarting. That is the key the stored rows were actually encrypted under. It also preserves outstanding unsubscribe links, which are signed with a key derived from the same value. The RPM's %post does this for you; Docker and hand-rolled deployments must do it explicitly.

Deployment-level mail addressed to a person — password resets today, digests later. Separate from the notification channels above: those carry an org's own SMTP credentials, so routing a user's reset link through one would tell that org's admin the user asked for a reset, and would strand a user who belongs to no org entirely. Leaving SMTP_HOST unset disables password reset and degrades nothing else — the API boots and serves normally, and logs one INFO line saying why. Only sauron-api reads these; it is also the only process that drains the queue.

Emails containing a link also need DASHBOARD_URL. Without it the message refuses to render rather than sending a link to nowhere.

Finds developer-supplied personal data in the telemetry jsonb columns, masks it irreversibly in hot Postgres, and enforces the mask on future ingest. Masking does not reach cold Parquet, the Redis dead-letter queue or anything already delivered by an alert — every surface says so, and so does this table.

INSPECTOR_ENABLED is off by default because the scanner reads the same partitions the ingest path writes. sauron-inspector opens its own 4-connection pool: raise Postgres max_connections to at least 150 before enabling it, or exhaustion surfaces as sauron-api 500s and sauron-ingest returning 202 and then dropping the event. The three keys marked shared below are read by more than one binary and, on an RPM host, live in /etc/sauron/sauron.env rather than inspector.env — the units that need them never load inspector.env.

The dashboard is a static bundle, so these are read at container start and written into config.js. They describe the URLs as the browser sees them — host-published ports, not Compose-network service names.

Consumed by docker-compose.yml itself — they provision the bundled Postgres container and are interpolated into every service's DATABASE_URL.

The runnable apps under examples/ read their own DSN from the environment so the SDKs themselves stay config-free. Not used by the backend.

Web (@edraj/sauron-browser):

import { Sauron } from '@edraj/sauron-browser';
Sauron.init({ dsn: 'http://<public_key>@localhost:8081/<environment_id>' });
throw new Error('hello from the browser');   // auto-captured & grouped
Sauron.track('checkout_completed', { cart_value: 42.5 });
Sauron.identify('u_42', { plan: 'pro' });

Flutter (sauron_flutter):

await Sauron.init(
  SauronOptions(dsn: 'http://<public_key>@localhost:8081/<environment_id>'),
  appRunner: () => runApp(const MyApp()),
);
Sauron.track('checkout_completed', properties: {'cart_value': 42.5});

One JSON envelope, shared by both SDKs and the backend (defined in backend/crates/sauron-core/src/envelope.rs; a golden fixture guards parity across all three test suites):

POST /api/{environment_id}/envelope
X-Sauron-Key: <public_key>          # or ?k=<public_key> for sendBeacon
Content-Encoding: gzip              # optional

The DSN's key identifies exactly one environment (and therefore one app, project and org); the {environment_id} path segment is informational only — the gateway authenticates on the key alone, so an event's environment is proven by the key it arrived with and cannot be spoofed by a client. See the Ingest Wire Contract for the full DSN shape.

Error grouping is line-number–independent: two occurrences of the same bug on different lines/releases collapse into one issue.

cd backend && cargo test --workspace     # fingerprint grouping, JWT, envelope parity
cd sdks/js && npm test                   # envelope shape, stacktrace parsing, offline queue
cd sdks/flutter && flutter test          # golden envelope, error capture, queue

An end-to-end check — register → create project → POST an envelope to :8081 → the grouped issue appears via :8080 — is described in plan.md under Verification.

Sauron is split across two licences, by component.

Server — the backend/ workspace and the dashboard/, and the sauron RPM built from them: AGPL-3.0-only, GNU Affero General Public License v3.0. The Affero network-use clause applies: offering a modified Sauron to users over a network obliges you to offer them the corresponding source.

Client SDKs — everything under sdks/ (Flutter, JS, Node, Python, C#): LGPL-3.0-only, GNU Lesser General Public License v3.0, each with its own LICENSE and the GPLv3 base text it extends in COPYING. Linking an SDK into your application does not place your application under copyleft — which is the point of licensing them apart from the server.

1.8.0 briefly applied LGPL-3.0-only to the server as well. That was broader than intended and is corrected in 1.8.1; 1.8.0 itself remains available under the terms it was published with.