Everything SnagSpy does, and how to reach it

Overview

The platform is a modular monolith in Go with a Nuxt dashboard. Two processes matter to you: ingest, which accepts telemetry, and the API, which serves everything you read. They are separate so a flood of telemetry cannot take the dashboard down with it.

Quick start

1. Create an account and a project. Register, then log in — registration deliberately returns no session. Projects are created from the dashboard, or from the API if you would rather script it.
2. Issue a DSN. One per project, from the Projects page in the dashboard. A DSN is scheme://publicKey@host/projectID and is safe to ship in a browser bundle — it can write telemetry and read nothing.
3. Send something. Either SDK below, or plain OTLP to the ingest endpoint.
4. Watch it arrive. The issue appears on the dashboard, under Errors.

JavaScript & the browser

import { init, captureException } from "@snagspy/browser"

init({ dsn: globalThis._importMeta_.env.VITE_SNAGSPY_DSN, environment: "production" })

try { risky() } catch (error) { captureException(error) }

Both SDKs redact secret-shaped values before anything leaves the process. That is not a server-side courtesy — a password sent to us and scrubbed on arrival has still crossed the network.

Concepts

Organisation

The billing and membership boundary. Every piece of data belongs to exactly one, and cross-tenant isolation is a release gate rather than a convention.

Project

One application. Owns its DSNs, its replay consent, and its ingest rate limit.

DSN

A per-project write credential, scheme://publicKey@host/projectID. Public by design: it can write telemetry and read nothing.

API key

A read credential for the dashboard API, scoped to the organisation. Shown once when created.

Event / occurrence

One error as it happened, with its stack, context and correlated signals.

Issue

Occurrences grouped by fingerprint. A minified stack groups on the message plus each frame’s chunk name with the content hash removed, so a redeploy does not split one issue into two.

Trace & span

Standard OTel. The trace list filters on spans and aggregates whole traces, and says which of its numbers are estimates.

Replay unit

The billing unit for session replay: one unit per 64 KiB of uploaded chunk.

Investigation

One AI model call, and the unit every AI feature is metered in: a root-cause analysis, or a code review. Charged when the call is made, before the outcome is known — a failed call still cost a call.

SDKs

Both are thin ergonomics layers over OpenTelemetry rather than instrumentation libraries of their own. What they add is the part that is easy to get wrong: DSN handling, exception recording in the shape the platform groups on, and redaction before send.

The browser SDK normalises every engine’s stack to V8’s shape before sending, and carries debug ids in a span attribute. A debug id is 32 hexadecimal characters with no separators — the SDK strips the hyphens of a canonical UUID for you.

Sending telemetry

The ingest service is separate from the API and listens on its own port (:8081 by default; publish it as INGEST_PUBLIC_URL). It takes OTLP over HTTP, and every route authenticates with a DSN rather than a session.

Two buckets apply to every upload: a per-project request limit and a per-organisation event limit. Both are described on the API reference page.

Session replay

Replay is recorded with rrweb, and masking is inverted from rrweb’s defaults: text is masked unless explicitly allowed, rather than exposed unless explicitly masked. The masking happens in the browser before capture, because nothing server-side can undo an unmasked recording that has already arrived.

The headers on a chunk upload

Content-Type: application/octet-stream
X-Replay-Session: <session id>
X-Replay-Seq: <0, 1, 2, …>
X-Replay-Encoding: json-zstd

The browser SDK sends these for you. The body is opaque compressed bytes that this platform contractually does not read. An absent or unparseable client clock is not an error — the server substitutes its own, because a recording with a wrong timestamp is still worth keeping.

Three things that will refuse you

• The project has not consented. Replay capture is per project and off until it is turned on for that project on the Projects page.
• Your plan does not sell replay. The free tier does not include it, and the upload is refused with plan_excludes_replay naming your plan. This is not a quota — nothing here counts units against a plan figure.
• The chunk is too large. The ceiling is applied to bytes actually read, not to what Content-Length claimed.

Watching a recording takes owner scope, re-checks project consent at read time, and is written to the audit trail before the bytes are read.

Source maps

Artifacts are uploaded per project from your build — the JavaScript SDK ships a Vite plugin that does it for you. The row lives in PostgreSQL and the bytes in an object store, addressed by content, so uploading the same map twice costs one copy.

