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
41 changes: 41 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,47 @@

## [Unreleased]

Packages: `runtime-node`, `runtime-next`, `runtime-cli`, `otlp-ingester`, and the Python adapter (`adapters/python`, copied, not published). `runtime-core` (private, bundled into the others) changes too. `runtime-browser` and `runtime-edge` do not: their built `dist` is byte-identical to 1.19.0 (only `runtime-browser`'s README wording changed).

### Running commit and default release

- `otlp-ingester`: sink occurrences carry an optional `commit`: the commit the app runs. It is read from `deployment.commit`, else `vcs.ref.head.revision`, on the exception event, then the span or log record, then the resource. It is sent only when it is 7 to 40 hexadecimal characters, lower-cased, and nothing else from the resource is forwarded. When the occurrence's attributes have no `deployment.commit`, it is also stored there. Older platforms ignore the field.
- `runtime-node`: `initAutterServer` sends the running commit as the resource attribute `deployment.commit`. It is the first of `AUTTER_COMMIT`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `CF_PAGES_COMMIT_SHA`, `GIT_SHA`, `GIT_COMMIT`, `COMMIT_SHA`, `SOURCE_COMMIT`, `RENDER_GIT_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`, `HEROKU_SLUG_COMMIT`, `SOURCE_VERSION` holding 7 to 40 hexadecimal characters; anything else is skipped and the next variable is tried. Environment variables only: the SDK never runs git. `initAutterServer` and `initAutterLogging` also put it on the resource of every log record, so request summaries, operation summaries and errors promoted from log records carry the commit like spans do.
- `runtime-node`: `enrichDeployment()` and `npx @autter/runtime-node verify` use the same list and hex rule. `verify` defaults its release the same way as the SDK and reports the commit (`commit` in `--json`).
- Python adapter: `init_tracing()` reports `deployment.commit` from the same list, in the same order, lower-cased (environment variables only, never git). A `deployment.commit` set in `OTEL_RESOURCE_ATTRIBUTES` is kept. Request counts carry the same environment, commit and release as the spans.
- `runtime-cli`: without `--release`, `AUTTER_RELEASE` names the upload release. After `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `CF_PAGES_COMMIT_SHA` and `GIT_SHA` (unchanged: any value, in that order), the CLI also takes a commit from `@autter/runtime-node`'s other commit variables (`AUTTER_COMMIT`, `GIT_COMMIT`, `COMMIT_SHA`, `SOURCE_COMMIT`, `RENDER_GIT_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`, `HEROKU_SLUG_COMMIT`, `SOURCE_VERSION`) before falling back to `git rev-parse HEAD`. Existing builds upload under the same release as before, and it matches the release the SDK reports by default.
- **Behaviour change (Node and Python): a service that sets no release now reports its commit as the release.** With no `release` option (Node) or `service.version` (Python), the release is `AUTTER_RELEASE`, else the detected commit as the full value, so Autter can link errors to the commit and its pull request. An explicit release always wins. Turn it off in Node with `release: false` or `AUTTER_DETECT_RELEASE=false` (for `initAutterServer` and `initAutterLogging`), in Python with `AUTTER_DETECT_RELEASE=false` or `init_tracing(detect_release=False)`; the commit is still sent as `deployment.commit`.
- Upgrade notes: `enrichDeployment()` used to copy any value of those variables (up to 64 characters) into `deployment.commit`; a value that is not 7 to 40 hex characters (a branch or tag name) is now skipped. If `AUTTER_COMMIT` and one of the CLI's four variables hold different commits, the SDK reports `AUTTER_COMMIT` and the CLI uploads source maps under the other: set `AUTTER_RELEASE` where the app builds and where it runs to name releases yourself (both honour it).

### Test runs report environment `test`

- `runtime-node`: with no `environment` option and no `NODE_ENV`, a service running under Jest, Vitest or `node --test` (`JEST_WORKER_ID`, `VITEST`, `NODE_TEST_CONTEXT`) reports environment `test` instead of `production`. Applies to `initAutterServer`, `initAutterLogging` and `registerAutter`.
- Python adapter: under pytest (`PYTEST_VERSION` or `PYTEST_CURRENT_TEST` set, or `pytest` imported) or Django's `manage.py test`, `init_tracing()` sets `deployment.environment=test` when the resource has no environment (neither `deployment.environment.name` nor `deployment.environment`), and logs one info line. Detection is from the process only, never from the request.
- Python adapter: requests made through Starlette's or FastAPI's `TestClient` (user agent `testclient` or host `testserver`), or Django's test `Client` when the instrumentation records host `testserver`, get `autter.test_client: true` on their server span. With `OTEL_SEMCONV_STABILITY_OPT_IN=http`, Django's instrumentation records no host, so those requests are not marked (environment detection still works).
- `otlp-ingester`: a server span whose raw user agent is exactly `testclient` (Starlette's and FastAPI's in-process `TestClient`) gets `autter.test_client: true` before the user agent is dropped. It is a hint only: the ingester never acts on it and never changes the environment because of it, since a caller could use a user agent or host to hide its errors from production views and alerts. The environment is the resource's `deployment.environment.name` or `deployment.environment`, else `production`, as before.
- **Behaviour change (Node and Python): test runners report environment `test`.** Autter leaves `test` out of default views and never pages on it. An explicit environment always wins. Turn it off in Node by passing `environment` or setting `NODE_ENV`; in Python with `AUTTER_DETECT_TEST_ENV=false` or `init_tracing(detect_test_env=False)`, or by setting an environment on the resource. Other OpenTelemetry senders set `deployment.environment=test` in their test configuration (for example `OTEL_RESOURCE_ATTRIBUTES`).

### Trace propagation on by default in `@autter/runtime-next/client`

- **Behaviour change (`runtime-next`): `initAutterBrowser` from `@autter/runtime-next/client` sends a W3C `traceparent` on same-origin requests by default**, so a browser error links to the server trace of the request behind it. Turn it off with `initAutterBrowser({ ..., tracePropagation: false })`. `tracePropagationTargets` adds cross-origin APIs you control (they must allow the header in CORS: `Access-Control-Allow-Headers: traceparent`). A third-party origin never gets the header and sees no new CORS preflight; the tracker's own endpoint never gets one. `fetch` is traced through the network observer, so `captureNetworkFailures: false` turns it off for `fetch`. The client bundle grows by the tracing module (about 0.6 KB brotlied). It does nothing outside a browser, so server rendering of a client component is unaffected.
- `enableTracePropagation` and `disableTracePropagation` are still exported from `@autter/runtime-next/client`. An app that already calls `enableTracePropagation({ tracePropagationTargets })` keeps working: called before `initAutterBrowser`, its targets are kept, and `disableTracePropagation()` before it keeps propagation off.
- Plain `@autter/runtime-browser` stays opt-in (`enableTracePropagation()` from `@autter/runtime-browser/tracing`), and its 10 KB size gate is unchanged.
- `runtime-cli`: `autter-runtime sourcemaps setup` lists the trace propagation step in its next steps for browser setups, with the CORS note: for `@autter/runtime-browser`, the `enableTracePropagation()` call (left out when the file that starts the tracker already calls it); for `@autter/runtime-next`, that it is on and how to turn it off.

### Queue and worker context helpers

- `runtime-node`: `runtimeContext.inject(target, format?)` returns a copy of a job payload (`"payload"`, the default, under the key `autter`), HTTP headers (`"headers"`, header `autter`) or SQS `MessageAttributes` (`"sqs"`) carrying the current operation's carrier. Outside an operation it returns the target unchanged; it never mutates its input and never throws.
- `runtime-node`: `withRuntimeOperation(name, fn, attrs, { from })` now also accepts a payload, headers, SQS `MessageAttributes` or a whole SQS message (including a Lambda SQS record) that contains the `autter` key, besides a carrier or its JSON string. Malformed input is ignored and the operation starts unlinked. The consumer's summary carries the producer's operation id (`autter.operation.parent_id`), request id and `autter.parent_trace_id`: its trace is linked to the producer's, not continued, and the request id is what joins them.
- The carrier format is unchanged (`{ v: 1, op, req?, traceparent? }`): ids only, no attributes, user context or baggage.
- `runtime-next`: the root's browser and edge builds have a matching `runtimeContext.inject` stand-in that returns the target.
- Docs: BullMQ, SQS and Celery recipes in [docs/OPERATION-LOGGING.md](docs/OPERATION-LOGGING.md). Celery needs no Autter helper: OpenTelemetry's Celery instrumentation already continues the trace.

### Docs

- [Getting started](docs/GETTING-STARTED.md): the release and commit defaults for Node, the `enableTracePropagation` call where the browser tracker is set up ("Link browser errors to server requests"), the Next.js default, `deployment.commit` for other languages, and how test runs are separated ("Test runs").
- [Integrations](docs/INTEGRATIONS.md): FastAPI and Django CORS snippets for cross-origin APIs that receive `traceparent`, the Python adapter's commit, release and test-run detection with their opt-outs, and that `captureNetworkFailures: false` turns fetch tracing off.
- [Requests and errors](docs/REQUESTS-AND-ERRORS.md): `initAutterLogging`'s defaults and `enrichDeployment()`'s hex rule. [Architecture](docs/ARCHITECTURE.md): the sink occurrence's `commit`.

## [1.19.0] - 2026-11-15

Packages: `runtime-node` 1.15.0, `otlp-ingester` 1.17.0, `runtime-next` 1.10.0, and the Python adapter (`adapters/python`, copied, not published). Deploy the ingester first: from 1.17.0 it drops identifying attributes for every sender, including SDKs that predate this release.
Expand Down
7 changes: 7 additions & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1020,6 +1020,13 @@ above 1, on a loop-collapse sample (`1 + collapsed_count`; see
(issue counts, rate buckets) and treat the record as one sample for
everything else. A replay from ClickHouse reads it from `collapsed_count`.

Unreleased: `commit`, the commit the app runs: `deployment.commit`, else
`vcs.ref.head.revision`, read from the exception event, then the span or
log record, then the resource. It is sent only when it is 7 to 40
hexadecimal characters, lower-cased; nothing else of the resource is
forwarded. When the occurrence's `attributes` have no `deployment.commit`,
the SHA is stored there too. Older consumers ignore it.

Batches also carry `metrics` (1-minute usage rollup points) and `llmCalls`
(per-call LLM usage — provider, model, tokens, `costUsd`, `costSource`,
`userId`, `status`, `startedAt`) whenever the ingest produced them — same
Expand Down
87 changes: 82 additions & 5 deletions docs/GETTING-STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,8 +160,7 @@ initAutterServer({
apiKey: process.env.AUTTER_RUNTIME_KEY, // server key
endpoint: process.env.AUTTER_ENDPOINT, // your ingester URL (below)
service: "payments-api",
environment: process.env.NODE_ENV,
release: process.env.GIT_SHA, // enables "broke in release X"
// environment: NODE_ENV by default; release: the running commit (below)
});
```

Expand All @@ -178,6 +177,21 @@ AUTTER_ENDPOINT=http://localhost:4318 AUTTER_RUNTIME_KEY=autter_rt_local_dev_onl
`AUTTER_ENDPOINT` is the ingester's base URL, without `/v1/...`. If you
leave `endpoint` out, the SDK sends to Autter cloud (`https://otlp.autter.dev`).

You don't need to pass `release`. On Vercel, Render, Railway, Cloudflare
Pages, Heroku, GitHub Actions, or anywhere you set `GIT_SHA` or
`AUTTER_COMMIT`, the SDK reports the running commit as the release and as
`deployment.commit`, so Autter can link errors to the commit and its pull
request (and "broke in release X" works). Only a 7 to 40 character hex SHA
counts, and the SDK never runs git. Set `AUTTER_RELEASE` to use a different
name, or `release: false` / `AUTTER_DETECT_RELEASE=false` to report none.
Source maps uploaded with `autter-runtime sourcemaps upload` without
`--release` land under the same release when the build sees the same commit
variable; set `AUTTER_RELEASE` in both places to name releases yourself.

Errors from your own test runs stay out of production: under Jest, Vitest
or `node --test`, with no `environment` and no `NODE_ENV`, the SDK reports
environment `test`. See [Test runs](#test-runs).

That alone gives you: every incoming HTTP request traced-and-sampled,
request/error/duration rollups per route, crashes and unhandled promise
rejections captured (without changing whether your process crashes, and
Expand Down Expand Up @@ -360,14 +374,40 @@ Then in your frontend entry point:

```ts
import { initAutterBrowser } from "@autter/runtime-browser";
import { enableTracePropagation } from "@autter/runtime-browser/tracing";

initAutterBrowser({
endpoint: "/api/autter-runtime", // same-origin — no key here
service: "web-app",
release: import.meta.env.VITE_GIT_SHA,
});
enableTracePropagation(); // link browser errors to the server request behind them
```

### Link browser errors to server requests

`enableTracePropagation()` adds a W3C `traceparent` header to your app's
same-origin `fetch` and XHR requests. Your server continues that trace
(`@autter/runtime-node`, `@autter/runtime-next` and OpenTelemetry's HTTP
instrumentation do this with no setup), so a browser error links to the
server trace, and the server error, of the same request.

- Other origins never get the header, so third-party APIs see no new CORS
preflight. The tracker's own endpoint never gets one either.
- An API on another origin that you control: list it, and allow the header
in its CORS response (`Access-Control-Allow-Headers: traceparent`; FastAPI
and Django snippets in
[INTEGRATIONS.md](INTEGRATIONS.md#browser-requests-from-another-origin-cors)):

```ts
enableTracePropagation({ tracePropagationTargets: ["https://api.example.com/"] });
```
- `fetch` is traced through the tracker's network observer, so
`captureNetworkFailures: false` turns it off for `fetch` (XHR keeps it).

It is a separate import because it does not fit the main tracker's size
budget. In Next.js it is on by default (next section).

### Option B — direct (static sites, no backend)

```ts
Expand Down Expand Up @@ -415,6 +455,13 @@ routes share the SDK that `registerAutter` starts either way (1.6.1+).
Wrap route handlers in `withRuntimeRequest` for request summaries;
`middleware.ts` uses `@autter/runtime-next/edge`.

Trace propagation is on by default here: `initAutterBrowser` from
`@autter/runtime-next/client` adds a `traceparent` to same-origin requests
(route handlers, server actions), so browser errors link to the server
request behind them. `tracePropagation: false` turns it off;
`tracePropagationTargets: ["https://api.example.com/"]` adds a cross-origin
API you control (it must allow the header in CORS).

Errors Next catches itself — in server components, server actions, route
handlers and middleware — reach Autter with their stack through Next 15's
`onRequestError`. Add it to `instrumentation.ts`, next to `register()`:
Expand Down Expand Up @@ -442,11 +489,17 @@ package at all — configure the SDK you already use:
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-ingester.example.com
OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer ${AUTTER_RUNTIME_KEY}"
OTEL_SERVICE_NAME=payments-api
OTEL_RESOURCE_ATTRIBUTES=service.version=${GIT_SHA},deployment.environment=production
OTEL_RESOURCE_ATTRIBUTES=service.version=${GIT_SHA},deployment.commit=${GIT_SHA},deployment.environment=production
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.01
```

`deployment.commit` (a 7 to 40 character hex SHA) lets Autter map each
release to the commit it runs. Python services that use
`adapters/python/autter_tracing.py` get the commit, the release and the
test environment filled in for them
([Python](INTEGRATIONS.md#python-django-fastapi-flask-celery)).

Errors become issues when spans record exceptions
(`span.RecordError(err)` in Go, `record_exception` in Python, …) or carry
`ERROR` status. The ratio sampler above drops the errors of the traces it
Expand All @@ -463,6 +516,24 @@ exempt GenAI spans in a custom sampler or route them through an always-on
tracer provider. See
[INTEGRATIONS.md § LLM / GenAI calls](INTEGRATIONS.md#llm--genai-calls-any-language).

### Test runs

A test suite that runs with telemetry on would otherwise report its errors
as production. Test runs are separated by the environment the process
reports, `test`:

| Sender | Under a test runner | Turn it off |
| --- | --- | --- |
| `@autter/runtime-node` (and `@autter/runtime-next` on the server) | Jest, Vitest or `node --test`, with no `environment` option and no `NODE_ENV` | pass `environment` or set `NODE_ENV` |
| `autter_tracing.py` | pytest or Django's `manage.py test`, with no environment on the resource | `AUTTER_DETECT_TEST_ENV=false` or `init_tracing(detect_test_env=False)` |
| Any other OpenTelemetry SDK | set it yourself, e.g. `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=test` in the CI job | |

An explicit environment always wins. Autter leaves the `test` environment
out of its default views and never pages on it. The ingester never changes
the environment because of what a request says about itself (user agent,
host, client address): a caller could use that to hide its errors from
production views and alerts.

## 7. See your own events

`verify` (step 2) proves the path works. From your app's directory it also
Expand Down Expand Up @@ -541,8 +612,14 @@ clickhouse-client --password dev`.
- [ ] Client keys have `allowedOrigins` set to your exact app origins (a
client key with none accepts no origin; add your dev origin, e.g.
`http://localhost:3000`, if you test locally with it).
- [ ] `release` is wired to your git SHA in **both** frontend and backend —
it's what powers regression detection ("broke in release X").
- [ ] Both frontend and backend report a release — it's what powers
regression detection ("broke in release X"). The Node SDK and the
Python adapter report the running commit when your platform sets a
commit variable (`npx @autter/runtime-node verify` shows it); the
browser tracker needs `release` passed in at build time.
- [ ] Browser requests carry `traceparent` (`enableTracePropagation()`, on
by default with `@autter/runtime-next/client`), and cross-origin APIs
you list allow the header in CORS.
- [ ] Request summaries are always kept: `ignore` health checks and metrics
scrapes in `autterRequests`, and size `LOG_TTL_DAYS` at the ingester.
- [ ] Error codes are stable and low-cardinality — never ids or user data.
Expand Down
Loading
Loading