@autter/runtime-node 1.3.4 → 1.5.0

package/README.md

@@ -1,3 +1,53 @@
+# Operation logging
+
+Use `withRuntimeOperation`, `runtimeLogger`, and `createRuntimeLogger` to attach
+application context to logs and completed operations. See the full
+[operation logging guide](../../docs/OPERATION-LOGGING.md) for initialization,
+steps, outcomes, redaction, export lifecycle, and release requirements.
+
+# Requests and coded errors (1.5.0)
+
+Requires ingester 1.5.0. One summary per request (always kept), request ids
+echoed to clients, one issue per error code:
+
+```ts
+import {
+  autterRequests, autterErrorResponse, defineRuntimeErrors, runtimeContext,
+} from "@autter/runtime-node";
+
+export const billingErrors = defineRuntimeErrors("billing", {
+  declined: { status: 402, message: "Payment declined", expected: true,
+              why: "The card issuer rejected the charge", fix: "Ask for another card" },
+  limit: ({ plan }: { plan: string }) => ({ status: 429, message: `Plan ${plan} limit reached` }),
+});
+
+app.use(autterRequests({ ignore: ["/healthz", "/metrics"] }));
+app.post("/checkout", async (req, res) => {
+  runtimeContext.set({ cart: { items: req.body.items.length } });
+  runtimeContext.info("Applied coupon", { coupon: "SPRING" });   // folded into the summary
+  if (overLimit) throw billingErrors.limit({ plan: "free" });     // Express 5 (next(err) on 4)
+  res.json({ ok: true, requestId: runtimeContext.requestId });
+});
+app.use(autterErrorResponse());   // { error: { message, code, why?, fix?, link?, requestId } }
+```
+
+Also: `autterFastify`, `withRuntimeRequest` (fetch-style handlers),
+`runtimeContext.fork` / `runInBackground` / `carrier()` for background work and
+queues, the per-operation AI usage rollup, `waitUntil`, `initAutterLogging`
+(no NodeSDK — for apps with their own OTel), enrichers (`enrichUserAgent`,
+`enrichRequestSize`, `enrichEdgeGeo`, `enrichDeployment`), sinks (`otlpSink`,
+`consoleSink`, `fileSink` → `.autter/runtime/*.jsonl` in development) and test
+helpers:
+
+```ts
+import { captureRuntime, expectOperation } from "@autter/runtime-node/testing";
+const runtime = captureRuntime();
+// … exercise the app …
+expectOperation(runtime, "POST /checkout").toHaveOutcome("degraded").toHaveErrorCode("billing.declined");
+```
+
+Full guide: [Requests, coded errors and background work](../../docs/REQUESTS-AND-ERRORS.md).
+
 # @autter/runtime-node
 
 The server tracker exports per-instance RSS, heap, memory limit, and GC
