Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ Packages: `runtime-node`, `otlp-ingester`, Python adapter (`adapters/python`).
- Spans already stored keep these attributes until their TTL expires.
- Opt-in hashed client IP (`runtime-node`, Python adapter, `otlp-ingester`), to count distinct clients without storing addresses: `hashClientIp: true | { salt }`, `init_tracing(hash_client_ip=True, client_ip_salt=...)`, or `AUTTER_HASH_CLIENT_IP=true` with `AUTTER_CLIENT_IP_SALT` (SDKs and ingester). The client's address (`client.address`, then `http.client_ip`, then on server spans the socket peer, which behind a proxy is the proxy) is normalised and exported as `client.address_hash`: HMAC-SHA256 under the secret salt, 32 hex characters, identical in the Node SDK, the Python adapter and the ingester for the same salt (shared vectors in `test-vectors/redaction.json`, `clientIpHash`). The raw address is still dropped. Off by default; on without a salt of at least 16 characters it hashes nothing and warns once, never an unsalted hash. The ingester keeps a hash it receives and does not hash it again. A hashed IP is still pseudonymous personal data in some readings of privacy law: treat the salt as a secret.

### runtime-next: the root is safe in modules shared with client and edge code

- `@autter/runtime-next` has a browser build (`browser` condition) and an edge build (`edge-light` / `worker`) of its root entry. Before, every bundler got the server build, so a module that both a client component and a route handler import (an error catalog importing `defineRuntimeErrors`) pulled `@autter/runtime-node`, OpenTelemetry and `fs` into the client bundle and the build failed. The new builds export every name the server root does, with the same types: the coded-error helpers (`RuntimeError`, `defineRuntimeErrors`, `isRuntimeErrorLike`, `toClientError`, `errorAttributes`, `CODE_PATTERN`) and `redactAttributes` / `redactText` are the real ones; capture, log and context calls (`captureServerException`, `runtimeLogger`, `runtimeContext`, …) do nothing and warn once in development; setup functions and server wrappers (`registerAutter`, `withAutter`, `withRuntimeRequest`, `createAutterRelayRoute`, `withLlmCall`, …) throw a "server-only" error when called. Node.js resolves the root to the server build as before, for `import` and `require`. See the README ("Importing the root from shared modules").

## [1.18.0] - 2026-11-14

Packages: `otlp-ingester` 1.16.0, `runtime-node` 1.14.0, and the local `dashboard` image. Release the ingester before `runtime-node` 1.14.0 (`llm_cache_tokens`); see the upgrade notes.
Expand Down
2 changes: 2 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

61 changes: 55 additions & 6 deletions packages/runtime-next/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,11 @@ Set `AUTTER_RUNTIME_KEY` in your environment. Then three small files, and
The package has two entry points — this split is what keeps the Node
OpenTelemetry SDK out of your browser bundle:

