@heystack/otel 0.9.2 → 0.11.0

package/README.md

@@ -22,9 +22,38 @@ HEYSTACK_API_KEY=sk_live_…
 | Next.js — **any** deploy target (Vercel/Node **and** Cloudflare/OpenNext) | `@heystack/otel/next` | `registerHeystack` in `instrumentation.ts`. Auto-detects Node vs Cloudflare workerd and picks the right exporter. No-op on Edge. |
 | Standalone Cloudflare Workers (hand-written `export default { fetch }`) | `@heystack/otel/workers` | `instrument()` wraps your handler. Fetch-based exporter, flushes via `ctx.waitUntil`. |
 | Node / Express / Fastify / NestJS (long-running server) | `@heystack/otel/node` | `initHeystack`: auto-instrumentations + graceful shutdown. |
-| Browser (SPA / any web frontend) | `@heystack/otel/web` | `instrumentWeb`: session replay + W3C `traceparent` on outgoing fetch. No-op on the server (SSR-safe). |
+| Browser (SPA / any web frontend) | `@heystack/otel/web` | `instrumentWeb`: session replay + opt-in browser distributed tracing (`tracing: true`) that emits CLIENT spans + propagates W3C `traceparent` (browser→API shows as one trace). No-op on the server (SSR-safe). |
 | Anywhere (pure helpers) | `@heystack/otel` | `buildExporterConfig`, types. No Node SDK loaded. |
 
