Quickstart

Autter Runtime captures errors and usage from your frontend and backend. Compatible server releases also capture structured logs and operation outcomes. This guide sets up capture and checks stored data; follow Operation logging for the new logging APIs and required deployments.

Prefer to have an AI coding agent set this up for you? See AI agent skills — npx skills add Autter-dev/autter-skills --all, then tell your agent “install Autter Runtime in this project.”

Concepts

Two kinds of keys — never mix them up:

	Server key	Client key
Looks like	`autter_rt_…`	`autter_rtc_…`
Secrecy	secret — env vars only, never in a browser bundle	publishable — safe to ship in frontend JS
Can send	OTLP traces + metrics + logs, browser events	browser events only (`/v1/browser`)
Extra protection	—	per-key origin allow-list, tighter rate limit

Two ways to send browser events:

Relay (recommended, including static sites) — the browser posts to a same-origin route on your server, Worker, or edge function, which forwards with your server key. Allow the relay in connect-src (usually 'self') and check the actual browser request. See Stack integrations for the serverless relay.
Direct (lossy fallback for pure-static only) — the browser posts straight to the ingester with a publishable client key. Ad-blockers silently drop these cross-origin requests.

What is never sent: cookies, DOM content, form values, request/response bodies, headers, emails, full URLs with query strings. Use a Runtime ingest key, not an Autter CLI/PAT or MCP token. Keep the key value in your environment; your coding agent only needs its variable name. Custom log context is application-authored: do not include sensitive data, even though the SDK and ingester redact it.

Run the ingester

For a local try-out, clone the repo and start ClickHouse plus the ingester with Docker Compose:

git clone https://github.com/Autter-dev/autter-runtime
cd autter-runtime
docker compose up   # ClickHouse + ingester on http://localhost:4318

There’s no key step. The local Compose setup accepts the built-in key autter_rt_local_dev_only, but only from your own machine. A deployed ingester never accepts it. 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 and reads it back

verify goes through key, network, ingester, storage, auth, ingest, stored, trace, release and logs, and stops at the first step that fails with what to do. Its test event never opens an issue. Run it first whenever events don’t show up. See Is my data arriving?.For real deployments, see Self-hosting or use Autter’s hosted ingester at otlp.autter.dev: set AUTTER_ENDPOINT=https://otlp.autter.dev and your repository’s server key, then run the same two commands.

Instrument your backend

npm install @autter/runtime-node

Create instrument.cjs — it must load before your app:

const { initAutterServer } = require("@autter/runtime-node");

initAutterServer({
  apiKey: process.env.AUTTER_RUNTIME_KEY,   // server key
  endpoint: process.env.AUTTER_ENDPOINT,     // your ingester URL
  service: "payments-api",
  environment: process.env.NODE_ENV,
  release: process.env.GIT_SHA,              // enables "broke in release X"
  retainTracesAboveMs: 2000,
});

node --require ./instrument.cjs server.js

Reuse your existing SDK initialization if you already have one. The example opts into bounded, local slow-request trace retention. Set GIT_SHA to the deployed commit SHA. See Endpoint regressions for metric requirements and retention limits.This records HTTP request metrics and captures crashes and unhandled promise rejections. A rejection from a promise started during a request keeps that request’s route and request id.On Express, add request ids and the error hook to your app:

const { autterRequests, autterErrorHandler } = require("@autter/runtime-node");

app.use(autterRequests());       // first: request ids and one summary per request
// ... your routes and routers ...
app.use(autterErrorHandler());   // after your routes, before your own error handlers

With @autter/runtime-node 1.10.0 or later, the error behind every Express 5xx is recorded with its type, message, stack, route and request id even without autterErrorHandler(). That holds in every router, including routers with their own error handler. The handler adds coded errors that end in a 4xx, and it never reports an error twice, so one app.use(autterErrorHandler()) at app level is enough. On older versions it is required: without it a thrown error shows up only as GET /route returned 500, with no stack. Fastify and Koa need their hooks (autterFastifyErrors, autterKoa); see Integrations.For handled errors:

const { captureException } = require("@autter/runtime-node");

try {
  await chargeCard(order);
} catch (err) {
  captureException(err, { "order.id": order.id });
  throw err;
}

A run that returns normally but did not do its job (a declined payment) is not an exception. Declare it so it becomes an issue:

const { reportOutcome } = require("@autter/runtime-node");

if (!payment.confirmed) reportOutcome("checkout", "payment was not confirmed");

Test it without an ingester: @autter/runtime-node/testing keeps every record in memory.