Frames are resolved at read time, not at ingest. A frame that cannot be resolved says why rather than failing the page, so a missing upload degrades to a minified frame with an explanation instead of an error.

Plans, usage & retention

Usage is metered and reported. It is never acted on at the write path. Going past a plan figure does not throttle you, reject your telemetry or trigger a charge — there is no pay-as-you-go billing here at all. You are told once per signal per billing period, and the message says plainly that nothing has been throttled. The one thing a plan does decide is whether a signal is sold at all: a plan that does not include session replay refuses replay uploads, which is a different act from discarding telemetry somebody paid for.

Retention

A plan narrows the platform ceiling and never widens it. The ceilings are 90 days for errors and events and 30 days for trace spans; log lines follow the trace setting. An organisation may narrow its own retention in its own settings. The audit log is not customer-configurable.

A lapsed plan keeps its data for a further 14 days. Limits, seats and features revert the moment a paid period ends, because paying restores them; the retention window does not, because deleted error history does not come back.

Alerts & integrations

Destinations are configured per organisation. A destination’s kind chooses the notifier, and a kind with no notifier behind it fails loudly rather than being skipped.

Deployments

Record deploys from your pipeline, or connect GitHub or GitLab per project. Each provider is its own webhook adapter, and a deployment records which provider vouched for it rather than only that a webhook did.

Digests

A scheduled summary, set per organisation. You can preview the next one without sending it to anybody.

Cron monitoring & uptime

Create a check, then have your job call its check-in URL — the dashboard issues one per check and hands you a ready-made crontab line. The token in the URL is the credential, so the call is unauthenticated by design: a cron job on a box with no secrets can still report in.

# at the end of your job
curl -fsS "$SNAGSPY_CHECKIN_URL"

A check that does not arrive within its grace raises an alert. Uptime monitors are the other direction: the platform probes a URL you name and records each result against the monitor.

AI investigations

An investigation reads one issue, alert or project and explains what happened. The division of labour is deliberate and worth knowing before you trust an answer: the model selects and phrases; the platform computes. Every figure in an answer comes from a query, not from the model, and an answer that cannot be grounded in one is not given.

• Off entirely unless the deployment is configured with an AI provider key — not failing per request, off.
• Charged per model call, before the outcome is known. A call that failed still cost a call, because charging only on success would hide a runaway loop in the one place you would look for it.
• Reviewing a change is a separate feature behind a separate permission, off until an organisation turns it on. Your build pipeline posts a diff and gets findings back — nothing is read from your repositories, because the platform holds no credential that could, and the diff is not stored. A review is one model call and draws on the same allowance an investigation does.
• Declinable per organisation. The data sent is a deliberately minimised subset of a single issue: exception type, message, stack, culprit, counts and the correlated release. Never end-user identifiers, never raw attribute bags, never whole events.

Self-hosting

The stack is Docker Compose: PostgreSQL, Redis, ClickHouse, the API, ingest, a worker and a one-shot migrate service. Everything is configured by environment.

Configuration variables

DATABASE_URL

PostgreSQL connection string. No default.

REDIS_URL

Redis, used for rate limiting. No default.

ENV

development (default) or production. Production refuses sandbox payment deliveries.

LOG_LEVEL

info by default.

DASHBOARD_ORIGIN

Where the dashboard is served. Cookie-authenticated requests must send a matching Origin or get origin_rejected.

API_PUBLIC_URL

Switches single sign-on on. Unset, SSO answers sso_unavailable.

INGEST_PUBLIC_URL

The endpoint published in DSNs.

SESSION_COOKIE_NAME

slk_session by default.

SESSION_TTL

720h by default.

SECURE_COOKIES

Set for HTTPS deployments.

SHUTDOWN_TIMEOUT

15s by default.

INGEST_REQUESTS_PER_MINUTE

600 by default, per project.

INGEST_EVENTS_PER_MINUTE

30000 by default, per organisation.

AUTH_ATTEMPTS_PER_MINUTE

10 by default.

INVESTIGATIONS_PER_HOUR

100 by default.

CLICKHOUSE_URL

Enables the ClickHouse event store. Its presence also switches reads to it.

READ_EVENTS_FROM_CLICKHOUSE

Derived from CLICKHOUSE_URL. Run the backfill before flipping it on a database with history.