- `@autter/runtime-next` (or `@autter/runtime-next/server`) — server only:
`instrumentation.ts`, route handlers, server components.
- `@autter/runtime-next` (or `@autter/runtime-next/server`) — the server
API: `instrumentation.ts`, route handlers, server components. The root
(not `/server`) is also safe in modules that client or edge code imports,
such as an error catalog: see
[Importing the root from shared modules](#importing-the-root-from-shared-modules).
- `@autter/runtime-next/client` — client components: browser tracker +
error boundary. Never imports Node code.
- `@autter/runtime-next/instrumentation` — `onRequestError` for
Expand Down Expand Up @@ -184,15 +187,61 @@ Also re-exported for convenience: `captureException`, `captureMessage`,
servers: `autterErrorHandler`, `autterFastifyErrors`, `autterKoa` and
`captureRequestError`.

> Importing the root entry from a client component pulls the Node OTel SDK
> into the browser bundle and fails the build (`fs` cannot be resolved).
> Client code must always use `@autter/runtime-next/client`.

LLM tracing is on automatically once `registerAutter` runs: Vercel AI SDK
calls with `experimental_telemetry: { isEnabled: true }` (and anything
wrapped in `withLlmCall` or an `instrumentLlmClient` client) are recorded at
100% — every call, with model, tokens, latency, and cost. See the
[`@autter/runtime-node` README](../runtime-node) for the API.

## Importing the root from shared modules

A module that both client and server code import, such as an error catalog,
can import the root. The bundler picks the root's build by export condition,
and the browser and edge builds export every name the server build does, with
the same types, so the import never fails with "export not found" and never
pulls the Node OpenTelemetry SDK (or `fs`) into a browser or edge bundle:

```ts
// lib/errors.ts — imported by a client component and by route handlers
import { defineRuntimeErrors } from "@autter/runtime-next";

export const orderErrors = defineRuntimeErrors("orders", {
not_found: { status: 404, message: "No such order", expected: true },
});
```

| Bundled for | Build | What the root gives you |
| --- | --- | --- |
| Node.js server (route handlers, server components, server actions, `instrumentation.ts`) | `import` / `require` | Everything. |
| Edge runtime (`middleware.ts`, `export const runtime = "edge"`; the `edge-light` / `worker` conditions) | `dist/index.edge.js` | The coded-error helpers for real (`@autter/runtime-edge`'s, the same classes `@autter/runtime-next/edge` uses). Every other name is a stand-in, as in the browser. |
| Browser (client components; the `browser` condition) | `dist/index.browser.js` | The coded-error helpers for real: `RuntimeError`, `defineRuntimeErrors`, `isRuntimeErrorLike`, `toClientError`, `errorAttributes`, `CODE_PATTERN`, plus `redactAttributes` and `redactText`. Every other name is a stand-in (below). |

The stand-ins in the browser and edge builds:

- Capture, log and context calls do nothing and warn once per name in
development (silent in production): `captureServerException`,
`captureServerMessage`, `reportServerOutcome`, `captureRequestError`,
`trackLlmCall`, `addBreadcrumb`, `makeSafeCapture()`, `runtimeLogger`,
`createRuntimeLogger()`, `runtimeContext`. Wrappers still run your code:
`withRuntimeOperation`, `withProcessSpan`, `runInBackground` and
`runtimeContext.fork` call the function and return its result;
`instrumentLlmClient` returns the client unchanged. `flushRuntimeLogs`
resolves `{ ok: true, errors: [] }`.
- Config builders return inert values, so a shared config module can build
them at import time: `otlpSink`, `consoleSink`, `fileSink`, and the
`enrich*` enrichers.
- Setup functions and server wrappers throw a "server-only" error naming the
function when they are called (never at import): `registerAutter`,
`withAutter`, `withRuntimeRequest`, `createAutterRelayRoute`,
`withLlmCall`, `emitLlmSelftestTrace`, `initAutterLogging`,
`installAutterAutoFlush`, and the Express, Fastify and Koa hooks.

So report browser errors with `captureException` from
`@autter/runtime-next/client` (a server capture called in the browser is not
forwarded to the browser tracker), and use `@autter/runtime-next/edge` for
middleware and edge routes. `@autter/runtime-next/server` has no browser or
edge build: import it from Node.js server code only.

## Operation logging (1.4.0+)

Import `withRuntimeOperation`, `runtimeLogger`, `createRuntimeLogger`,
Expand Down
16 changes: 15 additions & 1 deletion packages/runtime-next/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,18 @@
"exports": {
".": {
"types": "./dist/index.d.ts",
"edge-light": {
"import": "./dist/index.edge.js",
"require": "./dist/index.edge.cjs"
},
"worker": {
"import": "./dist/index.edge.js",
"require": "./dist/index.edge.cjs"
},
"browser": {
"import": "./dist/index.browser.js",
"require": "./dist/index.browser.cjs"
},
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
Expand Down Expand Up @@ -51,7 +63,7 @@
"directory": "packages/runtime-next"
},
"scripts": {
"build": "node ../../scripts/ensure-built.mjs runtime-node runtime-edge runtime-browser && node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
"build": "node ../../scripts/ensure-built.mjs runtime-core runtime-node runtime-edge runtime-browser && node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
"test": "npm run build -w @autter/runtime-core && npm run build -w @autter/runtime-node && npm run build -w @autter/runtime-edge && npm run build -w @autter/runtime-browser && npm run build && node --test test/*.test.mjs"
},
"dependencies": {
Expand All @@ -63,7 +75,9 @@
"react": ">=18"
},
"devDependencies": {
"@autter/runtime-core": "0.0.0",
"@types/react": "^18.3.0",
"esbuild": "^0.28.1",
"tsup": "^8.3.5",
"typescript": "^5.7.0"
},
Expand Down
92 changes: 92 additions & 0 deletions packages/runtime-next/src/index.browser.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
/**
* Browser build of the `@autter/runtime-next` root, picked by bundlers
* through the `browser` export condition (Next.js client components,
* Turbopack and webpack client builds, Vite).
*
* It exists for modules that both client and server code import, such as an
* error catalog:
*
* // lib/errors.ts, imported by a client component and a route handler
* import { defineRuntimeErrors } from "@autter/runtime-next";
* export const orderErrors = defineRuntimeErrors({ ... });
*
* It exports every name the server root exports, with the same types:
*
* - the coded-error and redaction helpers are the real ones (pure code from
* @autter/runtime-core, bundled in);
* - everything else is a stand-in from `server-stand-ins.ts`: capture and
* log calls are no-ops that warn once in development, setup functions
* (`registerAutter`, `withAutter`, …) throw a "server-only" error when
* called.
*
* Never imports @autter/runtime-node, OpenTelemetry or a Node module. The
* browser tracker and React components stay in `@autter/runtime-next/client`.
*/
import { serverStandIns } from "./server-stand-ins.js";

export {
CODE_PATTERN,
RuntimeError,
defineRuntimeErrors,
isRuntimeErrorLike,
toClientError,
errorAttributes,
redactAttributes,
redactText,
} from "@autter/runtime-core";

export const {
addBreadcrumb,
autterErrorHandler,
autterErrorResponse,
autterFastify,
autterFastifyErrors,
autterKoa,
autterRequests,
captureRequestError,
captureServerException,
captureServerMessage,
consoleSink,
createAutterRelayRoute,
createRuntimeLogger,
emitLlmSelftestTrace,
enrichDeployment,
enrichEdgeGeo,
enrichRequestSize,
enrichUserAgent,
fileSink,
flushRuntimeLogs,
initAutterLogging,
installAutterAutoFlush,
instrumentLlmClient,
makeSafeCapture,
otlpSink,
registerAutter,
reportServerOutcome,
runInBackground,
runtimeContext,
runtimeLogStats,
runtimeLogger,
trackLlmCall,
withAutter,
withLlmCall,
withProcessSpan,
withRuntimeOperation,
withRuntimeRequest,
} = serverStandIns("browser");

// The server root's types, so this build's declarations match it name for name.
export type * from "./server.js";

/*
* Compile-time parity with the server root (checked by the build's
* declaration step): the same value names, each assignable to its server
* type. test/root-builds.test.mjs checks the built files too.
*/
type Root = typeof import("./index.js");
type Self = typeof import("./index.browser.js");
type Assert<T extends true> = T;
type _BrowserRootParity = [
Assert<[keyof Root] extends [keyof Self] ? ([keyof Self] extends [keyof Root] ? true : false) : false>,
Assert<Self extends Pick<Root, keyof Self> ? true : false>,
];
77 changes: 77 additions & 0 deletions packages/runtime-next/src/index.edge.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
/**
* Edge build of the `@autter/runtime-next` root, picked by bundlers through
* the `edge-light` / `worker` export conditions (Next.js edge runtime:
* `middleware.ts`, `export const runtime = "edge"` routes; Workers), like
* `@autter/runtime-next/instrumentation` already is.
*
* Same contract as the browser build (`index.browser.ts`): every name the
* server root exports, with the same types. The coded-error helpers come
* from @autter/runtime-edge, so a `RuntimeError` built from a shared catalog
* is the very class `withAutter` from `@autter/runtime-next/edge` checks;
* the other server exports are stand-ins (no-ops that warn once in
* development, or a "server-only" error pointing to
* `@autter/runtime-next/edge`). Never imports @autter/runtime-node,
* OpenTelemetry or a Node module.
*/
import { serverStandIns } from "./server-stand-ins.js";

export {
CODE_PATTERN,
RuntimeError,
defineRuntimeErrors,
isRuntimeErrorLike,
toClientError,
} from "@autter/runtime-edge";
export { errorAttributes, redactAttributes, redactText } from "@autter/runtime-core";

export const {
addBreadcrumb,
autterErrorHandler,
autterErrorResponse,
autterFastify,
autterFastifyErrors,
autterKoa,
autterRequests,
captureRequestError,
captureServerException,
captureServerMessage,
consoleSink,
createAutterRelayRoute,
createRuntimeLogger,
emitLlmSelftestTrace,
enrichDeployment,
enrichEdgeGeo,
enrichRequestSize,
enrichUserAgent,
fileSink,
flushRuntimeLogs,
initAutterLogging,
installAutterAutoFlush,
instrumentLlmClient,
makeSafeCapture,
otlpSink,
registerAutter,
reportServerOutcome,
runInBackground,
runtimeContext,
runtimeLogStats,
runtimeLogger,
trackLlmCall,
withAutter,
withLlmCall,
withProcessSpan,
withRuntimeOperation,
withRuntimeRequest,
} = serverStandIns("edge");

// The server root's types, so this build's declarations match it name for name.
export type * from "./server.js";

/* Compile-time parity with the server root; see index.browser.ts. */
type Root = typeof import("./index.js");
type Self = typeof import("./index.edge.js");
type Assert<T extends true> = T;
type _EdgeRootParity = [
Assert<[keyof Root] extends [keyof Self] ? ([keyof Self] extends [keyof Root] ? true : false) : false>,
Assert<Self extends Pick<Root, keyof Self> ? true : false>,
];
12 changes: 8 additions & 4 deletions packages/runtime-next/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
/**
* @autter/runtime-next — one-command Autter Runtime for Next.js.
*
* The root entry is SERVER-ONLY (`instrumentation.ts`, route handlers).
* Client components must import from `@autter/runtime-next/client` —
* importing the root from client code would pull the Node OpenTelemetry
* SDK into the browser bundle and break the build.
* This is the root's Node.js build: the server API (`instrumentation.ts`,
* route handlers, server components). Bundlers pick `index.browser.ts` for
* the `browser` condition and `index.edge.ts` for `edge-light` / `worker`:
* the same names, with the coded-error helpers for real and stand-ins for
* the server-only functions, so a module shared with client or edge code
* can import the root without pulling the Node OpenTelemetry SDK in.
* Browser reporting and the error boundary live in
* `@autter/runtime-next/client`.
*/

export * from "./server.js";
Loading
Loading