const { captureRuntime, expectOperation } = require("@autter/runtime-node/testing");

const runtime = captureRuntime();
await request(app).post("/checkout").expect(402);
expectOperation(runtime, "POST /checkout").toHaveOutcome("degraded");
runtime.stop();

Then check the real path: npx @autter/runtime-node verify --service payments-api. If your app has no key, or the ingester refuses it, the SDK prints one line saying so at startup or on the first refusal.

Add server operation diagnostics

Node/Next.js SDK and ingester 1.4.0+ are required (compatibility table). npx @autter/runtime-node doctor shows whether operation logging is active for your installed SDK and ingester, and verify checks that a log record is stored.Once supported, add logging options to the existing initialization and wrap meaningful checkout/job boundaries with withRuntimeOperation. Record measured steps, bounded nested context, and explicit business outcomes. Use runtimeLogger.info/warn/error for diagnostics, while keeping exception or declared failed-outcome capture for issues.Follow the checkout example. A callback that returns normally defaults to success, so declare a failed payment result explicitly. Preserve existing loggers and await flushing at the end of short-lived jobs. If support is pending, continue basic capture and report that gap.

Instrument your frontend

npm install @autter/runtime-browser

Add a relay route to your backend (the key stays server-side):

// Express
const { createBrowserRelayHandler } = require("@autter/runtime-node");
app.post("/api/autter-runtime",
  createBrowserRelayHandler({ apiKey: process.env.AUTTER_RUNTIME_KEY,
                              endpoint: process.env.AUTTER_ENDPOINT }));

Then initialize the tracker in your frontend entry point:

import { initAutterBrowser, captureException, trackEvent } from "@autter/runtime-browser";

initAutterBrowser({
  endpoint: "/api/autter-runtime",   // same-origin — no key here
  service: "web-app",
  release: import.meta.env.VITE_GIT_SHA,
});

captureException(err, { operation: "start-checkout" }); // handled errors
trackEvent("clicked_upgrade");                          // usage counters

No backend? See the direct setup and full walkthrough in Installation.

See your own events

verify proves the path; it is safe in production because its test event never opens an issue or counts as a request. To see your app’s own events locally, trigger an error, wait a few seconds (server errors arrive within 2 s, request counts within 60 s; see arrival times), then query ClickHouse. In production, inspect existing traffic instead:

SELECT service, error_type, message, route, occurred_at
FROM autter_runtime.runtime_error_occurrences
ORDER BY occurred_at DESC LIMIT 10;

SELECT service, route, sum(request_count) AS requests, sum(error_count) AS errors
FROM autter_runtime.runtime_metrics_1m
WHERE bucket_at > now() - INTERVAL 1 HOUR
GROUP BY service, route;

With the local Compose setup: docker compose exec clickhouse clickhouse-client --password dev.When operation logging is enabled, verify it separately:

SELECT service, operation, outcome, message, trace_id, operation_id, attributes
FROM autter_runtime.runtime_logs
ORDER BY occurred_at DESC LIMIT 10;

These queries are for your local development database. In the platform, open the intended repository’s Runtime → Logs, inspect the captured IDs, and confirm the failed issue’s Operation evidence. Logs and traces may arrive separately; refresh or rerun analysis for later evidence. An unavailable source differs from an available source with no matching rows. See logging verification.

Production checklist

Server keys only in backend env vars; client keys only where a relay is genuinely impossible.
Client keys have allowedOrigins set to your exact app origins.
release is wired to your git SHA in both frontend and backend — it powers regression detection (“broke in release X”).
Keep trace sampling at ~1% (traceSampleRate) — errors are always captured regardless (what is sampled).
npx @autter/runtime-node verify passes from where the app runs (CI or the deployed host), with the production endpoint and key.
Confirm the logging SDK release and ingester/platform deployment separately; redeploy the application after upgrading.
Declare business outcomes, preserve existing loggers, and check buffered/dropped records and flush failures. Logs are best-effort diagnostics.
Check export volume after enabling retainTracesAboveMs. The platform rollout does not enable this option in existing applications.
The relay route keeps its built-in per-IP rate limit, or your WAF covers it (perIpRateLimit: false).
Direct browser ingest: your CSP includes connect-src https://your-ingester…, and you accept that ad-blockers may drop some events (the relay avoids this).
The ingester’s /healthz is wired to your load balancer health check.

Installation

Install the right package for your stack, including Next.js.

Stack integrations

Per-stack setup for React, Node, Next.js, Go, Rust, and any OpenTelemetry SDK.

Get started

Guides

Reference

Concepts

Production checklist

Installation

Stack integrations