Skip to content

About

Open-source lightweight runtime telemetry: tiny browser error tracking, server OpenTelemetry, one OTLP ingester

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Autter Runtime

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"]
Loading

Existing external logs

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.

Install

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/skills

See Autter-dev/autter-skills.

Server 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 automatically

Vercel 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.

Packages

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).

Supported stacks

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.

Keys: frontend vs backend

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.

Local dashboard

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:4319

Events 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:latest

Or build from source with cd dashboard && cargo run --release. See the dashboard README for configuration.

Docs

Contributing

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.

Hosting the ingester

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:latest

Or 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:4319

No 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 step

verify'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"

Design principles

  • 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.

License

MIT

Investigating your system

Use Dashboard Ask or autter ask, autter logs, and autter threads to investigate captured Runtime signals and resume saved debugging sessions. See system investigations.

About

Open-source lightweight runtime telemetry: tiny browser error tracking, server OpenTelemetry, one OTLP ingester

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages