Open-source, lightweight runtime telemetry for web apps — tiny error tracking in the browser, standard OpenTelemetry on the server, one normalised signal model, analysed per repository.
Autter Runtime deliberately does not ship the full OpenTelemetry browser SDK to your users. The browser gets a dependency-free, <10 KB error tracker; your server keeps real OTel; and this repo's OTLP ingester receives both and writes them to ClickHouse in a compact, per-repo data model.
flowchart TD
A["@autter/runtime-browser (tiny tracker)"] --> B["Same-origin relay (@autter/runtime-node)"]
B --> D["otlp-ingester /v1/browser (JSON)"]
C["Server OpenTelemetry + request summaries"] --> E["otlp-ingester /v1/traces + /v1/metrics + /v1/logs (OTLP)"]
I["@autter/runtime-edge (Workers, Vercel Edge, Deno, Bun)"] --> E
D --> F["Normaliser + fingerprinter"]
E --> F
F --> G["ClickHouse (occurrences, spans, logs, usage rollups)"]
F --> H["Optional sink webhook → issue grouping"]
Connect Sentry, PostHog, Grafana/Loki, Datadog or webhooks in the Autter platform's repository Runtime settings. Independent platform workers store provider records and run eligible RCA/draft fixes. This path does not require installing these SDKs or changing the OTLP ingester. See External sources for setup and the distinction from SDK telemetry.
npm install @autter/runtime-browser # frontend (React, Vue, any SPA, static sites)
npm install @autter/runtime-node # backend (Express, Fastify, Koa, Nest, plain Node)
npm install @autter/runtime-next # Next.js (both halves in one package)
npm install @autter/runtime-edge # Cloudflare Workers, Vercel Edge, Deno, Bun (zero deps)| Package | Version | Use it for |
|---|---|---|
@autter/runtime-browser |
1.8.2 | Browser errors + usage, coded-error duck typing, request-id capture |
@autter/runtime-node |
1.16.1 | Node servers: OTel tracing, request summaries, coded errors, operations |
@autter/runtime-next |
1.11.1 | Next.js: server + client + /edge for middleware.ts |
@autter/runtime-edge |
1.4.3 | Fetch-only runtimes: request summaries and coded errors over /v1/logs |
@autter/otlp-ingester |
1.18.1 | Self-hosted ingest — upgrade it before the SDKs |
@autter/runtime-cli |
1.4.1 | Build time: debug ids + source map upload (CLI, Vite/Rollup, webpack, Next.js) |
Minimum versions per feature, SDK and ingester are in one table:
Version compatibility. Once
AUTTER_ENDPOINT and AUTTER_RUNTIME_KEY are set, check the whole path
before writing any code: npx @autter/runtime-node verify
(Is my data arriving?).
Prefer to have an AI agent set it up for you? Install the companion agent skills — they inventory your repo and wire up Autter Runtime for whatever language/framework each service uses, npm packages or not:
npx @autter/skillsServer memory pressure detection works through the same OTLP/HTTP metric endpoint for any language. The Node package exports process metrics for you; Python, Go, Rust, JVM, .NET, and other services use their OTel meter provider or a process collector to emit the portable memory metrics. An OOM kill must be forwarded by ECS or Kubernetes because the killed process cannot report it afterward.
Frontend — errors + usage, automatic from init:
import { initAutterBrowser, captureException, trackEvent } from "@autter/runtime-browser";
initAutterBrowser({
endpoint: "/api/autter-runtime", // your relay route (recommended), or
// endpoint: "https://otlp.autter.dev/v1/browser", clientKey: "autter_rtc_…",
service: "web-app",
release: import.meta.env.VITE_GIT_SHA,
});
captureException(err, { operation: "start-checkout" });
trackEvent("clicked_upgrade");Backend — one preloaded file, created in your own app next to its entry point, requests traced automatically:
// instrument.cjs — run with: node --require ./instrument.cjs server.js
const { initAutterServer } = require("@autter/runtime-node");
initAutterServer({
apiKey: process.env.AUTTER_RUNTIME_KEY, // secret server key
service: "payments-api",
release: process.env.GIT_SHA,
});Requests and coded errors (1.5.0) — one summary per request, always kept, with a request id echoed to the client; one issue per error code:
const { autterRequests, autterErrorResponse, defineRuntimeErrors, runtimeContext } =
require("@autter/runtime-node");
const billing = defineRuntimeErrors("billing", {
declined: { status: 402, message: "Payment declined", expected: true, fix: "Try another card" },
});
app.use(autterRequests({ ignore: ["/healthz"] }));
app.post("/checkout", (req, res, next) => {
runtimeContext.set({ cart: { items: 3 } });
next(billing.declined()); // → 402 { error: { message, code, fix, requestId } }
});
app.use(autterErrorResponse());See Requests, coded errors and background work.
LLM calls — initialised with the server tracker, recorded at 100% (model, tokens, latency, USD cost). One line per client:
const { instrumentLlmClient } = require("@autter/runtime-node");
const openai = instrumentLlmClient(new OpenAI()); // that's it — every
// chat/embedding/stream call through this client is traced automaticallyVercel AI SDK users don't even need that — set
experimental_telemetry: { isEnabled: true } on the call. For raw-fetch
clients there's a manual withLlmCall wrapper (see
@autter/runtime-node).
Full walkthrough (keys, relay setup, Next.js, verification): docs/GETTING-STARTED.md.
| Package | Status | Description |
|---|---|---|
@autter/runtime-browser |
v1.6 | Zero-dependency browser error + usage tracker (<10 KB gzipped) |
@autter/runtime-node |
v1.6 | Curated OTel server tracker, request summaries, coded errors, operation logging, same-origin relay |
@autter/runtime-next |
v1.6 | One-command Next.js integration (server, client, relay route, error boundary, edge middleware) |
@autter/runtime-edge |
v1.1 | Zero-dependency edge SDK: request summaries and coded errors for Workers, Vercel Edge, Deno, Bun |
@autter/otlp-ingester |
v1.6 | Self-hostable ingest service: OTLP/HTTP (protobuf + JSON) traces, metrics, logs, browser payloads → ClickHouse |
dashboard |
v0.1 | Local development UI: browse what your local ingester stored (single Rust binary, read-only) |
@autter/runtime-cli |
v1.0 | Readable stack traces: autter-runtime sourcemaps inject/upload, Vite/Rollup, webpack and Next.js plugins (guide) |
packages/runtime-core is private: shared code bundled into runtime-node and
runtime-edge at build time, never published.
Runnable demo: examples/express-app — browser
tracker → relay → ingester, OTel server tracker, request summaries and coded
errors. docker compose up here, then npm start in the example: it sends
to the local ingester with the local key, no setup. Edge:
examples/edge-worker (Cloudflare Worker).
For endpoint latency detection and slow-request retention, see endpoint regression telemetry.
| Stack | How | Key type |
|---|---|---|
| React / any SPA / static site | @autter/runtime-browser (direct) |
client key (publishable) |
| React/SPA with a backend | @autter/runtime-browser → relay |
none in browser; server key in relay |
| Next.js | @autter/runtime-next |
server key |
| Node (Express, Fastify, Koa, Nest) | @autter/runtime-node |
server key |
| Cloudflare Workers, Vercel Edge, Deno, Bun | @autter/runtime-edge |
server key (secret binding) |
| Python (Django, FastAPI, Flask, Celery) | OTel SDK + framework instrumentation + autter_tracing.py (errors of unsampled traces kept) → OTLP/HTTP |
server key |
| Go, Rust, Java, .NET, … | any OTel SDK → OTLP/HTTP (protobuf or JSON) | server key |
Per-stack setup snippets: docs/INTEGRATIONS.md.
Two credential types keep the frontend and backend cleanly separated:
Server key (autter_rt_…) |
Client key (autter_rtc_…) |
|
|---|---|---|
| Secrecy | secret — backend env vars only | publishable — safe in frontend bundles |
| Can send | OTLP traces/metrics/logs + browser events | browser events only |
| Protection | rate limits | origin allow-list + tighter rate limits, write-only |
When your app has a backend, prefer the relay: the browser posts to your own server, which forwards with the server key — no key in the browser at all, and ad-blockers can't tell it apart from your own API traffic.
When you're building with Autter Runtime locally, the dashboard lets you see what the ingester stored without writing ClickHouse queries. It covers telemetry, errors, events and logs, traces and LLM usage. It's a development tool only. It isn't part of the hosted Autter cloud, and the self-hosted deploy files don't include it.
docker compose up # ClickHouse + ingester (:4318) + dashboard
open http://localhost:4319Events sent with the local key autter_rt_local_dev_only show up under the
local repository. Already running ClickHouse and the ingester some other way?
Start just the dashboard from the published image:
docker run --rm -p 127.0.0.1:4319:4319 \
-e CLICKHOUSE_URL=http://host.docker.internal:8123 -e CLICKHOUSE_PASSWORD=dev \
ghcr.io/autter-dev/runtime-dashboard:latestOr build from source with cd dashboard && cargo run --release. See the
dashboard README for configuration.
- Getting started — zero to data flowing
- Stack integrations — React, Node, Next.js, Python, Go, Rust, generic OTel
- Using Autter Runtime without npm — any OTel SDK, an OTel Collector, or plain HTTP from any language
- Architecture & data model
- Local dashboard — browse local telemetry, errors, events, traces and LLM usage
- Operation logging and diagnostic context
- Requests, coded errors and background work
- Continuous detection, profiles, and outcomes
- Version compatibility: the one compatibility table, the built-in SDK/ingester/schema check and
npx @autter/runtime-node doctor - Is my data arriving?:
verify, what is sampled, arrival times, and what each refusal means - Roadmap · Releasing
Contributions of every size are welcome — bug reports, docs fixes, new language integrations, features. We'd be more than glad to have you: see CONTRIBUTING.md for the dev setup, ground rules, and good first areas to pick up.
Upgrade the ingester before the SDKs. New features need its routes and
ClickHouse migrations. The SDK warns once at runtime when they don't match,
and npx @autter/runtime-node doctor --endpoint <ingester URL> prints a full
report. See Version compatibility.
Autter cloud hosts it at otlp.autter.dev (the SDKs' default
endpoint). Deployment runbook + scripts for the AWS/ECS setup:
deploy/aws.
Self-hosting on your own server — one small EC2/Lightsail box running
the ingester + ClickHouse together via Docker Compose, with Caddy handling
HTTPS automatically. No VPC/ECS setup required:
deploy/single-server.
Self-hosting, bring-your-own-infra — prebuilt multi-arch image, no clone needed:
docker run -p 4318:4318 \
-e CLICKHOUSE_URL=… -e CLICKHOUSE_PASSWORD=… \
-e AUTTER_INGEST_KEYS='[{"key":"…","orgId":"o","repositoryId":"r"}]' \
ghcr.io/autter-dev/otlp-ingester:latestOr for local development with a bundled ClickHouse, from a clone of this repo:
docker compose up # local ClickHouse + ingester on http://localhost:4318
# + local dashboard on http://localhost:4319No key step: the dev compose file accepts the built-in local key
autter_rt_local_dev_only from your machine (only there, and never on a
deployed ingester; see Getting started).
Point your app at it and check the connection:
export AUTTER_ENDPOINT=http://localhost:4318
export AUTTER_RUNTIME_KEY=autter_rt_local_dev_only
npx @autter/runtime-node doctor # versions, storage and the key; sends nothing
npx @autter/runtime-node verify # sends a test event, reads it back, names the first failing stepverify's test event never opens an issue. When events don't show up, run
it first; Is my data arriving? covers sampling, arrival
times and every failure it names.
Or with any OpenTelemetry exporter:
new OTLPTraceExporter({
url: "http://localhost:4318/v1/traces",
headers: { authorization: `Bearer ${process.env.AUTTER_RUNTIME_KEY}` },
});Then trigger an error and see it stored:
docker compose exec clickhouse clickhouse-client --password dev --query \
"SELECT service, error_type, message FROM autter_runtime.runtime_error_occurrences ORDER BY occurred_at DESC LIMIT 5"- Errors are 100%, everything else is sampled or aggregated. Raw error
occurrences are always kept (14-day TTL); traces containing an error are
retained in full (the Node SDK tail-retains them), so every issue keeps the
trace that explains it; healthy traces are expected to be sampled upstream
(0.5–1%); usage is stored as 1-minute rollups (90 days). Request and
operation summaries are one bounded record per unit of work and are always
kept (
LOG_TTL_DAYS, default 14). - Per-repo analysis. Every row is keyed by
org_id+repository_id. - Privacy by construction. No cookies, no DOM, no request/response bodies, no emails, no full URLs with query strings.
- OTLP-compatible at the ingestion layer, not inside a 3 KB browser script.
MIT
Use Dashboard Ask or autter ask, autter logs, and autter threads to investigate captured Runtime signals and resume saved debugging sessions. See system investigations.