@@ -117,6 +167,35 @@ import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 initAutterServer({ ..., instrumentations: [new ExpressInstrumentation()] });
 ```
 
+### Version compatibility: checked for you
+
+Some features need a minimum ingester version: operation logging needs
+1.4.0, memory metrics 1.3.3, endpoint latency 1.3.1. After
+`initAutterServer`, the SDK checks the ingester once in the background
+(`GET /v1/compat`, unref'd, 3 s timeout). For each feature in use that the
+ingester can't store, it prints one warning:
+
+```text
+[autter-runtime] Operation logging needs ingester >= 1.4.0; yours is 1.3.4. Upgrade the ingester: docker pull ghcr.io/autter-dev/otlp-ingester:latest and restart it (ClickHouse migrations run at boot). See …/docs/COMPATIBILITY.md
+```
+
+The check never throws, never delays startup or exit, and is silent when
+versions match or are unknown. `debug: true` logs the result. Turn it off
+with `compatCheck: false` or `AUTTER_COMPAT_CHECK=0`. The browser relay does
+the same for browser features such as CSP violation capture. The SDK reports
+itself through the OTLP resource attributes `telemetry.distro.name` and
+`telemetry.distro.version`, so the Autter dashboard shows the SDK version
+each service runs.
+
+For a full report (for example in CI or after a deploy):
+
+```bash
+npx @autter/runtime-node doctor --endpoint https://ingest.example.com [--key "$AUTTER_RUNTIME_KEY"] [--json]
+```
+
+Exit codes: 0 compatible, 1 mismatch or rejected key, 2 ingester unreachable.
+See [docs/COMPATIBILITY.md](../../docs/COMPATIBILITY.md).
+
 ### Lifecycle: never lose telemetry to a forgotten shutdown()
 
 Telemetry is batched (errors every ~2 s, healthy traces every ~5 s, metrics
@@ -148,23 +227,39 @@ default 1% sampling the span contribution is negligible; if you set
 Tail-retained error traces don't distort this: their spans carry
 `autter.tail_retained` and the ingester keeps them out of span-fed rollups.
 
-### Privacy: custom attributes are redacted before they leave the process
-
-The browser relay whitelist-sanitises everything a client posts — but the
-server tracker accepts free-form attributes from *your* code, where a stray
-`captureException(err, { "user.email": … })` would otherwise go out
-verbatim. Custom attributes are therefore scrubbed at capture time by
-default:
-
-- values that look like emails, JWTs, `sk-…`/`ghp_…`/AWS/Slack tokens,
-  `Bearer …` headers, or `scheme://user:pass@host` URLs are masked;
+### Privacy: secrets and PII are scrubbed before they leave the process
+
+Error context is where secrets leak: `connect ECONNREFUSED
+postgres://admin:hunter2@db…` in an exception message, a provider error
+echoing an API key, a `?token=` in a request URL, a stray
+`captureException(err, { "user.email": … })`. Everything the SDK exports is
+therefore scrubbed by default — custom attributes, exception messages and
+stack traces, span status messages, LLM call attributes and errors,
+structured logs, and the browser events the relay forwards. A final pass at
+export time scrubs every span regardless of who created it (HTTP
+instrumentation URLs, third-party instrumentations, `recordException` in
+your own code).
+
+- secrets inside any string are masked in place, keeping the rest of the
+  message/stack readable: JWTs, `Bearer`/`Basic` credentials,
+  `Authorization:`/`Cookie:`/`Set-Cookie:` header text,
+  `scheme://user:pass@host` connection strings (postgres, mysql,
+  mongodb+srv, redis, …), vendor keys (`sk-…`, `sk_live_…`, `ghp_…`,
+  `github_pat_…`, `xox?-…`, `AIza…`, `AKIA…`, …), PEM private keys,
+  `password=`/`?token=`/`?api_key=`-style assignments, emails, and
+  Luhn-valid card numbers;
 - attributes whose **key** looks sensitive (`password`, `token`, `secret`,
-  `api_key`, `authorization`, `cookie`, `ssn`, `card_number`, …) are masked
-  wholesale;
-- non-sensitive keys and primitives pass through untouched, so grouping and
-  dashboards keep working.
+  `api_key`, `authorization`, `cookie`, `session`, `ssn`, `card_number`, …)
+  are masked wholesale, at any nesting depth;
+- non-sensitive keys, numbers (including LLM token counts) and booleans pass
+  through untouched, so grouping, dashboards and cost tracking keep working.
+
+The same patterns run in the browser SDK, the relay, the Python adapter,
+and again in the ingester before storage (shared test vectors in
+`test-vectors/redaction.json`).
 
-Disable or extend it per service:
+Extend it (applies to messages, stacks and URLs too) or disable it per
+service:
 
 ```ts
 initAutterServer({
@@ -186,7 +281,9 @@ const safe = makeSafeCapture();
 safe.captureException(err, { "user.email": email }); // masked before export
 ```
 
-The raw primitive is exported too (`redactAttributes(attrs, options)`).
+The raw primitives are exported too (`redactAttributes(attrs, options)`,
+`redactText(text, options)`). The browser relay takes the same options as
+`createBrowserRelayHandler({ ..., redact })`.
 This closes the server-side gap to match the browser relay's payload
 whitelist; it is best-effort scrubbing of obvious PII shapes, not a DLP
 engine — keep secrets out of attributes in the first place.
@@ -287,4 +384,4 @@ Note on the slow-process monitor: Autter flags HTTP routes from the
 unsampled request metrics, so route detection works out of the box. Non-HTTP
 work is only visible where a span exists — relying on 1%-sampled regular
 traces there would undercount ~100×, which is why these spans skip head
-sampling.
+sampling.