SECRET_ENCRYPTION_KEY

Required by anything storing an encrypted secret, or it answers secrets_not_durable.

ARTIFACT_DIR / ARTIFACT_S3_*

Where source-map artifacts live. A service pointed at the wrong store fails quietly.

BACKUP_ENCRYPTION_KEY

Required by every backup command. A different value makes existing artifacts unreadable.

BACKUP_DIR / BACKUP_S3_* / BACKUP_WAL_SPOOL

Backup destination and write-ahead spool.

BACKUP_RETENTION_DAYS / BACKUP_MIN_ARTIFACTS

How much history to keep.

ANTHROPIC_API_KEY / ANTHROPIC_MODEL

AI investigations. Off entirely when unset.

GENIUSPAY_API_KEY / _API_SECRET / _WEBHOOK_SECRET

Buying a plan. The key is the switch: unset, neither checkout nor the webhook route is mounted.

GENIUSPAY_BASE_URL

Defaults to the merchant API base.

SMTP_HOST / _PORT / _USERNAME / _PASSWORD / _FROM

Email alert delivery.

OPERATOR_WEBHOOK_URL

Operator alerts about this deployment. Deliberately unset by default, so it sends nowhere.

ACCOUNT_ALERT_WEBHOOK_URL

Commercial alerts about customers. Falls back to OPERATOR_WEBHOOK_URL.

OTLP_ENDPOINT

Where this platform sends its own telemetry.

Commands

cmd/api

The dashboard API.

cmd/ingest

The telemetry ingest service. A separate process on purpose.

cmd/worker

Scheduled jobs — retention, purge, digests, alert evaluation.

cmd/alerts

Evaluate alerts once, by hand.

cmd/migrate

Apply migrations. Embedded in the binary, so a new .sql file does nothing until the image is rebuilt.

cmd/seed

Build the local fixture organisation and projects.

cmd/plan

Assign a plan to an organisation. An operator action, and audited.

cmd/retention

Apply retention now.

cmd/purge

Delete telemetry belonging to organisations that no longer exist.

cmd/erase

Erase one subject’s data on request.

cmd/refingerprint

Re-key issue grouping across history.

cmd/backfill

Copy existing events into ClickHouse before switching reads to it.

cmd/backup

Take an encrypted backup.

Migrations are embedded in the binary. A new .sql file does nothing until the migrate image is rebuilt, and the container still logs “migrations applied” either way. Check the schema version rather than the log line.

Security & privacy

• Scrubbing happens twice. The SDKs redact secret-shaped values before send, and the ingestion path scrubs again on arrival — keys, tokens, authorization headers, JWTs, cloud credentials, and key=value assignments in free text.
• Replay is masked before capture, in the browser, with rrweb’s defaults inverted.
• Tenants are isolated as a release gate, not as a convention. The cross-tenant suite is part of the check that must pass.
• Outbound requests are checked. Alert destinations are dialled through a guard that refuses private and link-local addresses, so a webhook cannot be pointed at the inside of the network.
• Plan changes are audited. Who granted what is the only history that assignment keeps.
• The marketing site stores nothing and calls nobody — no analytics, no CDN, no fonts fetched at runtime — which is why it carries no cookie banner. A test enforces it.

The sub-processor register and the retention ceilings are published separately and are part of the same commitment: see the security and privacy pages.

What this platform does not do

Listed rather than omitted. A developer who cannot find a feature assumes they missed it, and finds out the expensive way.

• It does not act on what a plan includes. Going past a plan figure never throttles you, never rejects telemetry, and never triggers a charge — there is no overage billing at all.
• It does not predict failure. It reports a metric climbing toward a line it already draws, with the slope and the traffic behind it, and says what would break the projection. There is no probability and no time-of-death.
• It does not suggest dependency upgrades. A stack frame names a package and never a version, so a suggestion would be a confident instruction about software it has never seen.
• It does not execute remediation. A suggestion is a sentence.
• There is no annual billing. The catalogue holds one monthly price and checkout sells months at it.
• There are no invoices yet. Nothing is issued to anyone.
• Metric-point ingestion is not plan-gated, unlike replay. A plan without a metric-point figure can still send them and have them metered.
• The dashboard is English only. The marketing, legal and documentation pages are in English and French; the product is not.