From d7acb3c12ad0750c1fefe41aee486e359f71f9cb Mon Sep 17 00:00:00 2001 From: Sagnik Ghosh Date: Sun, 15 Nov 2026 11:13:28 +0530 Subject: [PATCH] Trace propagation on by default for Next.js; docs and changelog for commit detection, test environments and queue helpers - @autter/runtime-next/client: initAutterBrowser turns on same-origin trace propagation by default (tracePropagation: false opts out; tracePropagationTargets adds cross-origin APIs). Third-party origins and the tracker's own endpoint never get a traceparent. Does nothing outside a browser. An enableTracePropagation/disableTracePropagation call made before initAutterBrowser keeps its effect. Plain @autter/runtime-browser stays opt-in; its dist is unchanged. - runtime-cli: `sourcemaps setup` prints the trace propagation step (with the CORS note) for browser setups. - runtime-node: log records' resource carries deployment.commit, like the trace resource, for initAutterServer and initAutterLogging. Added in the OTLP log sink, so runtime-core's encoder (shared with runtime-edge) and runtime-edge's dist stay unchanged. - Docs: Getting started (release/commit defaults, enableTracePropagation, test runs), Integrations (FastAPI and Django CORS, Python detection and opt-outs), Requests and errors, Architecture (sink `commit`), package READMEs. CHANGELOG [Unreleased] for #53-#56 and this change. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 41 +++++++++ docs/ARCHITECTURE.md | 7 ++ docs/GETTING-STARTED.md | 87 ++++++++++++++++-- docs/INTEGRATIONS.md | 89 ++++++++++++++++++- docs/REQUESTS-AND-ERRORS.md | 11 ++- packages/runtime-browser/README.md | 10 ++- packages/runtime-cli/src/setup.ts | 30 +++++++ packages/runtime-cli/test/setup.test.mjs | 37 ++++++++ packages/runtime-next/README.md | 46 +++++++--- packages/runtime-next/src/client.ts | 84 ++++++++++++++--- .../test/client-trace-default.test.mjs | 38 ++++++++ .../test/client-trace-disabled-first.test.mjs | 15 ++++ .../test/client-trace-explicit.test.mjs | 17 ++++ .../test/client-trace-optout.test.mjs | 16 ++++ packages/runtime-next/test/client.test.mjs | 27 ++++-- packages/runtime-next/test/fake-browser.mjs | 70 +++++++++++++++ packages/runtime-node/README.md | 7 +- packages/runtime-node/src/logger.ts | 3 + packages/runtime-node/src/logging-only.ts | 5 +- packages/runtime-node/src/server.ts | 2 +- packages/runtime-node/src/sinks.ts | 34 +++++-- .../runtime-node/test/environment.test.mjs | 6 ++ .../test/fixtures/golden-scenario.mjs | 8 +- 23 files changed, 632 insertions(+), 58 deletions(-) create mode 100644 packages/runtime-next/test/client-trace-default.test.mjs create mode 100644 packages/runtime-next/test/client-trace-disabled-first.test.mjs create mode 100644 packages/runtime-next/test/client-trace-explicit.test.mjs create mode 100644 packages/runtime-next/test/client-trace-optout.test.mjs create mode 100644 packages/runtime-next/test/fake-browser.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index 73d0b2c..5779955 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 50421d8..239a06e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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 diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md index e581f4a..d48d498 100644 --- a/docs/GETTING-STARTED.md +++ b/docs/GETTING-STARTED.md @@ -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) }); ``` @@ -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 @@ -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 @@ -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()`: @@ -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 @@ -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 @@ -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. diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md index 6930136..2b46343 100644 --- a/docs/INTEGRATIONS.md +++ b/docs/INTEGRATIONS.md @@ -52,6 +52,16 @@ initAutterBrowser({ }); ``` +Link browser errors to the server request behind them: call +`enableTracePropagation()` from `@autter/runtime-browser/tracing` after +`initAutterBrowser`. Same-origin requests then carry a W3C `traceparent`; +other origins never do, unless you list an API you control in +`tracePropagationTargets` and it allows the header in CORS +([FastAPI and Django](#browser-requests-from-another-origin-cors)). +`fetch` is traced through the network observer, so +`captureNetworkFailures: false` turns fetch tracing off. The +`@autter/runtime-next/client` tracker does this by default. + React render errors: wrap with `` (from `@autter/runtime-next/client`, works in any React app). Vue/Svelte/Angular: call `captureException(err)` from the framework's error hook @@ -69,10 +79,16 @@ const { initAutterServer } = require("@autter/runtime-node"); initAutterServer({ apiKey: process.env.AUTTER_RUNTIME_KEY, service: "payments-api", - release: process.env.GIT_SHA, }); ``` +With no `release`, the SDK reports `AUTTER_RELEASE`, else the running commit +from the platform (`GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `GIT_SHA`, +`RENDER_GIT_COMMIT`, …; 7 to 40 hex characters) as the release and as +`deployment.commit`. `release: false` or `AUTTER_DETECT_RELEASE=false` +reports none. With no `environment` and no `NODE_ENV`, it reports `test` +under Jest, Vitest or `node --test`, else `production`. + Relay for your frontend: `app.post("/api/autter-runtime", createBrowserRelayHandler({ apiKey }))`. ESM-only apps need OTel's loader hook (see the package README). @@ -151,7 +167,10 @@ out of the route bundles. Without it Next bundles extra copies of the SDK, which share the one `registerAutter` started (1.6.1+; 1.6.0 needed the line). See the package README. Route handlers: `export const POST = withRuntimeRequest(handler)` (flush wired to `after()`); -`middleware.ts`: `@autter/runtime-next/edge`. +`middleware.ts`: `@autter/runtime-next/edge`. The client tracker +(`@autter/runtime-next/client`) sends a `traceparent` on same-origin requests +by default, so browser errors link to the server request behind them; +`initAutterBrowser({ ..., tracePropagation: false })` turns it off. Errors Next catches itself (server components, server actions, route handlers, middleware) need Next 15's `onRequestError` hook, or they arrive as @@ -217,6 +236,35 @@ AUTTER_COUNT_REQUESTS=true # count every request (the default; older copies n in `OTEL_EXPORTER_OTLP_HEADERS` are URL-encoded, and `x-autter-key` needs no space. `service.version` is the release. +`init_tracing()` fills in what the resource leaves out; a value you set +always wins: + +- **Commit and release.** `deployment.commit` 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 hex characters + (environment variables only, never git). With no `service.version`, the + release is `AUTTER_RELEASE`, else that commit in full, so on those + platforms you can leave `service.version` out. `AUTTER_DETECT_RELEASE=false` + or `init_tracing(detect_release=False)` turns the release default off; the + commit is still sent. +- **Test runs.** Running your tests with tracing on? Under pytest or + `manage.py test`, the adapter reports `deployment.environment=test` unless + you set an environment yourself; set `AUTTER_DETECT_TEST_ENV=false` (or + `init_tracing(detect_test_env=False)`) to turn this off. An environment in + `OTEL_RESOURCE_ATTRIBUTES` counts as set, so keep + `deployment.environment=production` out of the environment your tests run + in. Autter leaves `test` out of default views and never pages on it. +- Requests made through Starlette's or FastAPI's `TestClient`, or Django's + test `Client` when the instrumentation records its host `testserver`, get + `autter.test_client: true` on their server span. + `autter.test_client` is a hint shown on the trace only; Autter never uses + it to decide the environment or to alert, since a caller can send any + user agent. + +Request counts carry the same environment, commit and release as the spans. + Call `init_tracing()` once in each process that serves requests or runs tasks, at startup, before the framework instrumentation: @@ -274,6 +322,43 @@ def init_worker_tracing(**kwargs): CeleryInstrumentor().instrument() ``` +### Browser requests from another origin (CORS) + +When the browser tracker propagates traces to an API on another origin +(`tracePropagationTargets`), the request carries a `traceparent` header. +It is not a CORS-safelisted header, so the browser sends a preflight and +blocks the request unless the API allows it. Allow your frontend's exact +origins and the header: + +```python +# FastAPI +from fastapi.middleware.cors import CORSMiddleware + +app.add_middleware( + CORSMiddleware, + allow_origins=["https://app.example.com"], + allow_methods=["*"], + allow_headers=["traceparent", "content-type"], + expose_headers=["x-request-id"], +) +``` + +```python +# Django (pip install django-cors-headers), settings.py +from corsheaders.defaults import default_headers + +INSTALLED_APPS = [..., "corsheaders"] +MIDDLEWARE = ["corsheaders.middleware.CorsMiddleware", ...] # before CommonMiddleware +CORS_ALLOWED_ORIGINS = ["https://app.example.com"] +CORS_ALLOW_HEADERS = (*default_headers, "traceparent") +CORS_EXPOSE_HEADERS = ["x-request-id"] +``` + +OpenTelemetry's FastAPI and Django instrumentation continue the browser's +trace with no other setup. The header is unsampled, so the parent-based +sampler does not head-sample those requests; `init_tracing()` still exports +the whole trace of any that fail. Same-origin requests need none of this. + ### Always-on errors Head sampling decides at a trace's first span, before anything has failed, diff --git a/docs/REQUESTS-AND-ERRORS.md b/docs/REQUESTS-AND-ERRORS.md index 8d658ec..d91235b 100644 --- a/docs/REQUESTS-AND-ERRORS.md +++ b/docs/REQUESTS-AND-ERRORS.md @@ -278,11 +278,18 @@ import { initAutterLogging } from "@autter/runtime-node"; initAutterLogging({ apiKey: process.env.AUTTER_RUNTIME_KEY, // omit → console/file only - service: "api", release: process.env.GIT_SHA, + service: "api", // release: AUTTER_RELEASE, else the running commit logging: { enrich: [enrichDeployment()] }, }); ``` +`initAutterLogging` takes the same `environment` and `release` defaults as +`initAutterServer`: `NODE_ENV`, else `test` under Jest, Vitest or +`node --test`, else `production`; `AUTTER_RELEASE`, else the running commit +(`release: false` or `AUTTER_DETECT_RELEASE=false` for none). The commit is +also sent as `deployment.commit` on every log record's resource, so request +summaries and errors promoted from log records carry it. + Requests, operations, `runtimeContext`, coded errors, sinks and enrichers all work; NodeSDK is never started (only `@opentelemetry/api` is read). Exceptions (`captureException`, errors thrown out of operations, uncaught crashes) are @@ -307,7 +314,7 @@ logging: { enrich: [enrichUserAgent(), enrichRequestSize(), enrichEdgeGeo(), enr | `enrichUserAgent()` | `user_agent.browser` ("Chrome 120"), `user_agent.os`, `user_agent.device` (desktop/mobile/tablet/bot), `user_agent.bot` — same mapping as runtime-browser; never the raw string | | `enrichRequestSize()` | `http.request.body.size`, `http.response.body.size` from Content-Length | | `enrichEdgeGeo()` | `geo.country.iso_code` from Cloudflare/Vercel/CloudFront/Fastly headers — country only | -| `enrichDeployment()` | `deployment.region`, `deployment.commit` from common platform env vars | +| `enrichDeployment()` | `deployment.region` from common platform env vars; `deployment.commit` from the commit variables `initAutterServer` reads (`AUTTER_COMMIT`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `GIT_SHA`, …), only when the value is 7 to 40 hex characters | ## Sinks and local files diff --git a/packages/runtime-browser/README.md b/packages/runtime-browser/README.md index edb16e4..6a97d43 100644 --- a/packages/runtime-browser/README.md +++ b/packages/runtime-browser/README.md @@ -193,7 +193,10 @@ the server continues the browser's trace and a browser failure links to the server spans and request summary of the same request. `@autter/runtime-node` (OpenTelemetry HTTP instrumentation) continues it with no setup. It is a separate import because it does not fit the main tracker's -10 KB budget (about 0.6 KB more, brotlied): +10 KB budget (about 0.6 KB more, brotlied), so in this package it stays +opt-in: call `enableTracePropagation()` once, after `initAutterBrowser`. +(`@autter/runtime-next/client` turns it on by default for same-origin +requests; `tracePropagation: false` turns it off there.) ```ts import { initAutterBrowser } from "@autter/runtime-browser"; @@ -229,8 +232,9 @@ Rules: - `fetch` is traced through the tracker's network observer, so `captureNetworkFailures: false` turns fetch propagation off; `XMLHttpRequest` is wrapped by the module itself. Call - `enableTracePropagation()` before your app sends requests; - `disableTracePropagation()` turns it off at runtime. + `enableTracePropagation()` before your app sends requests (requests + started earlier carry no header); `disableTracePropagation()` turns it off + at runtime. **CORS for cross-origin APIs.** `traceparent` is not a CORS-safelisted header, so a listed cross-origin API gets a preflight (`OPTIONS`) and must diff --git a/packages/runtime-cli/src/setup.ts b/packages/runtime-cli/src/setup.ts index 9bd1495..f202027 100644 --- a/packages/runtime-cli/src/setup.ts +++ b/packages/runtime-cli/src/setup.ts @@ -208,6 +208,34 @@ function releaseSnippet(detected: Detected): { file: string | undefined; snippet } } +const TRACE_CORS_NOTE = + "For a cross-origin API you control, list it in tracePropagationTargets and allow the header in its CORS response: Access-Control-Allow-Headers: traceparent."; + +/** + * The trace-propagation step for a browser setup: a traceparent on the app's + * requests links a browser error to the server request behind it. Null when + * there is no browser SDK, or the file that starts the tracker already + * configures it. + */ +export function tracePropagationStep(detected: Pick): string | null { + const pkg = detected.sdk.package; + if (!pkg) return null; + const file = detected.release.file; + const code = file ? (readText(join(detected.dir, file)) ?? "") : ""; + if (code.includes("enableTracePropagation")) return null; + if (pkg === "@autter/runtime-next") { + if (code.includes("tracePropagation")) return null; + return ( + "Browser errors link to the server request behind them through a traceparent header, which initAutterBrowser from @autter/runtime-next/client sends on same-origin requests (tracePropagation: false turns it off; older versions need enableTracePropagation() after it).\n" + + TRACE_CORS_NOTE + ); + } + return ( + `Link browser errors to the server request behind them: call enableTracePropagation() from @autter/runtime-browser/tracing after initAutterBrowser${file ? ` in ${file}` : ""}, so same-origin requests carry a traceparent header.\n` + + TRACE_CORS_NOTE + ); +} + function secretTargets(detected: Detected): SecretTarget[] { const where: SecretTarget[] = []; for (const ci of detected.ci) { @@ -572,6 +600,8 @@ export function runSetup(dir: string, options: SetupOptions = {}): SetupResult { addCommand(detected, `${detected.sdk.package}@latest`, false).command, ); } + const tracing = tracePropagationStep(detected); + if (tracing) next.push(tracing); if (!detected.sdk.package) { next.push("No Autter browser SDK in package.json: source maps resolve browser errors that @autter/runtime-browser (or @autter/runtime-next) 1.6.0+ reports. Set it up first, or alongside."); } diff --git a/packages/runtime-cli/test/setup.test.mjs b/packages/runtime-cli/test/setup.test.mjs index e7309eb..c25c26e 100644 --- a/packages/runtime-cli/test/setup.test.mjs +++ b/packages/runtime-cli/test/setup.test.mjs @@ -441,3 +441,40 @@ test("edits keep comments where they were and the list's trailing-comma style", ].join("\n"), ); }); + +test("browser setups get the trace-propagation step in next, with the CORS note", () => { + const tracing = (result) => result.next.filter((item) => /traceparent/.test(item)); + + // @autter/runtime-browser: opt-in, so the step names the call and the file. + const browser = setup(viteProject()).result; + assert.equal(tracing(browser).length, 1); + const [step] = tracing(browser); + assert.match(step, /^Link browser errors to the server request behind them: call enableTracePropagation\(\) from @autter\/runtime-browser\/tracing after initAutterBrowser in src\/main\.ts/); + assert.match(step, /\nFor a cross-origin API you control, list it in tracePropagationTargets and allow the header in its CORS response: Access-Control-Allow-Headers: traceparent\.$/); + assert.equal(step.split("\n").length, 2, "two lines"); + + // Already wired: nothing to add. + const wired = viteProject({ + "src/main.ts": + 'import { initAutterBrowser } from "@autter/runtime-browser";\nimport { enableTracePropagation } from "@autter/runtime-browser/tracing";\ninitAutterBrowser({ endpoint: "/api/autter-runtime", service: "web" });\nenableTracePropagation();\n', + }); + assert.deepEqual(tracing(setup(wired).result), []); + + // @autter/runtime-next: on by default in the client entry; the step says so and how to turn it off. + const nextApp = tempDir({ + "package.json": pkg({ scripts: { build: "next build" }, dependencies: { next: "15.5.0", "@autter/runtime-next": "^1.6.1", react: "^19.0.0" } }), + "next.config.mjs": "export default {};\n", + "app/autter.tsx": '"use client";\nimport { initAutterBrowser } from "@autter/runtime-next/client";\ninitAutterBrowser({ endpoint: "/api/autter-runtime", service: "web", release: process.env.NEXT_PUBLIC_AUTTER_RELEASE });\n', + }); + const [nextStep, ...more] = tracing(setup(nextApp).result); + assert.deepEqual(more, []); + assert.match(nextStep, /initAutterBrowser from @autter\/runtime-next\/client sends on same-origin requests \(tracePropagation: false turns it off/); + assert.match(nextStep, /Access-Control-Allow-Headers: traceparent\.$/); + + // No browser SDK: no step. + const server = tempDir({ + "package.json": pkg({ scripts: { build: "vite build" }, devDependencies: { vite: "^6.0.0" } }), + "vite.config.ts": "export default {}\n", + }); + assert.deepEqual(tracing(setup(server).result), []); +}); diff --git a/packages/runtime-next/README.md b/packages/runtime-next/README.md index 92522bf..c3a6138 100644 --- a/packages/runtime-next/README.md +++ b/packages/runtime-next/README.md @@ -118,7 +118,11 @@ own stack, `next.router_kind` `Pages Router` and `next.route_path` such as `registerAutter` passes options straight to `initAutterServer`, so the server SDK's defaults apply out of the box: exporters are flushed on process exit (`autoFlush`) and custom attributes are scrubbed for PII -before export (`redactAttributes`). The same goes for `sampleRate` and +before export (`redactAttributes`). With no `release`, the server reports +`AUTTER_RELEASE`, else the running commit (`VERCEL_GIT_COMMIT_SHA` on +Vercel, `GIT_SHA`, and the other variables in the `@autter/runtime-node` +README) as the release and as `deployment.commit`; `release: false` +reports none. The same goes for `sampleRate` and `ignoreErrors` (1.8.0); in the browser, `@autter/runtime-next/client` re-exports `withFilters` for `sampleRate`, `ignoreErrors` and `denyUrls` (`initAutterBrowser(withFilters({ endpoint, service, sampleRate: 0.5 }))`), @@ -160,24 +164,40 @@ export function Providers({ children }: { children: React.ReactNode }) { React render errors don't reach `window.onerror` — the boundary reports them via `captureException` and then renders your fallback. -**Linking browser errors to server traces** (opt-in): call -`enableTracePropagation` from `@autter/runtime-next/client`, next to -`initAutterBrowser` and before the app sends requests. Same-origin `fetch` -and XHR requests (your route handlers and server actions) then carry a W3C -`traceparent`, which `registerAutter` continues, so a browser error links to -the server trace of the request behind it. Cross-origin APIs get one only -when listed in `tracePropagationTargets`, and must allow the header in CORS. -`disableTracePropagation()` turns it off; the rules are in -`@autter/runtime-browser`'s README ("Trace propagation"). +**Linking browser errors to server traces** (on by default): +`initAutterBrowser` from `@autter/runtime-next/client` adds a W3C +`traceparent` header to same-origin `fetch` and XHR requests (your route +handlers and server actions). `registerAutter` continues it, so a browser +error links to the server trace and request summary of the request behind +it. Cross-origin requests never get the header unless you list them in +`tracePropagationTargets`, so third-party APIs see no new CORS preflight. +The tracker's own `endpoint` never gets one. ```tsx "use client"; -import { initAutterBrowser, enableTracePropagation } from "@autter/runtime-next/client"; +import { initAutterBrowser } from "@autter/runtime-next/client"; -initAutterBrowser({ endpoint: "/api/autter-runtime", service: "web-app" }); -enableTracePropagation({ tracePropagationTargets: ["https://api.example.com/"] }); +initAutterBrowser({ + endpoint: "/api/autter-runtime", + service: "web-app", + // Optional: a cross-origin API you control. It must allow the header in + // CORS (Access-Control-Allow-Headers: traceparent). + tracePropagationTargets: ["https://api.example.com/"], +}); ``` +- `tracePropagation: false` turns it off. With `withFilters`, spread its + result: `initAutterBrowser({ ...withFilters({ endpoint, service, sampleRate: 0.5 }), tracePropagation: false })`. +- `fetch` is traced through the tracker's network observer, so + `captureNetworkFailures: false` turns it off for `fetch` too (XHR keeps it). +- `enableTracePropagation({ tracePropagationTargets })` and + `disableTracePropagation()` are still exported, to change it at runtime. + An app that already calls `enableTracePropagation` keeps working: called + before `initAutterBrowser`, its targets are kept. +- Plain `@autter/runtime-browser` stays opt-in. The rules (which trace id + each event carries, sampling, existing headers) are in its README + ("Trace propagation"). + Also re-exported for convenience: `captureException`, `captureMessage`, `trackEvent`, `setUser`, `setContext`, `flush` (from `@autter/runtime-next/client`) and `captureServerException`, diff --git a/packages/runtime-next/src/client.ts b/packages/runtime-next/src/client.ts index 1e402de..e2e2aaa 100644 --- a/packages/runtime-next/src/client.ts +++ b/packages/runtime-next/src/client.ts @@ -11,10 +11,83 @@ * `sampleRate`, `ignoreErrors` and `denyUrls` (1.8.0) wrap the options: * * initAutterBrowser(withFilters({ endpoint: "/api/autter-runtime", service: "web-app", sampleRate: 0.5 })); + * + * Trace propagation is on by default here, unlike in plain + * @autter/runtime-browser: same-origin requests carry a W3C `traceparent`, + * so a browser error links to the server trace of the request behind it. + * `tracePropagation: false` turns it off; `tracePropagationTargets` adds + * cross-origin APIs you control. + */ + +import { initAutterBrowser as startTracker, type AutterBrowserOptions } from "@autter/runtime-browser"; +import { + enableTracePropagation as enableTracing, + disableTracePropagation as disableTracing, + type TracePropagationOptions, +} from "@autter/runtime-browser/tracing"; + +export interface AutterNextBrowserOptions extends AutterBrowserOptions { + /** + * W3C trace propagation (default true): same-origin `fetch` and XHR + * requests carry a `traceparent` header, which `registerAutter` continues, + * so a browser error links to the server trace of the request behind it. + * Cross-origin requests get one only when listed in + * `tracePropagationTargets`, and the tracker's own endpoint never does. + * `false` turns it off. `fetch` is traced through the network observer, + * so `captureNetworkFailures: false` turns it off for `fetch` too. + */ + tracePropagation?: boolean; + /** + * Cross-origin URLs that also get a `traceparent`: a string matches as a + * URL prefix, a RegExp is tested against the full URL. List only APIs you + * control, and allow the header in their CORS response + * (`Access-Control-Allow-Headers: traceparent`). + */ + tracePropagationTargets?: TracePropagationOptions["tracePropagationTargets"]; +} + +/** The tracker was started in this page: the first call in a browser wins, as in the tracker itself. */ +let started = false; +/** The app called enableTracePropagation or disableTracePropagation itself: its choice is kept. */ +let chosen = false; + +/** + * Start the browser tracker (`@autter/runtime-browser`'s initAutterBrowser) + * and, unless `tracePropagation: false`, trace propagation for same-origin + * requests and `tracePropagationTargets`. Does nothing outside a browser + * (server rendering of a client component) and nothing on a second call. */ +export function initAutterBrowser(options: AutterNextBrowserOptions): void { + const { tracePropagation, tracePropagationTargets, ...tracker } = options; + startTracker(tracker); + if (started || typeof window === "undefined") return; + started = true; + // enableTracePropagation({ tracePropagationTargets }) or + // disableTracePropagation() called before this keeps its effect. + if (tracePropagation === false || chosen) return; + enableTracing(tracePropagationTargets ? { tracePropagationTargets } : {}); +} + +/** + * Turn trace propagation on, or replace its targets. initAutterBrowser + * already turns it on for same-origin requests; called before it, this + * call's targets are kept. The same switch as + * `@autter/runtime-browser/tracing`, on the same tracker. + */ +export function enableTracePropagation(options: TracePropagationOptions = {}): void { + chosen = true; + enableTracing(options); +} + +/** Turn trace propagation off: at runtime, or before initAutterBrowser to keep it off. */ +export function disableTracePropagation(): void { + chosen = true; + disableTracing(); +} + +export type { TracePropagationOptions }; export { - initAutterBrowser, captureException, captureOutcome, captureMessage, @@ -34,15 +107,6 @@ export { type BreadcrumbInput, type BreadcrumbOptions, } from "@autter/runtime-browser/breadcrumbs"; -// Opt-in trace propagation (EI-11): a W3C `traceparent` on same-origin and -// listed requests, so browser errors link to the server trace they caused. -// Also kept out of the main bundle; re-exported so a Next app needs no -// direct @autter/runtime-browser dependency. -export { - enableTracePropagation, - disableTracePropagation, - type TracePropagationOptions, -} from "@autter/runtime-browser/tracing"; // Opt-in client-side volume control (EI-38): sampleRate, ignoreErrors and // denyUrls as a beforeSend filter, outside the main tracker's bundle. // initAutterBrowser(withFilters({ endpoint, service, sampleRate: 0.5, ignoreErrors: [/ResizeObserver/] })); diff --git a/packages/runtime-next/test/client-trace-default.test.mjs b/packages/runtime-next/test/client-trace-default.test.mjs new file mode 100644 index 0000000..db57dfa --- /dev/null +++ b/packages/runtime-next/test/client-trace-default.test.mjs @@ -0,0 +1,38 @@ +// @autter/runtime-next/client turns same-origin trace propagation on by +// default: initAutterBrowser alone adds a traceparent to the app's own +// requests, never to a third-party origin or to the tracker's endpoint. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { initAutterBrowser } from "../dist/client.js"; +import { ORIGIN, TRACEPARENT, TRACKER, fetchTraceparent, installFakeBrowser, xhrTraceparent } from "./fake-browser.mjs"; + +installFakeBrowser(); +initAutterBrowser({ ...TRACKER, tracePropagationTargets: ["https://api.example.test/"] }); + +test("same-origin requests get a traceparent with no extra call", async () => { + assert.match(await fetchTraceparent("/api/orders?page=2"), TRACEPARENT); + assert.match(await fetchTraceparent(`${ORIGIN}/api/orders`, { method: "POST" }), TRACEPARENT); + assert.match(xhrTraceparent("/api/cart"), TRACEPARENT); +}); + +test("a third-party origin never gets one by default", async () => { + assert.equal(await fetchTraceparent("https://cdn.thirdparty.test/lib.json"), null); + assert.equal(await fetchTraceparent("https://app.example.test.evil.test/api"), null, "a prefix of the origin is not the origin"); + assert.equal(await fetchTraceparent("https://api.example.test.evil.test/x"), null, "nor is a host that starts like a target"); + assert.equal(xhrTraceparent("https://maps.thirdparty.test/tiles"), null); +}); + +test("an origin listed in tracePropagationTargets gets one", async () => { + assert.match(await fetchTraceparent("https://api.example.test/v1/orders"), TRACEPARENT); + assert.match(xhrTraceparent("https://api.example.test/v1/cart"), TRACEPARENT); +}); + +test("the tracker's own endpoint is skipped", async () => { + assert.equal(await fetchTraceparent("/api/autter-runtime", { method: "POST", body: "{}" }), null); +}); + +test("a second initAutterBrowser call changes nothing", async () => { + initAutterBrowser({ ...TRACKER, tracePropagation: false }); + assert.match(await fetchTraceparent("/api/orders"), TRACEPARENT); + assert.match(await fetchTraceparent("https://api.example.test/v1/orders"), TRACEPARENT); +}); diff --git a/packages/runtime-next/test/client-trace-disabled-first.test.mjs b/packages/runtime-next/test/client-trace-disabled-first.test.mjs new file mode 100644 index 0000000..1f5b90f --- /dev/null +++ b/packages/runtime-next/test/client-trace-disabled-first.test.mjs @@ -0,0 +1,15 @@ +// disableTracePropagation() called before initAutterBrowser keeps +// propagation off: the default does not turn it back on. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { disableTracePropagation, initAutterBrowser } from "../dist/client.js"; +import { TRACKER, fetchTraceparent, installFakeBrowser, xhrTraceparent } from "./fake-browser.mjs"; + +installFakeBrowser(); +disableTracePropagation(); +initAutterBrowser(TRACKER); + +test("an earlier disableTracePropagation call keeps every request free of a traceparent", async () => { + assert.equal(await fetchTraceparent("/api/orders"), null); + assert.equal(xhrTraceparent("/api/cart"), null); +}); diff --git a/packages/runtime-next/test/client-trace-explicit.test.mjs b/packages/runtime-next/test/client-trace-explicit.test.mjs new file mode 100644 index 0000000..3e09273 --- /dev/null +++ b/packages/runtime-next/test/client-trace-explicit.test.mjs @@ -0,0 +1,17 @@ +// An app that already calls enableTracePropagation before initAutterBrowser +// (the documented opt-in before it became the default) keeps its targets: +// the default does not replace them. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { enableTracePropagation, initAutterBrowser } from "../dist/client.js"; +import { TRACEPARENT, TRACKER, fetchTraceparent, installFakeBrowser } from "./fake-browser.mjs"; + +installFakeBrowser(); +enableTracePropagation({ tracePropagationTargets: ["https://api.example.test/"] }); +initAutterBrowser(TRACKER); + +test("targets passed to an earlier enableTracePropagation call are kept", async () => { + assert.match(await fetchTraceparent("https://api.example.test/v1/orders"), TRACEPARENT); + assert.match(await fetchTraceparent("/api/orders"), TRACEPARENT); + assert.equal(await fetchTraceparent("https://cdn.thirdparty.test/lib.json"), null); +}); diff --git a/packages/runtime-next/test/client-trace-optout.test.mjs b/packages/runtime-next/test/client-trace-optout.test.mjs new file mode 100644 index 0000000..3044b43 --- /dev/null +++ b/packages/runtime-next/test/client-trace-optout.test.mjs @@ -0,0 +1,16 @@ +// `tracePropagation: false` keeps every request free of a traceparent, even +// same-origin and listed ones. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { initAutterBrowser } from "../dist/client.js"; +import { TRACKER, fetchTraceparent, installFakeBrowser, xhrTraceparent } from "./fake-browser.mjs"; + +installFakeBrowser(); +initAutterBrowser({ ...TRACKER, tracePropagation: false, tracePropagationTargets: ["https://api.example.test/"] }); + +test("tracePropagation: false sends no traceparent anywhere", async () => { + assert.equal(await fetchTraceparent("/api/orders"), null); + assert.equal(await fetchTraceparent("https://api.example.test/v1/orders"), null); + assert.equal(await fetchTraceparent("https://cdn.thirdparty.test/lib.json"), null); + assert.equal(xhrTraceparent("/api/cart"), null); +}); diff --git a/packages/runtime-next/test/client.test.mjs b/packages/runtime-next/test/client.test.mjs index e010da7..6d7e022 100644 --- a/packages/runtime-next/test/client.test.mjs +++ b/packages/runtime-next/test/client.test.mjs @@ -6,26 +6,37 @@ import * as tracing from "@autter/runtime-browser/tracing"; import * as filters from "@autter/runtime-browser/filters"; import * as client from "../dist/client.js"; -test("the client entry re-exports opt-in trace propagation, like breadcrumbs", () => { - // The very functions of @autter/runtime-browser/tracing, so they hook into - // the same tracker instance initAutterBrowser starts. - assert.equal(client.enableTracePropagation, tracing.enableTracePropagation); - assert.equal(client.disableTracePropagation, tracing.disableTracePropagation); +test("the client entry's trace propagation switches drive @autter/runtime-browser/tracing", () => { + // Thin wrappers (they remember that the app chose, so initAutterBrowser's + // default keeps that choice) over the tracing module, which hooks into the + // same tracker instance initAutterBrowser starts. Breadcrumbs are the very + // functions. assert.equal(client.enableBreadcrumbs, breadcrumbs.enableBreadcrumbs); + assert.equal(typeof tracing.enableTracePropagation, "function"); // Callable without a browser (no XMLHttpRequest here): a no-op wrap. client.enableTracePropagation({ tracePropagationTargets: ["https://api.example.com", /^https:\/\/internal\./] }); client.disableTracePropagation(); }); -test("the client entry's types include TracePropagationOptions, for ESM and CJS", () => { +test("initAutterBrowser outside a browser (server rendering a client component) does nothing and never throws", () => { + assert.equal(typeof globalThis.window, "undefined"); + client.initAutterBrowser({ endpoint: "/api/autter-runtime", service: "web" }); + client.initAutterBrowser({ endpoint: "/api/autter-runtime", service: "web", tracePropagation: false }); + assert.equal(typeof globalThis.XMLHttpRequest, "undefined", "nothing was wrapped or defined"); +}); + +test("the client entry's types include the trace propagation options, for ESM and CJS", () => { for (const file of ["client.d.ts", "client.d.cts"]) { const types = readFileSync(new URL(`../dist/${file}`, import.meta.url), "utf8"); assert.match(types, /enableTracePropagation/); assert.match(types, /disableTracePropagation/); assert.match(types, /TracePropagationOptions/); + assert.match(types, /AutterNextBrowserOptions/); + assert.match(types, /tracePropagation\?: boolean/); + assert.match(types, /tracePropagationTargets\?:/); } - // The bundle keeps the subpath import, so the tracing code stays out of - // apps that never call it. + // The bundle imports the tracing subpath (it is on by default here), so + // the app's bundler resolves the same module instance the tracker uses. assert.match(readFileSync(new URL("../dist/client.js", import.meta.url), "utf8"), /@autter\/runtime-browser\/tracing/); }); diff --git a/packages/runtime-next/test/fake-browser.mjs b/packages/runtime-next/test/fake-browser.mjs new file mode 100644 index 0000000..727f427 --- /dev/null +++ b/packages/runtime-next/test/fake-browser.mjs @@ -0,0 +1,70 @@ +// A minimal browser for the client entry's trace propagation tests: a page at +// https://app.example.test with fetch and XMLHttpRequest that record what +// they were sent. Each test file runs in its own process (node --test), so +// each starts the tracker once with its own options. + +export const ORIGIN = "https://app.example.test"; +export const TRACEPARENT = /^00-[0-9a-f]{32}-[0-9a-f]{16}-00$/; + +/** Every fetch the page made: { url, input, init }. */ +export const calls = []; +/** Every XMLHttpRequest the page opened. */ +export const xhrs = []; + +class FakeXHR { + status = 0; + readyState = 0; + headers = []; + open(_method, url) { + this.url = url; + this.readyState = 1; + xhrs.push(this); + } + send() {} + setRequestHeader(name, value) { + this.headers.push([name, value]); + } + getResponseHeader() { + return null; + } + addEventListener() {} + removeEventListener() {} + traceparent() { + const found = this.headers.filter(([name]) => name.toLowerCase() === "traceparent"); + return found.length ? found.map(([, value]) => value).join(", ") : null; + } +} + +export function installFakeBrowser() { + globalThis.window = { + origin: ORIGIN, + addEventListener() {}, + async fetch(input, init) { + const url = input instanceof Request ? input.url : String(input); + calls.push({ url, input, init }); + return new Response(null, { status: 200 }); + }, + }; + globalThis.document = { addEventListener() {}, visibilityState: "visible" }; + globalThis.location = { href: `${ORIGIN}/checkout`, pathname: "/checkout", origin: ORIGIN }; + globalThis.XMLHttpRequest = FakeXHR; + Object.defineProperty(globalThis, "navigator", { configurable: true, value: { sendBeacon: () => true } }); +} + +/** The traceparent the page's fetch to `url` was sent with (null when none). */ +export async function fetchTraceparent(url, init) { + await window.fetch(url, init); + const { input, init: sent } = calls[calls.length - 1]; + return new Headers(sent?.headers ?? (input instanceof Request ? input.headers : undefined)).get("traceparent"); +} + +/** The traceparent an XMLHttpRequest to `url` was sent with (null when none). */ +export function xhrTraceparent(url) { + const request = new XMLHttpRequest(); + request.open("GET", url); + request.send(); + return request.traceparent(); +} + +/** The options the tests start the tracker with (no session ping, no timings). */ +export const TRACKER = { endpoint: "/api/autter-runtime", service: "web", sessionTracking: false, captureTimings: false }; diff --git a/packages/runtime-node/README.md b/packages/runtime-node/README.md index 8b9d191..2cd794a 100644 --- a/packages/runtime-node/README.md +++ b/packages/runtime-node/README.md @@ -170,8 +170,8 @@ import { initAutterServer } from "@autter/runtime-node"; const autter = initAutterServer({ apiKey: process.env.AUTTER_RUNTIME_KEY!, service: "payments-api", - environment: process.env.NODE_ENV, - release: process.env.GIT_SHA, + // environment: NODE_ENV by default; release: AUTTER_RELEASE, else the + // running commit (GIT_SHA, VERCEL_GIT_COMMIT_SHA, ...). See Defaults below. }); // handled errors — always recorded, never sampled out: @@ -220,6 +220,9 @@ Defaults (cheap by construction): | Query strings in span URLs | parameter names only (`keepQueryParams`) | | Client IP, raw user agent, host id, command line | dropped (`keepIdentifyingAttributes`, `dropAttributes`) | | Forgotten `shutdown()` | exporters still flushed on exit (`autoFlush`) | +| Release (`release` unset) | `AUTTER_RELEASE`, else the running commit as the full SHA; `release: false` or `AUTTER_DETECT_RELEASE=false` reports none | +| Running commit | 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 hex characters, sent as `deployment.commit` (never runs git) | +| Environment (`environment` unset) | `NODE_ENV`, else `test` under Jest, Vitest or `node --test` (`JEST_WORKER_ID`, `VITEST`, `NODE_TEST_CONTEXT`), else `production` | **Error-linked trace retention.** Errors export at 100% while traces are head-sampled — on its own that strands a retained error without the trace diff --git a/packages/runtime-node/src/logger.ts b/packages/runtime-node/src/logger.ts index 18aab1c..7c8ffdb 100644 --- a/packages/runtime-node/src/logger.ts +++ b/packages/runtime-node/src/logger.ts @@ -166,6 +166,8 @@ export interface LoggerConfig { service: string; environment: string; release?: string; + /** The running commit (deployment.ts), sent as the `deployment.commit` resource attribute. */ + commit?: string; /** SDK identity for the `telemetry.distro.*` resource attributes. */ distro?: { name: string; version: string }; options?: RuntimeLoggingOptions; @@ -353,6 +355,7 @@ export function configureRuntimeLogger(next: LoggerConfig): void { service: next.service, environment: next.environment, ...(next.release ? { release: next.release } : {}), + ...(next.commit ? { commit: next.commit } : {}), ...(next.distro ? { distro: next.distro } : {}), }); } catch { diff --git a/packages/runtime-node/src/logging-only.ts b/packages/runtime-node/src/logging-only.ts index ef59c7e..cc33e8b 100644 --- a/packages/runtime-node/src/logging-only.ts +++ b/packages/runtime-node/src/logging-only.ts @@ -34,7 +34,7 @@ import { unregisterFlushTargets, type AutoFlushHandle, } from "./lifecycle.js"; -import { resolveEnvironment, resolveRelease } from "./deployment.js"; +import { detectCommit, resolveEnvironment, resolveRelease } from "./deployment.js"; import { makeRedactor, type RedactOptions } from "./redact.js"; import { markCaptured } from "./requests.js"; import { @@ -138,6 +138,8 @@ export function initAutterLogging(options: AutterLoggingOptions): AutterLogging const endpoint = (options.endpoint ?? "https://otlp.autter.dev").replace(/\/$/, ""); const environment = resolveEnvironment(options.environment); const release = resolveRelease(options.release); + // Environment variables only (deployment.ts), as initAutterServer. + const commit = detectCommit(); const redact = makeRedactor(options.redactAttributes ?? true); const mode = options.exceptions ?? "auto"; debugLog(`initialising logger-only service=${options.service} endpoint=${endpoint}`); @@ -226,6 +228,7 @@ export function initAutterLogging(options: AutterLoggingOptions): AutterLogging service: options.service, environment, ...(release ? { release } : {}), + ...(commit ? { commit } : {}), ...(options.logging ? { options: options.logging } : {}), redact, reportOutcome: (name, message, attributes) => { diff --git a/packages/runtime-node/src/server.ts b/packages/runtime-node/src/server.ts index 1c5c940..46c4a72 100644 --- a/packages/runtime-node/src/server.ts +++ b/packages/runtime-node/src/server.ts @@ -1727,7 +1727,7 @@ export function initAutterServer(options: AutterServerOptions): AutterServer { } configureRuntimeLogger({ endpoint, apiKey: apiKey ?? "", service: options.service, environment, distro, - release, options: options.logging, redact: redactor, + release, ...(commit ? { commit } : {}), options: options.logging, redact: redactor, run: (name, fn, attributes, links) => runWithSpan(processTracer, name, fn, redactor(attributes), links), reportOutcome, }); diff --git a/packages/runtime-node/src/sinks.ts b/packages/runtime-node/src/sinks.ts index df36ddb..c0978aa 100644 --- a/packages/runtime-node/src/sinks.ts +++ b/packages/runtime-node/src/sinks.ts @@ -43,6 +43,8 @@ export interface RuntimeSinkContext { service: string; environment: string; release?: string; + /** The running commit (7-40 hex), sent as the `deployment.commit` resource attribute, as on spans. */ + commit?: string; /** SDK identity for the `telemetry.distro.*` resource attributes. */ distro?: { name: string; version: string }; } @@ -77,6 +79,19 @@ interface QueuedLog { bytes: number; } +/** + * The logs request with `deployment.commit` on its resource, as the trace + * resource has it, so request summaries and errors promoted from log records + * carry the commit too. Added here rather than in runtime-core's encoder, + * which runtime-edge shares and which stays as it is. + */ +function withCommit(request: Record, commit: string | undefined): Record { + const attributes = (request.resourceLogs as Array<{ resource: { attributes: unknown[] } }> | undefined)?.[0]?.resource + .attributes; + if (commit && Array.isArray(attributes)) attributes.push({ key: "deployment.commit", value: { stringValue: commit } }); + return request; +} + /** * OTLP/HTTP JSON export to `${endpoint}/v1/logs`. Bounded exactly like * 1.4.0: 1000 records / 4 MiB buffered, 256 KiB per record, batches of 50 @@ -138,14 +153,17 @@ export function otlpSink(options: OtlpSinkOptions = {}): RuntimeSink { remaining -= batch.length; inFlight = batch.length; const body = JSON.stringify( - buildOtlpLogsRequest( - { - service: active.service, - environment: active.environment, - ...(active.release ? { release: active.release } : {}), - ...(active.distro ? { distro: active.distro } : {}), - }, - batch.map((entry) => entry.record), + withCommit( + buildOtlpLogsRequest( + { + service: active.service, + environment: active.environment, + ...(active.release ? { release: active.release } : {}), + ...(active.distro ? { distro: active.distro } : {}), + }, + batch.map((entry) => entry.record), + ), + active.commit, ), ); let failure: unknown; diff --git a/packages/runtime-node/test/environment.test.mjs b/packages/runtime-node/test/environment.test.mjs index 14840d6..a55ec59 100644 --- a/packages/runtime-node/test/environment.test.mjs +++ b/packages/runtime-node/test/environment.test.mjs @@ -257,6 +257,7 @@ test("initAutterServer: the detected commit is deployment.commit and, by default assert.equal(only(detected.spans, "deployment.commit"), SHA); assert.equal(only(detected.spans, "service.version"), SHA); assert.equal(only(detected.logs, "service.version"), SHA, "log records carry the same release"); + assert.equal(only(detected.logs, "deployment.commit"), SHA, "and the same commit"); const explicit = await run("server", { release: "v2" }, { GITHUB_SHA: SHA, AUTTER_RELEASE: "r9" }); assert.equal(only(explicit.spans, "service.version"), "v2"); @@ -269,6 +270,7 @@ test("initAutterServer: the detected commit is deployment.commit and, by default assert.equal(only(off.spans, "service.version"), undefined); assert.equal(only(off.logs, "service.version"), undefined); assert.equal(only(off.spans, "deployment.commit"), SHORT); + assert.equal(only(off.logs, "deployment.commit"), SHORT, "the commit is on log records whatever the release"); const envOff = await run("server", {}, { GIT_SHA: SHORT, AUTTER_RELEASE: "r9", AUTTER_DETECT_RELEASE: "false" }); assert.equal(only(envOff.spans, "service.version"), undefined); @@ -277,16 +279,19 @@ test("initAutterServer: the detected commit is deployment.commit and, by default const notCommit = await run("server", {}, { GIT_SHA: "main" }); assert.equal(only(notCommit.spans, "service.version"), undefined); assert.equal(only(notCommit.spans, "deployment.commit"), undefined); + assert.equal(only(notCommit.logs, "deployment.commit"), undefined); }); test("initAutterLogging: the same environment and release defaults", async () => { const outside = await run("logging"); assert.equal(only(outside.logs, "deployment.environment"), "production"); assert.equal(only(outside.logs, "service.version"), undefined); + assert.equal(only(outside.logs, "deployment.commit"), undefined); const vitest = await run("logging", {}, { VITEST: "true", RAILWAY_GIT_COMMIT_SHA: SHA }); assert.equal(only(vitest.logs, "deployment.environment"), "test"); assert.equal(only(vitest.logs, "service.version"), SHA); + assert.equal(only(vitest.logs, "deployment.commit"), SHA, "logger-only mode sends the commit too"); const explicit = await run("logging", { environment: "eu", release: "v3" }, { VITEST: "true", GIT_SHA: SHA, NODE_ENV: "development" }); assert.equal(only(explicit.logs, "deployment.environment"), "eu"); @@ -294,4 +299,5 @@ test("initAutterLogging: the same environment and release defaults", async () => const off = await run("logging", { release: false }, { GIT_SHA: SHA }); assert.equal(only(off.logs, "service.version"), undefined); + assert.equal(only(off.logs, "deployment.commit"), SHA); }); diff --git a/packages/runtime-node/test/fixtures/golden-scenario.mjs b/packages/runtime-node/test/fixtures/golden-scenario.mjs index 5eff5b5..e3d79b2 100644 --- a/packages/runtime-node/test/fixtures/golden-scenario.mjs +++ b/packages/runtime-node/test/fixtures/golden-scenario.mjs @@ -116,14 +116,16 @@ export function normalise(bodies, { stripAdditive = false } = {}) { return bodies.map((body) => ({ resourceLogs: body.resourceLogs.map((resourceLog) => ({ ...resourceLog, - // telemetry.distro.* (SDK identity for the compat check) is - // additive resource metadata, not part of the 1.4.0 record shape. + // telemetry.distro.* (SDK identity for the compat check) and + // deployment.commit (the running commit, when a commit variable + // such as CI's GITHUB_SHA is set) are additive resource metadata, + // not part of the 1.4.0 record shape. ...(stripAdditive && resourceLog.resource ? { resource: { ...resourceLog.resource, attributes: resourceLog.resource.attributes.filter( - (attribute) => !attribute.key.startsWith("telemetry.distro."), + (attribute) => !attribute.key.startsWith("telemetry.distro.") && attribute.key !== "deployment.commit", ), }, }