+## Release & commit attribution (`version` / `build`)
+
+Two optional options tag every span with **which release and commit it came from**, so the console can power **release health**, **suspect release**, and **suspect commit** views (spot the exact version/commit that introduced a regression). They work on **every runtime entry** (`/node`, `/next`, `/workers`).
+
+```ts
+initHeystack({
+  apiKey: process.env.HEYSTACK_API_KEY,
+  service: "my-app",
+  version: process.env.APP_VERSION,          // → service.version (e.g. "1.4.2" or a git tag)
+  build: process.env.GIT_SHA,                // → service.build   (the commit SHA)
+});
+```
+
+| Option | Resource attribute | Meaning |
+| --- | --- | --- |
+| `version` | `service.version` | Release identifier — a semver (`1.4.2`), a git tag, or any string that changes per release. Groups telemetry by release for **release health** + **suspect release**. |
+| `build` | `service.build` | The commit SHA of this deploy. Powers **suspect commit** — when you configure a repository URL for the app in the console, the SHA deep-links to the exact commit. |
+
+Both are optional and only emitted when set — an empty value is skipped (the console's release queries filter these out). Set them from your build/deploy environment, e.g. `build: process.env.GIT_SHA` (`GIT_SHA=$(git rev-parse HEAD)` in CI).
+
+On **`/node`** they also fall back to environment variables when the option is omitted: `HEYSTACK_SERVICE_VERSION` (or `OTEL_SERVICE_VERSION`) for the release and `HEYSTACK_SERVICE_BUILD` for the commit — so a Node deploy can attribute a release without touching code:
+
+```bash
+HEYSTACK_SERVICE_VERSION=1.4.2
+HEYSTACK_SERVICE_BUILD=$(git rev-parse HEAD)
+```
+
+On **`/next`** pass them to `registerHeystack({ service, version, build })` — they're threaded to whichever runtime the app runs on (Node or workerd). On **`/workers`** pass them in the `instrument()` / `initHeystackWorkers()` config.
+
 ## Node / Express / etc.
 
 At the very top of your app's entry file:
@@ -32,10 +61,15 @@ At the very top of your app's entry file:
 ```ts
 import { initHeystack } from "@heystack/otel/node";
 
-initHeystack({ apiKey: process.env.HEYSTACK_API_KEY, service: "my-app" });
+initHeystack({
+  apiKey: process.env.HEYSTACK_API_KEY,
+  service: "my-app",
+  version: process.env.APP_VERSION, // optional: release health + suspect release/commit
+  build: process.env.GIT_SHA,       // optional: commit SHA (see "Release & commit attribution")
+});
 ```
 
-This enables auto-instrumentations (HTTP, Express, etc.) so you get spans without manual wiring.
+This enables auto-instrumentations (HTTP, Express, etc.) so you get spans without manual wiring. `version`/`build` are optional (see [Release & commit attribution](#release--commit-attribution-version--build)).
 
 ### Slimming down auto-instrumentations (cost)
 
@@ -120,6 +154,8 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 | `sampling` | `{ rate?: number } \| { remote: true }` | Head-sampling configuration. `{ rate }`: keep a deterministic fraction of fresh root traces (0–1; default `1` = keep all). `{ remote: true }`: fetch the rate from the Heystack config endpoint instead — lets you change it centrally without redeploying. Cold isolates keep all traffic until the first config fetch resolves; fails open if the config can't be reached. Parent-respecting in both modes: a request arriving with a sampled `traceparent` is always recorded. See [Head sampling](#head-sampling) below. |
 | `ai` | `{ captureContent?: boolean; redact?: (text: string) => string; maxContentChars?: number }` | LLM/gen_ai capture for outbound calls to known providers. See [AI / LLM observability](#ai--llm-observability) below. |
 | `waitUntil` | `(p: Promise<unknown>) => void` | Override the isolate keep-alive hook; defaults to the auto-detected `ctx.waitUntil`. |
+| `version` | `string?` | Release identifier → `service.version` resource attribute. Powers release health + suspect release. See [Release & commit attribution](#release--commit-attribution-version--build). |
+| `build` | `string?` | Commit SHA → `service.build` resource attribute. Powers suspect commit (deep-links to the commit when a repo URL is set in the console). |
 | `endpoint` | `string?` | Override the ingest endpoint (advanced). |
 
 ### Head sampling
@@ -304,13 +340,18 @@ The default export still needs to be wrapped with `instrument()` (or `initHeysta
 
 ## `@heystack/otel/web` (browser / session replay)
 
-For a browser frontend (any SPA / web app), `instrumentWeb` records **session replay** and injects a W3C `traceparent` header on outgoing `fetch` calls, so replays correlate with the backend traces they triggered. It is a **no-op on the server** (SSR-safe), so it's safe to call from code that also runs during server rendering.
+For a browser frontend (any SPA / web app), `instrumentWeb` records **session replay**, captures **uncaught errors + `console.error`** as logs, and injects a W3C `traceparent` header on outgoing `fetch` calls, so replays/errors correlate with the backend traces they triggered. It is a **no-op on the server** (SSR-safe), so it's safe to call from code that also runs during server rendering.
+
+The rrweb recorder **ships inside this package** — there is nothing else to install. Uploads go cross-origin to the Heystack ingest endpoint and **work out of the box** (no CORS configuration on your side).
 
 ```ts
 import { instrumentWeb } from "@heystack/otel/web";
 
 const stop = await instrumentWeb({
-  apiKey: process.env.HEYSTACK_API_KEY, // same ingest key as the rest of the SDK
+  // A BROWSER-exposed ingest key — it ships to the client, like an analytics
+  // write key. Use a public env var (below), ideally a dedicated key you can
+  // rotate independently of your server-side key. NOT your server secret.
+  apiKey: import.meta.env.VITE_HEYSTACK_API_KEY, // Vite; Next.js: process.env.NEXT_PUBLIC_HEYSTACK_API_KEY
   service: "my-web-app",
 });
 
@@ -320,17 +361,88 @@ stop();
 
 `instrumentWeb` returns a `stop()` function that ends the recording session.
 
+**Where to call it.** It must run in the **browser**. In a Vite/CRA SPA, call it once in your client entry (`main.tsx`). In **Next.js (App Router)**, wrap it in a small `"use client"` component that calls it from a `useEffect` and mount that once in your root layout (server components can't call it). Recording is **server-gated**: nothing is captured until you enable replay for the app in the console, so it's safe to ship this before flipping the switch.
+
 ### Options
 
 | Option | Type | Notes |
 | --- | --- | --- |
-| `apiKey` | `string` | **Required.** The same Heystack ingest key used by the rest of the SDK. |
+| `apiKey` | `string` | **Required.** A Heystack ingest key, **exposed to the browser** (public env var). Prefer a dedicated key you can rotate — not your server-side secret. |
 | `service` | `string` | **Required.** The OTel service name (matches the app's service in the console). |
 | `userId` | `string?` | Optional app-supplied identifier stamped on the session. |
 | `endpoint` | `string?` | Optional ingest endpoint override (defaults to the Heystack ingest endpoint). |
 | `sampleRate` | `number?` | Optional **local** override for the recording sample rate (0–1). By default sampling is controlled from the console. |
 | `flushIntervalMs` | `number?` | How often buffered events are flushed (default 5000ms). |
 | `flushEveryEvents` | `number?` | Max buffered events before an early flush (default 200). |
+| `tracing` | `boolean?` | Opt in to **browser distributed tracing** (default off). Emits a real CLIENT span per outbound `fetch` and propagates W3C trace context, so browser→backend calls show as one connected trace + a service-map edge. Independent of replay. |
+| `traceSampleRate` | `number?` | Head sample rate for browser tracing (0–1, default 1 when `tracing` is on). Lower it to cap span volume/cost on busy apps. |
+| `errors` | `boolean?` | Capture uncaught browser errors (`window.onerror` + `unhandledrejection`) as logs. **On by default** — set `false` to disable. Independent of replay/tracing. |
+| `captureConsole` | `'error' \| 'warn' \| false` | Capture `console` output as logs. `'error'` (default) captures `console.error`; `'warn'` captures `console.warn` **and** `console.error`; `false` disables it. Rate-capped + recursion-guarded. |
+| `version` | `string?` | Release identifier → the `service.version` resource attribute on exported browser logs (release attribution / suspect release). |
+| `build` | `string?` | Commit SHA → the `service.build` resource attribute on exported browser logs. |
+
+### Browser distributed tracing
+
+By default `/web` only records session replay. Set `tracing: true` to also trace the browser: each outbound `fetch` becomes a CLIENT span, and the injected `traceparent` makes the downstream service's SERVER span its child — so a browser→API call renders as **one connected trace** and a **service-map edge** (`web → api`). This is separate from replay (it works even with replay off).
+
+```ts
+await instrumentWeb({
+  apiKey: import.meta.env.VITE_HEYSTACK_API_KEY,
+  service: "my-web-app",
+  tracing: true,
+  traceSampleRate: 0.25, // sample 25% of requests — tune for cost
+});
+```
+
+It's **cost-aware and safe by design**: off unless you opt in; head-sampled (an unsampled request still propagates `traceparent` with the sampled flag cleared, so the backend makes the same keep/drop decision — no orphaned server spans); and the exporter posts through the *original* `fetch`, never tracing its own upload (no self-export loop). Spans post to `/v1/traces` cross-origin with no CORS setup on your side.
+
+### Browser error & console collection
+
+`instrumentWeb` captures **uncaught browser errors** out of the box — no extra setup. Any `window.onerror` / unhandled promise rejection becomes an OTLP **log** (`event.name=browser.error`, `ERROR` severity) carrying the OTel `exception.type` / `exception.message` / `exception.stacktrace` semconv attributes, the page `url.full`, the `session_id` (so it correlates to the session replay), and — when `tracing` is on — the active `trace_id` / `span_id`. `console.error` is captured too by default.
+
+```ts
+await instrumentWeb({
+  apiKey: import.meta.env.VITE_HEYSTACK_API_KEY,
+  service: "my-web-app",
+  version: "1.4.2",            // → service.version (release attribution)
+  build: "abc1234",           // → service.build  (commit)
+  captureConsole: "warn",     // capture console.warn + console.error (default: 'error')
+  // errors: false,           // opt out of error capture entirely
+});
+```
+
+It's the **same cost-safe design** as tracing/replay: logs POST to `/v1/logs` through the *original* `fetch` (captured before any patching) so the exporter never traces its own upload — no self-export loop. Console capture is **recursion-guarded** (anything logged on the export path is never re-captured) and **rate-capped** (max ~60 records/minute; the overflow is dropped and counted, with one summary log emitted when the cap lifts) so a runaway `console.error` in a render loop can't flood ingest. Errors show up in the console **Logs** tab and correlate to their session replay and trace.
+
+### In-app bug reports (`reportBug`)
+
+Let users report a bug from inside your app. `reportBug` is a headless API — **no widget, you own the UX** — that files a structured report and auto-attaches the context a triager needs: the current URL, user agent, replay `session_id`, active `trace_id`, `release` / `build`, and the **last few captured browser errors** (so you see what was going wrong on the page right before the report). The report also appears on the Logs timeline (`event.name=user.bug_report`).
+
+Call it any time after `instrumentWeb()` has run (it throws if the SDK isn't initialised yet, or if `message` is empty). Network failures are swallowed — a failed report never breaks your app.
+
+```ts
+import { instrumentWeb, reportBug } from "@heystack/otel/web";
+
+await instrumentWeb({ apiKey: import.meta.env.VITE_HEYSTACK_API_KEY, service: "my-web-app" });
+
+// A minimal report button (wire this to whatever UI you like):
+const btn = document.querySelector("#report-bug")!;
+btn.addEventListener("click", async () => {
+  const message = prompt("What went wrong?");
+  if (!message) return;
+  await reportBug({
+    message,
+    email: currentUser?.email,          // optional — so the team can follow up
+    context: { plan: "pro", screen: "checkout" }, // optional app metadata (string→string)
+  });
+  alert("Thanks — your report was sent.");
+});
+```
+
+Reports land in the console under the app's **Bugs** tab, already linked to the session replay, the trace, and the recent errors — one click from report to root cause. The POST goes to `/v1/bug-reports` via the same *original* `fetch` used by the other exporters (no self-export loop).
+
+### Session-replay keyframes (seekable playback)
+
+The recorder checkpoints a fresh full snapshot roughly every **60 seconds** and starts a new chunk at each one (a "keyframe"). The console player can therefore begin playback from the nearest keyframe at or before a target moment — e.g. jumping straight to where an error happened — instead of downloading the whole session first. No configuration; it's automatic.
 
 ### Sampling & masking come from the console
 
@@ -364,6 +476,8 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.11.0`** — **`/web`: browser error + console collection, in-app bug reports, and seekable replay keyframes.** `instrumentWeb` now captures uncaught errors (`window.onerror` + `unhandledrejection`) and `console.error` as OTLP logs by default (`event.name=browser.error` / `browser.console`, with `exception.*` semconv, `url.full`, `session_id`, and the active trace/span ids when `tracing` is on). New options: `errors?: boolean` (default `true`), `captureConsole?: 'error' | 'warn' | false` (default `'error'`). New **`reportBug({ message, email?, context? })`** API — a headless in-app bug reporter that POSTs to `/v1/bug-reports` and auto-attaches the URL, user agent, `session_id`, active `trace_id`, `release`/`build`, and the last ≤20 captured browser errors (also emitted as a `user.bug_report` log); reports triage in the console **Bugs** tab. The `version` / `build` options are now stamped as `service.version` / `service.build` on exported browser logs (release attribution). Console capture is recursion-guarded + rate-capped (no self-export loop, no flood). The recorder also checkpoints a keyframe (~60s) so the console player seeks from the nearest snapshot instead of loading the whole session. No breaking changes; all new options are optional.
+- **`0.10.0`** — **release / commit attribution (`version` + `build`) on every runtime entry.** New optional options: `version` → the `service.version` resource attribute (a release identifier such as `1.4.2` or a git tag), `build` → the `service.build` resource attribute (the commit SHA). They power **release health**, **suspect release**, and **suspect commit** in the console — attributing a regression to the version/commit that introduced it (suspect-commit deep-links to the commit when a repo URL is configured for the app). Wired on `/node`, `/next` (threaded to whichever runtime runs), and `/workers`; accepted on `/web` for API symmetry. `/node` also reads `HEYSTACK_SERVICE_VERSION` / `OTEL_SERVICE_VERSION` and `HEYSTACK_SERVICE_BUILD` as env fallbacks. Both options are optional and only emitted when non-empty. No breaking changes. See [Release & commit attribution](#release--commit-attribution-version--build).
 - **`0.9.2`** — **`/workers`: `instrument()` no longer breaks WebSocket / Durable Object upgrades.** The fetch wrapper rebuilt every response with `new Response(...)`, which **drops the `webSocket` property** on a `101 Switching Protocols` upgrade — so every WebSocket connection on an instrumented Worker failed *whenever tracing was active* (an API key set), while passing in dev/staging where `instrument()` is a passthrough. `instrument()` now detects an upgrade (`response.webSocket` present, or `status === 101`) and returns the **original response untouched** (span closed immediately; no `traceparent` header injected — headers on a 101 aren't delivered anyway). Fixes failed `wss://` connections behind `routeAgentRequest` / any `new WebSocketPair()` handler. No API change; upgrade and redeploy.
 - **`0.9.1`** — **`/workers`: binding spans no longer orphan without `nodejs_compat`.** On a workerd runtime without `nodejs_compat` (no `globalThis.AsyncLocalStorage`), the synchronous fallback context manager cannot carry the active span across an `await` — so a D1/KV/R2/Vectorize/AI/Queue/Service span created *after* an `await` in your handler was emitted as the root of its own single-span trace instead of a child of the request. `instrument()` now captures the request's SERVER context per-request and uses it as an explicit parent fallback when no span is active, so binding operations are always children of the request trace. `nodejs_compat` is still recommended for cross-`await` parenting of outbound-fetch CLIENT spans and manual `withSpan` spans. No API change; upgrade and redeploy.
 - **`0.9.0`** — **`/workers`: automatic LLM gen_ai enrichment for outbound API calls.** Outbound `fetch` calls to known LLM providers (OpenAI, Anthropic, Cloudflare AI Gateway, Google) automatically gain `gen_ai.*` OTel semantic-convention attributes on the CLIENT span — model, token counts, finish reason, response ID — with no extra code. New optional `WorkersConfig.ai` option: `captureContent: true` also captures prompt/completion text (off by default; **strongly recommended for AI-app RCA**), with `redact` for scrubbing and `maxContentChars` for length capping. The original request/response bodies are never consumed (request read only when already a string; response via `response.clone()`). Streaming responses skip response enrichment. No breaking changes.

package/dist/core.d.ts

@@ -6,7 +6,41 @@ export interface HeystackOptions {
     service: string;
     /** Override the ingest endpoint (defaults to Heystack production). */
     endpoint?: string;
+    /**
+     * Release identifier for this deploy — maps to the `service.version` resource
+     * attribute (a semver like `1.4.2`, a git tag, or any string that changes per
+     * release). Powers **release health** and the **suspect-release** view in the
+     * console: it groups telemetry by release so a regression can be pinned to the
+     * version that introduced it. Recommended for every deploy.
+     */
+    version?: string;
+    /**
+     * Commit SHA for this deploy — maps to the `service.build` resource attribute.
+     * Powers **suspect-commit** attribution: when a repository URL is configured
+     * for the app in the console, the SHA becomes a deep link to the exact commit.
+     * Use the full or short git SHA of the build.
+     */
+    build?: string;
 }
+/**
+ * Resource-attribute key for the commit/build identifier. `service.version` has a
+ * standard OTel semantic-convention constant (`ATTR_SERVICE_VERSION`); there is
+ * no standard key for the build SHA, so Heystack uses the `service.build` literal.
+ */
+export declare const ATTR_SERVICE_BUILD = "service.build";
+/**
+ * Pure, runtime-agnostic: map the optional release-attribution options to OTel
+ * resource attributes — `version` → `service.version`, `build` → `service.build`.
+ *
+ * Only non-empty values are included: the console's release queries filter
+ * `!= ''`, so emitting an empty attribute is pure noise. Depends on nothing but
+ * the pure `@opentelemetry/semantic-conventions` constant, so it is safe for
+ * every entry including the WinterCG-only `/workers` path.
+ */
+export declare function releaseResourceAttributes(o: {
+    version?: string;
+    build?: string;
+}): Record<string, string>;
 export interface ExporterConfig {
     url: string;
     headers: {

package/dist/core.js

@@ -1,4 +1,30 @@
+import { ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 export const DEFAULT_ENDPOINT = "https://ingest.heystack.dev";
+/**
+ * Resource-attribute key for the commit/build identifier. `service.version` has a
+ * standard OTel semantic-convention constant (`ATTR_SERVICE_VERSION`); there is
+ * no standard key for the build SHA, so Heystack uses the `service.build` literal.
+ */
+export const ATTR_SERVICE_BUILD = "service.build";
+/**
+ * Pure, runtime-agnostic: map the optional release-attribution options to OTel
+ * resource attributes — `version` → `service.version`, `build` → `service.build`.
+ *
+ * Only non-empty values are included: the console's release queries filter
+ * `!= ''`, so emitting an empty attribute is pure noise. Depends on nothing but
+ * the pure `@opentelemetry/semantic-conventions` constant, so it is safe for
+ * every entry including the WinterCG-only `/workers` path.
+ */
+export function releaseResourceAttributes(o) {
+    const attrs = {};
+    const version = o.version?.trim();
+    const build = o.build?.trim();
+    if (version)
+        attrs[ATTR_SERVICE_VERSION] = version;
+    if (build)
+        attrs[ATTR_SERVICE_BUILD] = build;
+    return attrs;
+}
 /** Pure: derive the OTLP/HTTP traces URL + auth header. Works in any runtime. */
 export function buildExporterConfig(o) {
     const base = (o.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");

package/dist/next.js

@@ -56,7 +56,14 @@ export async function registerHeystack(o) {
         // "./workers" → "./dist/workers.js" and "./node" → "./dist/node.js".
         const { initHeystackWorkers } = await import(
         /* @vite-ignore */ /* webpackIgnore: true */ "@heystack/otel/workers");
-        initHeystackWorkers({ apiKey, service: o.service, endpoint: o.endpoint });
+        initHeystackWorkers({
+            apiKey,
+            service: o.service,
+            endpoint: o.endpoint,
+            // Release/commit attribution — carried into the workerd resource.
+            version: o.version,
+            build: o.build,
+        });
     }
     else {
         const { initHeystack } = await import(
@@ -65,6 +72,9 @@ export async function registerHeystack(o) {
             apiKey,
             service: o.service,
             endpoint: o.endpoint,
+            // Release/commit attribution — carried into the NodeSDK resource.
+            version: o.version,
+            build: o.build,
             debug: o.debug,
         });
     }

package/dist/node.d.ts

@@ -52,6 +52,18 @@ export declare class SelfSpanFilteringExporter implements SpanExporter {
     shutdown(): Promise<void>;
     forceFlush(): Promise<void>;
 }
+/**
+ * Resolve the release-attribution resource attributes for the Node entry.
+ *
+ * Prefers the explicit `version`/`build` options, then falls back to environment
+ * variables — `HEYSTACK_SERVICE_VERSION` (or `OTEL_SERVICE_VERSION`) for the
+ * release, `HEYSTACK_SERVICE_BUILD` for the commit SHA — so a deploy can stamp
+ * the release/commit without touching code (e.g. `HEYSTACK_SERVICE_BUILD=$(git
+ * rev-parse HEAD)`). Node-only: `process` is read behind a `typeof` guard so the
+ * function never references an undefined global. Returns only the keys that
+ * resolved to a non-empty value (empty attributes are noise the console filters).
+ */
+export declare function resolveNodeReleaseAttributes(o: NodeOptions): Record<string, string>;
 /** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
 export declare function initHeystack(o: NodeOptions): NodeSDK;
 /** Flush + shutdown the SDK on SIGTERM/SIGINT so short-lived processes don't lose the last batch. Registers handlers at most once. */

package/dist/node.js

@@ -3,7 +3,8 @@ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { ExportResultCode } from "@opentelemetry/core";
-import { buildExporterConfig } from "./core.js";
+import { Resource } from "@opentelemetry/resources";
+import { buildExporterConfig, releaseResourceAttributes, } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 /**
  * Wraps a span exporter and drops any span that targets the Heystack ingest
@@ -88,6 +89,23 @@ let _signalHandlersRegistered = false;
  * handlers).
  */
 let _sdk = null;
+/**
+ * Resolve the release-attribution resource attributes for the Node entry.
+ *
+ * Prefers the explicit `version`/`build` options, then falls back to environment
+ * variables — `HEYSTACK_SERVICE_VERSION` (or `OTEL_SERVICE_VERSION`) for the
+ * release, `HEYSTACK_SERVICE_BUILD` for the commit SHA — so a deploy can stamp
+ * the release/commit without touching code (e.g. `HEYSTACK_SERVICE_BUILD=$(git
+ * rev-parse HEAD)`). Node-only: `process` is read behind a `typeof` guard so the
+ * function never references an undefined global. Returns only the keys that
+ * resolved to a non-empty value (empty attributes are noise the console filters).
+ */
+export function resolveNodeReleaseAttributes(o) {
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    const version = o.version ?? env?.HEYSTACK_SERVICE_VERSION ?? env?.OTEL_SERVICE_VERSION;
+    const build = o.build ?? env?.HEYSTACK_SERVICE_BUILD;
+    return releaseResourceAttributes({ version, build });
+}
 /** Initialise Heystack tracing on a Node runtime. Call once, as early as possible. Returns the started SDK. */
 export function initHeystack(o) {
     // Idempotent: a second call returns the cached SDK rather than starting a new
@@ -111,6 +129,10 @@ export function initHeystack(o) {
     const traceExporter = new SelfSpanFilteringExporter(new OTLPTraceExporter({ url: cfg.url, headers: cfg.headers }), ingestHost);
     const sdk = new NodeSDK({
         serviceName: o.service,
+        // Release/commit attribution. NodeSDK merges `serviceName` on top of this
+        // resource, so the final resource carries service.name + (when provided)
+        // service.version + service.build. Empty when neither option nor env is set.
+        resource: new Resource(resolveNodeReleaseAttributes(o)),
         traceExporter,
         instrumentations,
     });

package/dist/web.d.ts

@@ -58,6 +58,20 @@ export interface InstrumentWebOptions {
     apiKey: string;
     service: string;
     endpoint?: string;
+    /**
+     * Release identifier for this build — the same `service.version` concept as the
+     * server entries (see `HeystackOptions.version`). Stamped as `service.version` on
+     * the resource of every browser error/console log exported here, so a browser
+     * regression is attributed to the release that introduced it (release health /
+     * suspect release in the console).
+     */
+    version?: string;
+    /**
+     * Commit SHA for this build — the same `service.build` concept as the server
+     * entries (see `HeystackOptions.build`). Stamped as `service.build` on the
+     * resource of exported browser logs for commit-level attribution.
+     */
+    build?: string;
     /** Optional app-supplied user identifier stamped on the session. */
     userId?: string;
     /** Local overrides; by default sampling + masking come from server config. */
@@ -65,11 +79,35 @@ export interface InstrumentWebOptions {
     flushIntervalMs?: number;
     /** Max buffered events before an early flush. */
     flushEveryEvents?: number;
+    /**
+     * Opt in to browser distributed tracing: emit a real CLIENT span per outbound
+     * fetch and propagate W3C trace context, so browser→backend calls show as one
+     * connected trace (and a service-map edge). Off by default — it adds span
+     * volume (backend cost). Independent of session replay.
+     */
+    tracing?: boolean;
+    /** Head sample rate for browser tracing (0–1, default 1 when `tracing` is on).
+     *  Lower it to control span volume/cost on high-traffic apps. */
+    traceSampleRate?: number;
+    /**
+     * Capture uncaught browser errors (`window.onerror` + `unhandledrejection`) and
+     * export them as OTLP logs (`event.name=browser.error`, ERROR severity, with
+     * `exception.*` semconv attributes). **On by default** when `instrumentWeb` is
+     * called; set `false` to disable. Independent of replay and tracing — errors
+     * correlate to replays via `session_id` and to traces via the active span.
+     */
+    errors?: boolean;
+    /**
+     * Capture `console` output as logs. `'error'` (default) captures `console.error`;
+     * `'warn'` captures `console.warn` **and** `console.error`; `false` disables it.
+     * Rate-capped and recursion-guarded so it can never feed a self-export loop.
+     */
+    captureConsole?: "error" | "warn" | false;
 }
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export declare function instrumentWeb(opts: InstrumentWebOptions): Promise<() => void>;
-export declare function makeTraceparent(traceId: string, spanId: string): string;
+export declare function makeTraceparent(traceId: string, spanId: string, sampled?: boolean): string;
 /** Collects trace ids observed during a session (deduped, capped). */
 export declare class TraceIdCollector {
     private readonly cap;
@@ -78,7 +116,201 @@ export declare class TraceIdCollector {
     add(id: string): void;
     drain(): string[];
 }
+/** Holds the most recent browser CLIENT span context so an error captured during
+ *  (or right after) a fetch can be tagged with that trace/span id. There is no
+ *  ambient active-span stack in the browser SDK — spans are per-fetch — so this is
+ *  a best-effort "last span" correlation, only populated when tracing is on. */
+export declare class ActiveTraceRef {
+    private cur?;
+    set(traceId: string, spanId: string): void;
+    get(): {
+        traceId: string;
+        spanId: string;
+    } | undefined;
+}
 /** Patch window.fetch to inject traceparent on outgoing calls and record the
  *  trace id for correlation. Returns an unpatch function. */
 export declare function patchFetchForCorrelation(collector: TraceIdCollector): () => void;
+/** One recorded browser CLIENT span (an outbound fetch). */
+export interface BrowserClientSpan {
+    traceId: string;
+    spanId: string;
+    name: string;
+    startMs: number;
+    endMs: number;
+    method: string;
+    url: string;
+    /** HTTP response status; 0 for a network error / throw. */
+    statusCode: number;
+    error: boolean;
+}
+/** Build an OTLP/JSON ExportTraceServiceRequest for a batch of client spans. */
+export declare function buildTraceExport(service: string, spans: BrowserClientSpan[], resourceAttributes?: Record<string, string>): Record<string, unknown>;
+export interface TraceExporterOpts {
+    endpoint: string;
+    apiKey: string;
+    service: string;
+    /** MUST be the ORIGINAL fetch captured before patching, or the export POST
+     *  self-traces and loops (cost guardrail #1). */
+    fetchImpl: typeof fetch;
+    /** `service.version` / `service.build` — stamped on the resource for attribution. */
+    resourceAttributes?: Record<string, string>;
+    maxBatch?: number;
+}
+/** Buffers browser CLIENT spans and POSTs them as OTLP/JSON to /v1/traces. */
+export declare class BrowserTraceExporter {
+    private readonly o;
+    private buf;
+    constructor(o: TraceExporterOpts);
+    add(span: BrowserClientSpan): void;
+    flush(keepalive?: boolean): Promise<void>;
+}
+export interface TracingPatchOpts {
+    onSpan: (s: BrowserClientSpan) => void;
+    sampleRate: number;
+    /** Bare ingest hostname; calls to it are never traced (self-export loop guard). */
+    ingestHost: string;
+    /** Optional: also record the real trace id for replay↔trace correlation. */
+    collector?: TraceIdCollector;
+    /** Optional: publish the current span context so captured errors can reference it. */
+    activeTrace?: ActiveTraceRef;
+    rng?: () => number;
+}
+/** Patch window.fetch to emit a real CLIENT span per outbound call, inject that
+ *  span's W3C traceparent, and (head-sampled) hand the finished span to onSpan.
+ *  Returns an unpatch function. */
+export declare function patchFetchForTracing(o: TracingPatchOpts): () => void;
+/** A browser log record before OTLP encoding. */
+export interface BrowserLogRecord {
+    /** Client epoch millis. */
+    timeUnixMs: number;
+    severityText: "ERROR" | "WARN" | "INFO";
+    body: string;
+    attributes: Record<string, string>;
+    traceId?: string;
+    spanId?: string;
+}
+/** Build an OTLP/JSON ExportLogsServiceRequest for a batch of browser logs. */
+export declare function buildLogsExport(service: string, records: BrowserLogRecord[], resourceAttributes?: Record<string, string>): Record<string, unknown>;
+export interface LogsExporterOpts {
+    endpoint: string;
+    apiKey: string;
+    service: string;
+    /** MUST be the ORIGINAL fetch captured before patching, or the export POST
+     *  self-traces and loops (cost guardrail #1). */
+    fetchImpl: typeof fetch;
+    /** `service.version` / `service.build` (from `version`/`build`) — stamped on the resource. */
+    resourceAttributes?: Record<string, string>;
+    maxBatch?: number;
+}
+/** Buffers browser logs and POSTs them as OTLP/JSON to /v1/logs. */
+export declare class BrowserLogsExporter {
+    private readonly o;
+    private buf;
+    constructor(o: LogsExporterOpts);
+    add(r: BrowserLogRecord): void;
+    flush(keepalive?: boolean): Promise<void>;
+}
+/** Sliding-window rate gate: allow up to `cap` records per `windowMs`; count drops
+ *  and report how many were dropped the moment a new window opens, so the caller
+ *  can emit one summary record when the cap lifts. */
+export declare class RateGate {
+    private readonly cap;
+    private readonly windowMs;
+    private readonly now;
+    private count;
+    private windowStart;
+    private dropped;
+    constructor(cap: number, windowMs: number, now?: () => number);
+    take(): {
+        allow: boolean;
+        recovered: number;
+    };
+}
+/** One recently-captured browser error, kept cheap on purpose (message + type +
+ *  timestamp only, no stack) so a bug report can attach the last N without holding
+ *  large objects. Populated by startErrorCapture and read by reportBug(). */
+export interface RecentError {
+    message: string;
+    type?: string;
+    /** Client epoch millis when the error was captured. */
+    timestamp: number;
+}
+/** Fixed-capacity ring of the most recent captured errors. Push is O(1); once the
+ *  cap is reached the oldest entry is dropped. `list()` returns oldest→newest. */
+export declare class RecentErrorsBuffer {
+    private readonly cap;
+    private buf;
+    constructor(cap?: number);
+    push(e: RecentError): void;
+    list(): RecentError[];
+}
+export interface ErrorCaptureOpts {
+    exporter: BrowserLogsExporter;
+    /** Correlates logs to the replay session and to each other. */
+    sessionId: string;
+    /** `'error'` = console.error; `'warn'` = warn + error; `false` = no console capture. */
+    captureConsole: "error" | "warn" | false;
+    activeTrace?: ActiveTraceRef;
+    /** Optional ring the capture path records each uncaught error into (message +
+     *  type + timestamp), so reportBug() can attach recent errors as context. */
+    recent?: RecentErrorsBuffer;
+    now?: () => number;
+    /** Max records per window before dropping (default 60). */
+    rateCap?: number;
+    /** Rate window in ms (default 60_000). */
+    rateWindowMs?: number;
+}
+/** Wire up `window.onerror` / `unhandledrejection` (+ optional console) capture.
+ *  Returns an unpatch function. Recursion-guarded (anything logged on our own
+ *  export path is never re-captured) and rate-capped. */
+export declare function startErrorCapture(o: ErrorCaptureOpts): () => void;
+/** The user-supplied part of a bug report. `message` is required; everything else
+ *  the SDK attaches automatically. `context` is arbitrary app metadata (plan,
+ *  feature flag, screen…) stored verbatim. */
+export interface BugReport {
+    message: string;
+    /** Optional reporter email so the team can follow up. */
+    email?: string;
+    /** Arbitrary string metadata the app wants to attach (values are stored as-is). */
+    context?: Record<string, string>;
+}
+/** The session context reportBug() draws on, registered by instrumentWeb() and
+ *  cleared on stop(). Kept separate from InstrumentWebOptions so the module-level
+ *  reportBug() has everything it needs without re-reading config. */
+export interface BugReportSession {
+    endpoint: string;
+    apiKey: string;
+    service: string;
+    /** Shared with browser errors / console logs / replay — the correlation key. */
+    sessionId: string;
+    /** ORIGINAL fetch captured before patching (self-export-loop guard). */
+    fetchImpl: typeof fetch;
+    /** Last browser CLIENT span, so a report references the in-flight trace. */
+    activeTrace: ActiveTraceRef;
+    /** Ring of recent captured errors attached as report context. */
+    recentErrors: RecentErrorsBuffer;
+    /** Emits the user.bug_report OTLP log so the report shows in the timeline. */
+    logsExporter: BrowserLogsExporter;
+    version?: string;
+    build?: string;
+}
+/** Internal: instrumentWeb() registers the active session here (and clears it with
+ *  `null` on stop) so the module-level reportBug() works after instrumentWeb() is
+ *  called. Exported for that wiring + tests; not part of the app-facing surface. */
+export declare function registerBugSession(session: BugReportSession | null): void;
+/** Build the /v1/bug-reports POST body: the user's fields plus the auto-attached
+ *  session/trace/release context and recent errors. Pure (env reads are guarded)
+ *  so it is unit-testable. */
+export declare function buildBugReportPayload(s: BugReportSession, report: BugReport): Record<string, unknown>;
+/**
+ * File an in-app bug report. Call after instrumentWeb() — it throws if the SDK
+ * isn't initialised or the message is empty (both are programmer errors). Network
+ * failures are swallowed (a failed report must never break the host app).
+ *
+ * @example
+ * import { reportBug } from "@heystack/otel/web";
+ * button.onclick = () => reportBug({ message: input.value, email: userEmail });
+ */
+export declare function reportBug(report: BugReport): Promise<void>;
 export {};

package/dist/web.js

@@ -1,4 +1,8 @@
-import { DEFAULT_ENDPOINT } from "./core.js";
+import { DEFAULT_ENDPOINT, releaseResourceAttributes } from "./core.js";
+// safeHostname is pure string logic (no runtime imports) — safe in the browser
+// bundle. Used to skip tracing our OWN telemetry POSTs (the self-export loop that
+// caused the June 2026 cost incident); see CLAUDE.md → "Cost guardrails".
+import { safeHostname } from "./self-span.js";
 /** Pure: decide once per session whether to record. rng defaults to Math.random. */
 export function shouldRecord(cfg, rng = Math.random) {
     if (!cfg.enabled)
@@ -93,10 +97,90 @@ export async function instrumentWeb(opts) {
     catch { /* offline / blocked - fall back to disabled */ }
     if (opts.sampleRate !== undefined)
         cfg = { ...cfg, sample_rate: opts.sampleRate };
-    // 2. Session-level sampling decision.
+    // Capture the ORIGINAL fetch before any patching — telemetry exporters MUST use
+    // it so their own POSTs to the ingest endpoint aren't traced/looped (guardrail #1).
+    const originalFetch = fetch.bind(globalThis);
+    const ingestHost = safeHostname(endpoint);
+    const traces = new TraceIdCollector();
+    const activeTrace = new ActiveTraceRef();
+    // One session id for the whole run — shared by errors, console logs AND replay
+    // (created here, before the replay sampling gate, so errors correlate even when
+    // replay isn't sampled; when it is, they share this id → error ↔ replay linking).
+    const sessionId = crypto.randomUUID();
+    // service.version / service.build for release attribution on exported browser logs.
+    const releaseAttrs = releaseResourceAttributes({ version: opts.version, build: opts.build });
+    // 2. Browser distributed tracing (opt-in) — INDEPENDENT of replay sampling. Emits
+    //    a real CLIENT span per outbound fetch + propagates W3C context to the backend.
+    let stopTracing = () => { };
+    let fetchPatched = false;
+    if (opts.tracing) {
+        const exporter = new BrowserTraceExporter({
+            endpoint, apiKey: opts.apiKey, service: opts.service, fetchImpl: originalFetch,
+            resourceAttributes: releaseAttrs,
+        });
+        const unpatchTrace = patchFetchForTracing({
+            onSpan: (s) => exporter.add(s),
+            sampleRate: opts.traceSampleRate ?? 1,
+            ingestHost,
+            collector: traces, // real trace ids also tag the replay session (better correlation)
+            activeTrace, // so a captured error can reference the in-flight span
+        });
+        fetchPatched = true;
+        const traceFlush = setInterval(() => void exporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
+        const onHideTrace = () => { if (document.visibilityState === "hidden")
+            void exporter.flush(true); };
+        document.addEventListener("visibilitychange", onHideTrace);
+        window.addEventListener("pagehide", () => void exporter.flush(true));
+        stopTracing = () => {
+            clearInterval(traceFlush);
+            document.removeEventListener("visibilitychange", onHideTrace);
+            unpatchTrace();
+            void exporter.flush(true);
+        };
+    }
+    // The logs exporter + recent-errors ring are shared by error capture AND the
+    // in-app bug reporter, so they're constructed here (before the errors gate) and
+    // always available to reportBug() even when error capture is disabled. The
+    // exporter is inert until something is added, so constructing it eagerly is free.
+    const logsExporter = new BrowserLogsExporter({
+        endpoint, apiKey: opts.apiKey, service: opts.service, fetchImpl: originalFetch,
+        resourceAttributes: releaseAttrs,
+    });
+    const recentErrors = new RecentErrorsBuffer(20);
+    // Register the session so the module-level reportBug() works after this call.
+    registerBugSession({
+        endpoint, apiKey: opts.apiKey, service: opts.service, sessionId,
+        fetchImpl: originalFetch, activeTrace, recentErrors, logsExporter,
+        version: opts.version, build: opts.build,
+    });
+    // 2b. Browser error / console log collection — ON by default, INDEPENDENT of both
+    //     tracing and replay sampling. Exports OTLP logs to /v1/logs via the original fetch.
+    let stopErrors = () => { };
+    if (opts.errors !== false) {
+        const unpatchErrors = startErrorCapture({
+            exporter: logsExporter,
+            sessionId,
+            captureConsole: opts.captureConsole ?? "error",
+            activeTrace,
+            recent: recentErrors,
+        });
+        const logFlush = setInterval(() => void logsExporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
+        const onHideLogs = () => { if (document.visibilityState === "hidden")
+            void logsExporter.flush(true); };
+        const onPageHideLogs = () => void logsExporter.flush(true);
+        document.addEventListener("visibilitychange", onHideLogs);
+        window.addEventListener("pagehide", onPageHideLogs);
+        stopErrors = () => {
+            clearInterval(logFlush);
+            document.removeEventListener("visibilitychange", onHideLogs);
+            window.removeEventListener("pagehide", onPageHideLogs);
+            unpatchErrors();
+            void logsExporter.flush(true);
+        };
+    }
+    // 3. Session replay — gated on the replay sampling decision (independent of tracing/errors).
     if (!shouldRecord(cfg))
-        return () => { };
-    // 3. Start the recorder.
+        return () => { stopTracing(); stopErrors(); registerBugSession(null); };
     const { record } = await import("rrweb");
     // An element marked `data-hs-unmask` (or any descendant of one) is recorded in
     // cleartext; everything else is masked. rrweb 2.0.1's real opt-out hooks are
@@ -108,13 +192,11 @@ export async function instrumentWeb(opts) {
     const reveal = (text, element) => !!element?.closest?.("[data-hs-unmask]");
     const maskInputFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
     const maskTextFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
-    const sessionId = crypto.randomUUID();
-    const transport = new ReplayTransport({ endpoint, apiKey: opts.apiKey, sessionId });
-    // Install the fetch patch AFTER the transport is constructed so the recorder's
-    // own upload POSTs (which captured the original fetch at construction time via
-    // fetch.bind(globalThis)) are not self-traced.
-    const traces = new TraceIdCollector();
-    const unpatch = patchFetchForCorrelation(traces);
+    const transport = new ReplayTransport({ endpoint, apiKey: opts.apiKey, fetchImpl: originalFetch, sessionId });
+    // Only patch fetch for replay correlation if tracing didn't already patch it
+    // (tracing's patch injects real context AND feeds `traces`). Avoids double-wrapping
+    // window.fetch. Uses the original fetch for uploads (self-span suppression).
+    const unpatch = fetchPatched ? () => { } : patchFetchForCorrelation(traces);
     let buffer = [];
     let errorCount = 0;
     const browser = navigator.userAgent;
@@ -135,11 +217,19 @@ export async function instrumentWeb(opts) {
         }, keepalive);
     };
     const stopRecord = record({
-        emit(event) {
+        emit(event, isCheckout) {
+            // rrweb re-checkpoints (takes a fresh FULL_SNAPSHOT) every `checkoutEveryNms`.
+            // Flush the buffer BEFORE appending the checkout event so each keyframe starts
+            // a new chunk (has_snapshot=true) — the player can then begin playback from the
+            // nearest keyframe ≤ a target time instead of loading the whole session.
+            if (isCheckout)
+                flush();
             buffer.push(event);
             if (buffer.length >= (opts.flushEveryEvents ?? DEFAULT_FLUSH_EVENTS))
                 flush();
         },
+        // A ~60s keyframe cadence bounds how many chunks the player must fetch to seek.
+        checkoutEveryNms: 60_000,
         maskAllInputs: cfg.masking_mode === "strict",
         maskTextSelector: "[data-hs-mask]",
         blockSelector: "[data-hs-block]",
@@ -159,6 +249,9 @@ export async function instrumentWeb(opts) {
         stopRecord?.();
         unpatch();
         flush(true);
+        stopTracing();
+        stopErrors();
+        registerBugSession(null);
     };
 }
 function matchMediaDevice() {
@@ -171,8 +264,11 @@ function randHex(bytes) {
     crypto.getRandomValues(a);
     return Array.from(a, (b) => b.toString(16).padStart(2, "0")).join("");
 }
-export function makeTraceparent(traceId, spanId) {
-    return `00-${traceId}-${spanId}-01`;
+export function makeTraceparent(traceId, spanId, sampled = true) {
+    // The trace-flags byte's low bit is "sampled". When head sampling drops a
+    // request we still inject the context (00) so the downstream service makes the
+    // SAME keep/drop decision — coordinated sampling, no orphaned server spans.
+    return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
 }
 /** Collects trace ids observed during a session (deduped, capped). */
 export class TraceIdCollector {
@@ -192,6 +288,15 @@ export class TraceIdCollector {
         return out;
     }
 }
+/** Holds the most recent browser CLIENT span context so an error captured during
+ *  (or right after) a fetch can be tagged with that trace/span id. There is no
+ *  ambient active-span stack in the browser SDK — spans are per-fetch — so this is
+ *  a best-effort "last span" correlation, only populated when tracing is on. */
+export class ActiveTraceRef {
+    cur;
+    set(traceId, spanId) { this.cur = { traceId, spanId }; }
+    get() { return this.cur; }
+}
 /** Patch window.fetch to inject traceparent on outgoing calls and record the
  *  trace id for correlation. Returns an unpatch function. */
 export function patchFetchForCorrelation(collector) {
@@ -209,3 +314,445 @@ export function patchFetchForCorrelation(collector) {
     });
     return () => { window.fetch = orig; };
 }
+const kvStr = (key, value) => ({ key, value: { stringValue: value } });
+const kvInt = (key, n) => ({ key, value: { intValue: String(n) } });
+const msToNano = (ms) => `${Math.trunc(ms)}000000`;
+function spanToOtlp(s) {
+    const attributes = [
+        kvStr("http.request.method", s.method),
+        kvStr("url.full", s.url),
+        kvStr("server.address", safeHostname(s.url)),
+    ];
+    if (s.statusCode > 0)
+        attributes.push(kvInt("http.response.status_code", s.statusCode));
+    return {
+        traceId: s.traceId,
+        spanId: s.spanId,
+        name: s.name,
+        kind: 3, // SPAN_KIND CLIENT
+        startTimeUnixNano: msToNano(s.startMs),
+        endTimeUnixNano: msToNano(s.endMs),
+        attributes,
+        status: { code: s.error ? 2 : 1 }, // STATUS_CODE ERROR : OK
+    };
+}
+/** Build an OTLP/JSON ExportTraceServiceRequest for a batch of client spans. */
+export function buildTraceExport(service, spans, resourceAttributes = {}) {
+    const resAttrs = [
+        kvStr("service.name", service),
+        ...Object.entries(resourceAttributes).map(([k, v]) => kvStr(k, v)),
+    ];
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: resAttrs },
+                scopeSpans: [{ scope: { name: "@heystack/otel/web" }, spans: spans.map(spanToOtlp) }],
+            },
+        ],
+    };
+}
+/** Buffers browser CLIENT spans and POSTs them as OTLP/JSON to /v1/traces. */
+export class BrowserTraceExporter {
+    o;
+    buf = [];
+    constructor(o) {
+        this.o = o;
+    }
+    add(span) {
+        this.buf.push(span);
+        if (this.buf.length >= (this.o.maxBatch ?? 50))
+            void this.flush();
+    }
+    async flush(keepalive = false) {
+        if (this.buf.length === 0)
+            return;
+        const spans = this.buf;
+        this.buf = [];
+        const body = JSON.stringify(buildTraceExport(this.o.service, spans, this.o.resourceAttributes));
+        await this.o
+            .fetchImpl(`${this.o.endpoint}/v1/traces`, {
+            method: "POST",
+            keepalive,
+            headers: { authorization: `Bearer ${this.o.apiKey}`, "content-type": "application/json" },
+            body,
+        })
+            .catch(() => { });
+    }
+}
+function fetchUrl(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    return input.url ?? "";
+}
+function fetchMethod(input, init) {
+    const m = init?.method ?? (input instanceof Request ? input.method : undefined) ?? "GET";
+    return m.toUpperCase();
+}
+function pathOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** Patch window.fetch to emit a real CLIENT span per outbound call, inject that
+ *  span's W3C traceparent, and (head-sampled) hand the finished span to onSpan.
+ *  Returns an unpatch function. */
+export function patchFetchForTracing(o) {
+    if (typeof window === "undefined" || !window.fetch)
+        return () => { };
+    const orig = window.fetch.bind(window);
+    const rng = o.rng ?? Math.random;
+    window.fetch = ((input, init) => {
+        const url = fetchUrl(input);
+        // Never trace our own telemetry POSTs (trace export, replay upload, config) —
+        // they'd create spans that export → re-trace → loop. The exporter already uses
+        // the original fetch; this is the belt-and-suspenders host-match guard.
+        if (o.ingestHost && safeHostname(url) === o.ingestHost)
+            return orig(input, init);
+        const sampled = rng() < o.sampleRate;
+        const traceId = randHex(16);
+        const spanId = randHex(8);
+        if (sampled && o.collector)
+            o.collector.add(traceId);
+        if (sampled)
+            o.activeTrace?.set(traceId, spanId);
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        if (!headers.has("traceparent"))
+            headers.set("traceparent", makeTraceparent(traceId, spanId, sampled));
+        const method = fetchMethod(input, init);
+        const startMs = Date.now();
+        const emit = (statusCode, error) => {
+            if (!sampled)
+                return;
+            o.onSpan({ traceId, spanId, name: `${method} ${pathOf(url)}`, startMs, endMs: Date.now(), method, url, statusCode, error });
+        };
+        return orig(input, { ...init, headers }).then((res) => { emit(res.status, res.status >= 400); return res; }, (err) => { emit(0, true); throw err; });
+    });
+    return () => { window.fetch = orig; };
+}
+// ── Browser error / console log collection ──────────────────────────────────
+// Uncaught errors + (opt) console output become OTLP logs POSTed to /v1/logs.
+// No official OTel browser *logs* SDK exists, so we write the thin exporter here
+// and keep the OSS wire format (OTLP/JSON LogsRequest, matching what /v1/logs and
+// schema's logsToRows parse). Same cost guardrail as traces/replay: the exporter
+// MUST be handed the ORIGINAL fetch (captured before patching) so its own POST is
+// never traced → re-exported → looped.
+/** OTel severity numbers for the levels we emit (see OTLP LogRecord spec).
+ *  INFO is used by non-error events such as a user bug report. */
+const SEVERITY_NUMBER = { ERROR: 17, WARN: 13, INFO: 9 };
+/** Max characters of a log body we keep (console args / messages can be huge). */
+const MAX_LOG_BODY = 4096;
+function logToOtlp(r) {
+    const rec = {
+        timeUnixNano: msToNano(r.timeUnixMs),
+        severityText: r.severityText,
+        severityNumber: SEVERITY_NUMBER[r.severityText],
+        body: { stringValue: r.body },
+        attributes: Object.entries(r.attributes).map(([k, v]) => kvStr(k, v)),
+    };
+    if (r.traceId)
+        rec.traceId = r.traceId;
+    if (r.spanId)
+        rec.spanId = r.spanId;
+    return rec;
+}
+/** Build an OTLP/JSON ExportLogsServiceRequest for a batch of browser logs. */
+export function buildLogsExport(service, records, resourceAttributes = {}) {
+    const resAttrs = [
+        kvStr("service.name", service),
+        ...Object.entries(resourceAttributes).map(([k, v]) => kvStr(k, v)),
+    ];
+    return {
+        resourceLogs: [
+            {
+                resource: { attributes: resAttrs },
+                scopeLogs: [{ scope: { name: "@heystack/otel/web" }, logRecords: records.map(logToOtlp) }],
+            },
+        ],
+    };
+}
+/** Buffers browser logs and POSTs them as OTLP/JSON to /v1/logs. */
+export class BrowserLogsExporter {
+    o;
+    buf = [];
+    constructor(o) {
+        this.o = o;
+    }
+    add(r) {
+        this.buf.push(r);
+        if (this.buf.length >= (this.o.maxBatch ?? 50))
+            void this.flush();
+    }
+    async flush(keepalive = false) {
+        if (this.buf.length === 0)
+            return;
+        const records = this.buf;
+        this.buf = [];
+        const body = JSON.stringify(buildLogsExport(this.o.service, records, this.o.resourceAttributes));
+        await this.o
+            .fetchImpl(`${this.o.endpoint}/v1/logs`, {
+            method: "POST",
+            keepalive,
+            headers: { authorization: `Bearer ${this.o.apiKey}`, "content-type": "application/json" },
+            body,
+        })
+            .catch(() => { });
+    }
+}
+/** Sliding-window rate gate: allow up to `cap` records per `windowMs`; count drops
+ *  and report how many were dropped the moment a new window opens, so the caller
+ *  can emit one summary record when the cap lifts. */
+export class RateGate {
+    cap;
+    windowMs;
+    now;
+    count = 0;
+    windowStart = Number.NEGATIVE_INFINITY;
+    dropped = 0;
+    constructor(cap, windowMs, now = Date.now) {
+        this.cap = cap;
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    take() {
+        const t = this.now();
+        let recovered = 0;
+        if (t - this.windowStart >= this.windowMs) {
+            recovered = this.dropped;
+            this.dropped = 0;
+            this.count = 0;
+            this.windowStart = t;
+        }
+        if (this.count >= this.cap) {
+            this.dropped++;
+            return { allow: false, recovered };
+        }
+        this.count++;
+        return { allow: true, recovered };
+    }
+}
+/** Best-effort stringify of a console arg: strings pass through; Errors keep their
+ *  stack; objects are JSON'd (circular refs degrade to their tag). */
+function stringifyArg(a) {
+    if (typeof a === "string")
+        return a;
+    if (a instanceof Error)
+        return a.stack ?? `${a.name}: ${a.message}`;
+    try {
+        return JSON.stringify(a) ?? String(a);
+    }
+    catch {
+        return Object.prototype.toString.call(a);
+    }
+}
+/** Fixed-capacity ring of the most recent captured errors. Push is O(1); once the
+ *  cap is reached the oldest entry is dropped. `list()` returns oldest→newest. */
+export class RecentErrorsBuffer {
+    cap;
+    buf = [];
+    constructor(cap = 20) {
+        this.cap = cap;
+    }
+    push(e) {
+        this.buf.push(e);
+        if (this.buf.length > this.cap)
+            this.buf.shift();
+    }
+    list() {
+        return [...this.buf];
+    }
+}
+/** Wire up `window.onerror` / `unhandledrejection` (+ optional console) capture.
+ *  Returns an unpatch function. Recursion-guarded (anything logged on our own
+ *  export path is never re-captured) and rate-capped. */
+export function startErrorCapture(o) {
+    if (typeof window === "undefined")
+        return () => { };
+    const now = o.now ?? Date.now;
+    const gate = new RateGate(o.rateCap ?? 60, o.rateWindowMs ?? 60_000, now);
+    // Re-entrancy flag: if capturing a record ends up invoking a patched console
+    // (or any path that re-enters here), we drop the nested call — this is what
+    // stops a console.error emitted while building/exporting a record from looping.
+    let inCapture = false;
+    const push = (rec) => {
+        const { allow, recovered } = gate.take();
+        if (recovered > 0) {
+            o.exporter.add({
+                timeUnixMs: now(),
+                severityText: "WARN",
+                body: `${recovered} browser log record(s) dropped (rate cap)`,
+                attributes: { "event.name": "heystack.rate_limited", session_id: o.sessionId },
+            });
+        }
+        if (!allow)
+            return;
+        o.exporter.add(rec);
+    };
+    const emitError = (e) => {
+        if (inCapture)
+            return;
+        inCapture = true;
+        try {
+            // Record into the recent-errors ring (cheap: message + type + timestamp) so
+            // a later reportBug() can attach it. Done before the rate gate so a captured
+            // error is always available as bug context even when log export is throttled.
+            o.recent?.push({ message: e.message, type: e.type, timestamp: now() });
+            const attrs = {
+                "event.name": "browser.error",
+                "url.full": location.href,
+                session_id: o.sessionId,
+                "exception.message": e.message,
+            };
+            if (e.type)
+                attrs["exception.type"] = e.type;
+            if (e.stack)
+                attrs["exception.stacktrace"] = e.stack;
+            const active = o.activeTrace?.get();
+            push({
+                timeUnixMs: now(),
+                severityText: "ERROR",
+                body: e.message,
+                attributes: attrs,
+                traceId: active?.traceId,
+                spanId: active?.spanId,
+            });
+        }
+        finally {
+            inCapture = false;
+        }
+    };
+    const onError = (ev) => {
+        const err = ev.error;
+        emitError({
+            message: ev.message || err?.message || "Error",
+            type: err?.name,
+            stack: err?.stack,
+        });
+    };
+    const onRejection = (ev) => {
+        const reason = ev.reason;
+        const isErr = reason instanceof Error;
+        emitError({
+            message: isErr ? reason.message : String(reason),
+            type: isErr ? reason.name : "UnhandledRejection",
+            stack: isErr ? reason.stack : undefined,
+        });
+    };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    // Console capture (optional) — patches console methods, always calling the
+    // ORIGINAL first so host behaviour is unchanged.
+    const levels = o.captureConsole === "warn" ? ["warn", "error"] : o.captureConsole === "error" ? ["error"] : [];
+    const originals = {};
+    for (const level of levels) {
+        const orig = console[level];
+        originals[level] = orig;
+        console[level] = ((...args) => {
+            orig.apply(console, args);
+            if (inCapture)
+                return;
+            inCapture = true;
+            try {
+                const body = args.map(stringifyArg).join(" ").slice(0, MAX_LOG_BODY);
+                const active = o.activeTrace?.get();
+                push({
+                    timeUnixMs: now(),
+                    severityText: level === "error" ? "ERROR" : "WARN",
+                    body,
+                    attributes: {
+                        "event.name": "browser.console",
+                        "console.level": level,
+                        "url.full": location.href,
+                        session_id: o.sessionId,
+                    },
+                    traceId: active?.traceId,
+                    spanId: active?.spanId,
+                });
+            }
+            finally {
+                inCapture = false;
+            }
+        });
+    }
+    return () => {
+        window.removeEventListener("error", onError);
+        window.removeEventListener("unhandledrejection", onRejection);
+        for (const level of levels) {
+            const orig = originals[level];
+            if (orig)
+                console[level] = orig;
+        }
+    };
+}
+let activeBugSession = null;
+/** Internal: instrumentWeb() registers the active session here (and clears it with
+ *  `null` on stop) so the module-level reportBug() works after instrumentWeb() is
+ *  called. Exported for that wiring + tests; not part of the app-facing surface. */
+export function registerBugSession(session) {
+    activeBugSession = session;
+}
+/** Build the /v1/bug-reports POST body: the user's fields plus the auto-attached
+ *  session/trace/release context and recent errors. Pure (env reads are guarded)
+ *  so it is unit-testable. */
+export function buildBugReportPayload(s, report) {
+    const active = s.activeTrace.get();
+    return {
+        message: report.message,
+        email: report.email,
+        context: report.context,
+        url: typeof location !== "undefined" ? location.href : undefined,
+        user_agent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+        session_id: s.sessionId,
+        trace_id: active?.traceId,
+        release: s.version,
+        build: s.build,
+        recent_errors: s.recentErrors.list(),
+    };
+}
+/**
+ * File an in-app bug report. Call after instrumentWeb() — it throws if the SDK
+ * isn't initialised or the message is empty (both are programmer errors). Network
+ * failures are swallowed (a failed report must never break the host app).
+ *
+ * @example
+ * import { reportBug } from "@heystack/otel/web";
+ * button.onclick = () => reportBug({ message: input.value, email: userEmail });
+ */
+export async function reportBug(report) {
+    const s = activeBugSession;
+    if (!s) {
+        throw new Error("reportBug() called before instrumentWeb(); call instrumentWeb() first");
+    }
+    const message = typeof report.message === "string" ? report.message.trim() : "";
+    if (!message)
+        throw new Error("reportBug() requires a non-empty message");
+    const payload = buildBugReportPayload(s, { ...report, message });
+    // 1. POST the structured report via the ORIGINAL fetch (never the patched one).
+    await s
+        .fetchImpl(`${s.endpoint}/v1/bug-reports`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${s.apiKey}`, "content-type": "application/json" },
+        body: JSON.stringify(payload),
+    })
+        .catch(() => { });
+    // 2. Emit one OTLP log so the report also appears on the telemetry timeline.
+    const active = s.activeTrace.get();
+    s.logsExporter.add({
+        timeUnixMs: Date.now(),
+        severityText: "INFO",
+        body: message,
+        attributes: {
+            "event.name": "user.bug_report",
+            "url.full": typeof location !== "undefined" ? location.href : "",
+            session_id: s.sessionId,
+            ...(report.email ? { "user.email": report.email } : {}),
+        },
+        traceId: active?.traceId,
+        spanId: active?.spanId,
+    });
+    await s.logsExporter.flush().catch(() => { });
+}

package/dist/workers.d.ts

@@ -134,6 +134,18 @@ export interface WorkersConfig {
     /** Defaults to env.HEYSTACK_API_KEY at request time if omitted. */
     apiKey?: string;
     endpoint?: string;
+    /**
+     * Release identifier for this deploy → `service.version` resource attribute.
+     * Powers release health + the suspect-release view in the console. See
+     * {@link HeystackOptions.version}.
+     */
+    version?: string;
+    /**
+     * Commit SHA for this deploy → `service.build` resource attribute. Powers
+     * suspect-commit attribution (deep-links to the commit when a repo URL is set
+     * in the console). See {@link HeystackOptions.build}.
+     */
+    build?: string;
     /**
      * Optional override to keep the isolate alive until each export `fetch`
      * completes. When provided this takes priority over the auto-detected

package/dist/workers.js

@@ -13,7 +13,7 @@ import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { Resource } from "@opentelemetry/resources";
 import { BasicTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-import { buildExporterConfig, DEFAULT_ENDPOINT } from "./core.js";
+import { buildExporterConfig, DEFAULT_ENDPOINT, releaseResourceAttributes, } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 import { detectLLMProvider, llmRequestAttrs, llmResponseAttrs, llmContentAttrs } from "./llm-enrich.js";
 import { instrumentEnv } from "./workers-bindings.js";
@@ -576,7 +576,12 @@ export class HeystackSpanExporter {
 export function createTracerProvider(config) {
     const exporter = new HeystackSpanExporter(config);
     const provider = new BasicTracerProvider({
-        resource: new Resource({ [ATTR_SERVICE_NAME]: config.service }),
+        // service.name is always present; service.version/service.build are added
+        // only when the caller supplied `version`/`build` (release attribution).
+        resource: new Resource({
+            [ATTR_SERVICE_NAME]: config.service,
+            ...releaseResourceAttributes(config),
+        }),
         spanProcessors: [new SimpleSpanProcessor(exporter)],
         sampler: makeSampler(config.sampling),
     });
@@ -781,6 +786,8 @@ export function instrument(handler, config) {
             apiKey,
             service: config.service,
             endpoint: config.endpoint,
+            version: config.version,
+            build: config.build,
             waitUntil: config.waitUntil,
             sampling: config.sampling,
             ai: config.ai,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",