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. POST /v1/auth/register, then log in — registration deliberately returns no session. Create a project from the dashboard or POST /v1/projects.
2. Issue a DSN. POST /v1/projects/{projectID}/dsns. 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 under /v1/issues and on the dashboard.

Go

import "github.com/rellinxe/snagspy/sdk/go/snagspy"

client, err := snagspy.New(snagspy.Options{
    DSN:         os.Getenv("SNAGSPY_DSN"),
    Environment: "production",
    Release:     buildSHA,
})
if err != nil {
    log.Fatal(err)
}
defer client.Close(context.Background())

if err := doWork(); err != nil {
    client.CaptureException(context.Background(), err)
}

JavaScript & the browser

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

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

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 root-cause analysis. Charged per model call, 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). Every route here authenticates with a DSN, not a session.

Two buckets apply to every upload: a per-project request limit and a per-organisation event limit. Both are described under Rate limits.

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.

Uploading a chunk

POST /v1/replay
Content-Type: application/octet-stream
X-Replay-Session:     <session id>
X-Replay-Seq:         <0, 1, 2, …>
X-Replay-Encoding:    json-zstd
X-Replay-Recorded-At: <RFC 3339, optional>

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 turned on with PUT /v1/projects/{projectID}/session-replay.
• 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

Upload artifacts to POST /v1/projects/{projectID}/artifacts. 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.

Dashboard API

Served by the API process on :8080 by default. Everything is under /v1. Responses are JSON; errors carry a stable code, a human-readable message and a request_id.

Authentication

Cookie-authenticated requests are Origin-checked. A request without an Origin matching DASHBOARD_ORIGIN is refused with origin_rejected (403). Scripting with curl against a local stack therefore needs -H "Origin: http://localhost:3000".

Rate limits

Rate limits are abuse control, and they are the one thing here that really does refuse a request. They have nothing to do with what your plan includes: going past a plan figure never throttles you and never rejects telemetry. Redis is authoritative so every instance shares a bucket, with a per-process fallback that keeps limiting alive if Redis is unavailable.

A refused request answers 429 with Retry-After.

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.

This table is generated from the same constant the platform bills against, so it cannot advertise a figure the product does not use.

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 PATCH /v1/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 at /v1/alert-destinations. A destination’s kind chooses the notifier, and a kind with no notifier behind it fails loudly rather than being skipped.

Deployments

Record deploys with POST /v1/deployments, or connect GitHub or GitLab at /v1/projects/{projectID}/integrations. 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 at /v1/reports/schedule. Preview the next one without sending it at /v1/reports/preview.

Cron monitoring & uptime

Create a check, then have your job call its check-in URL. The token in the URL is the credential, so the endpoint 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 https://ingest.example.com/v1/checkins/<token>

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 the result at /v1/uptime/monitors/{monitorID}/checks.

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 ANTHROPIC_API_KEY is set — 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.
• 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.

Commands

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.