autotel-posthog 1.0.0 → 2.0.0

package/README.md

@@ -18,10 +18,15 @@ npm install autotel-posthog posthog-js autotel-web
 npm install autotel-posthog posthog-node autotel autotel-subscribers
 ```
 
-Every peer is declared optional so the half you skip does not warn about
-packages it will never import. `posthog-js` is not bundled: two copies on one
-page means two session managers and two different answers to
-`get_session_id()`, which would break the join this package exists to make.
+Peers are declared optional so the half you skip does not warn about packages it
+will never import — with one exception. `autotel-web` is **required**: the root
+entry's `joinPostHog` imports `autotel-web/baggage` at module scope for the
+session hop, and a peer the entry point always imports is not optional. Server
+events live behind `autotel-posthog/subscriber`, which does not pull it in.
+
+`posthog-js` is not bundled: two copies on one page means two session managers
+and two different answers to `get_session_id()`, which would break the join this
+package exists to make.
 
 ## The short version
 
@@ -111,6 +116,70 @@ posthog.init('<key>', { before_send: [autotelBeforeSend()] });
 
 A `$exception` or a funnel drop-off in PostHog now names the trace that explains it. Events an earlier hook dropped stay dropped: `before_send` is a chain, and `null` means the page suppressed the event deliberately.
 
+#### Events captured after an `await`
+
+The browser has no `AsyncLocalStorage`, so OpenTelemetry's active context is gone by the first `await` — which is exactly where the events worth joining fire:
+
+```ts
+await span('checkout.click', async () => {
+  await fetch('/checkout', { method: 'POST' });
+  // The active span is already gone here. joinPostHog still finds it.
+  posthog.capture('checkout_failed', { message: 'Card declined' });
+});
+```
+
+`joinPostHog` falls back to the most recent span it has seen start and not yet end, so no Zone.js and no manual `context.with()`. The active context wins when there is one, and a span that already ended is never used.
+
+It refuses to guess when guessing could be wrong. Two overlapping user actions each start their own trace, and with no active context there is nothing to say which one an event belongs to — so nothing is added rather than a trace id pointing at an unrelated request. In development it says so in the console, and names the fix.
+
+The fix is one line. Read the ids while the span is still active, before the first `await`, and spread them onto the capture:
+
+```ts
+import { traceProperties } from 'autotel-posthog';
+
+await span('checkout.click', async () => {
+  const trace = traceProperties();
+  await fetch('/checkout', { method: 'POST' });
+  posthog.capture('checkout_failed', { ...trace, message: 'Card declined' });
+});
+```
+
+`traceProperties()` returns `{}` when nothing is being traced, so the spread is always safe, and a property the caller set is never overwritten — explicit always wins. `$trace_url` is still added for you.
+
+`autotelBeforeSend()` on its own reads only the active context. Pass `fallbackSpanContext` for the same behaviour without the enricher.
+
+## When nothing shows up
+
+Every failure here is quiet on purpose — a missing PostHog, a rotated session, replay switched off all just produce no attribute. That is right in production and useless while wiring it up, so each exit says why, once per reason:
+
+`debug` is on by default in development and silent in production — `process.env.NODE_ENV` where a bundler substituted one, a localhost page otherwise. A diagnostic nobody switches on is a diagnostic nobody reads. `debug: false` silences it anywhere; `debug: true` forces it on.
+
+### Testing it end to end
+
+`posthog-js` drops bots — headless Chrome included — **before** `before_send` runs, so a Playwright or Puppeteer test sees no events and no stamping, with no error to explain it. Turn the filter off on the instance under test only:
+
+```ts
+await page.evaluate(() =>
+  window.posthog.set_config({ opt_out_useragent_filter: true }),
+);
+```
+
+PostHog still classifies that traffic as a bot server-side, so filter it out of your own analysis rather than leaving it in production code.
+
+## Server hop
+
+`joinPostHog` copies PostHog's session id onto subsequent same-origin fetches as W3C `baggage` (`propagateSession`, default on). The backend then stamps that id on the handler span:
+
+```ts
+init({ service: 'api', endpoint, baggage: '' });
+```
+
+`baggage: ''` writes `session.id`. `baggage: true` would write `baggage.session.id`. Distinct id stays off; it can be an email. Pass `propagateSession: false` to skip the header.
+
+Needs `autotel` 7.0.1 or later: earlier versions read the empty string as "off" and the attribute never landed.
+
+Docs: [PostHog join](https://jagreehal.github.io/autotel/integrations/posthog/). Worked example: [`apps/example-posthog`](../../apps/example-posthog).
+
 ## Product events from the server
 
 ```ts

package/dist/index.cjs

@@ -1,5 +1,31 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let autotel_web_baggage = require("autotel-web/baggage");
 let _opentelemetry_api = require("@opentelemetry/api");
+//#region src/dev-mode.ts
+/**
+* Whether to say something when the join cannot do its job.
+*
+* Diagnostics behind an opt-in flag are read by people who already know
+* something is wrong, and the failure here is not knowing: every exit on this
+* path produces a missing property and nothing else, which looks exactly like
+* a working integration until someone queries for it weeks later.
+*
+* So it follows the convention React and Redux use — loud while you build,
+* silent once you ship — rather than off until asked.
+*/
+function isDevelopment() {
+	try {
+		const env = typeof process !== "undefined" ? process.env?.NODE_ENV : void 0;
+		if (typeof env === "string" && env.length > 0) return env !== "production";
+	} catch {}
+	try {
+		const host = globalThis.location?.hostname;
+		return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host?.endsWith(".local") === true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/posthog-like.ts
 /**
 * Whether this object can actually answer questions yet.
@@ -86,6 +112,24 @@ const STATUS_ERROR = 2;
 function failed(span) {
 	return span.status?.code === STATUS_ERROR || span.attributes["exception.type"] !== void 0 || span.events?.some((event) => event.name === "exception") === true;
 }
+const EXPLANATION = {
+	"no-posthog": "no usable PostHog on the page. Pass the instance to joinPostHog(), or check posthog.init() runs before the first span.",
+	"session-rotated": "the PostHog session rotated after this span started, so a link would point at a different recording than the one the span belongs to.",
+	"not-recording": "session replay is not recording. Check it is enabled for the project, that this session was not sampled out, and that the recorder has started. Note posthog-js does not record bots or headless browsers."
+};
+/**
+* One warning per reason, not per span. A failing join fails on every span,
+* and a console with a thousand copies of the same line is the same as a
+* console with none.
+*/
+function explainer(enabled) {
+	const said = /* @__PURE__ */ new Set();
+	return (reason) => {
+		if (!enabled || said.has(reason)) return;
+		said.add(reason);
+		console.warn(`[autotel-posthog] No session.replay.url on a failed span: ${EXPLANATION[reason]}`);
+	};
+}
 function resolvePostHog(options) {
 	const configured = typeof options.posthog === "function" ? options.posthog() : options.posthog;
 	if (isUsable(configured)) return configured;
@@ -93,6 +137,7 @@ function resolvePostHog(options) {
 	return isUsable(global) ? global : void 0;
 }
 function posthogCompatibility(options = {}) {
+	const explain = explainer(options.debug ?? isDevelopment());
 	return {
 		/**
 		* Identity is read here, not in `onEnd`, because it is a fact about when
@@ -120,13 +165,23 @@ function posthogCompatibility(options = {}) {
 		onEnd(span) {
 			if (!failed(span)) return;
 			const posthog = resolvePostHog(options);
-			if (!posthog) return;
+			if (!posthog) {
+				explain("no-posthog");
+				return;
+			}
 			const attributes = span.attributes;
 			if (attributes["session.replay.url"] !== void 0) return;
 			const current = readSessionId(posthog);
-			if (current === void 0 || current !== attributes["session.id"]) return;
+			if (current === void 0 || current !== attributes["session.id"]) {
+				explain("session-rotated");
+				return;
+			}
 			const url = readReplayUrl(posthog);
-			if (url !== void 0) attributes["session.replay.url"] = url;
+			if (url === void 0) {
+				explain("not-recording");
+				return;
+			}
+			attributes["session.replay.url"] = url;
 		},
 		forceFlush() {
 			return Promise.resolve();
@@ -160,21 +215,60 @@ function posthogCompatibility(options = {}) {
 * ```
 */
 /**
+* The ids of the span in progress, shaped to spread straight onto a capture.
+*
+* The hook recovers the span by itself in every case it can be sure of. This
+* is for the case it cannot: two overlapping user actions, each its own trace,
+* with no active context left to say which one an event belongs to. Read it
+* while the span is still active — before the first `await` — and spread it:
+*
+* ```ts
+* await span('checkout.click', async () => {
+*   const trace = traceProperties();
+*   await fetch('/checkout', { method: 'POST' });
+*   posthog.capture('checkout_failed', { ...trace });
+* });
+* ```
+*
+* Returns `{}` when nothing is being traced, so the spread is always safe.
+* Properties the caller sets are never overwritten, so this always wins.
+*/
+function traceProperties() {
+	const spanContext = _opentelemetry_api.trace.getSpanContext(_opentelemetry_api.context.active());
+	if (!spanContext) return {};
+	return {
+		$trace_id: spanContext.traceId,
+		$span_id: spanContext.spanId
+	};
+}
+/** The active context wins; this only answers when there is nothing active. */
+function readFallback(options) {
+	try {
+		return options.fallbackSpanContext?.();
+	} catch {
+		return;
+	}
+}
+/**
 * A PostHog `before_send` hook that adds `$trace_id` and `$span_id` from the
 * span in progress.
 */
 function autotelBeforeSend(options = {}) {
 	return (event) => {
 		if (event === null) return null;
-		const spanContext = _opentelemetry_api.trace.getSpanContext(_opentelemetry_api.context.active());
-		if (!spanContext) return event;
 		const properties = event.properties;
-		if (properties["$trace_id"] === void 0) properties["$trace_id"] = spanContext.traceId;
-		if (properties["$span_id"] === void 0) properties["$span_id"] = spanContext.spanId;
+		const spanContext = _opentelemetry_api.trace.getSpanContext(_opentelemetry_api.context.active()) ?? readFallback(options);
+		if (spanContext) {
+			if (properties["$trace_id"] === void 0) properties["$trace_id"] = spanContext.traceId;
+			if (properties["$span_id"] === void 0) properties["$span_id"] = spanContext.spanId;
+		}
+		const traceId = properties["$trace_id"];
+		const spanId = properties["$span_id"];
+		if (typeof traceId !== "string" || typeof spanId !== "string") return event;
 		if (options.traceUrl && properties["$trace_url"] === void 0) try {
 			const url = options.traceUrl({
-				traceId: spanContext.traceId,
-				spanId: spanContext.spanId
+				traceId,
+				spanId
 			});
 			if (url !== void 0) properties["$trace_url"] = url;
 		} catch {}
@@ -187,8 +281,21 @@ function autotelBeforeSend(options = {}) {
 * Marks our hook so a second call recognises it. Framework code runs more than
 * once — strict mode, HMR, a re-render — and a chain that grows on every render
 * stamps the same properties again and again.
+*
+* The marker is not a flag but the hook's registry of live-span lists. Only one
+* hook is ever installed, while every call returns its own processor tracking
+* its own spans — and the app registers whichever one it was handed last. A
+* later call therefore has to join the installed hook's registry rather than
+* keep its spans to itself, or the join stops working after the first
+* re-render, silently, in exactly the frameworks that re-render.
 */
 const MARKER = "__autotelBeforeSend";
+/**
+* How many started-but-not-ended spans to keep for the fallback. Deep enough
+* for any real nesting on a page, shallow enough that leaked spans cost
+* nothing.
+*/
+const MAX_LIVE_SPANS = 128;
 function existingHooks(posthog) {
 	const current = posthog.config?.before_send;
 	if (Array.isArray(current)) return current;
@@ -210,29 +317,167 @@ function joinPostHog(posthog, options = {}) {
 			const instance = resolve();
 			if (!instance) return false;
 			const hooks = existingHooks(instance);
-			if (hooks.some((hook) => hook[MARKER])) return true;
+			const installed = hooks.find((hook) => hook[MARKER]);
+			if (installed) {
+				const shared = installed[MARKER];
+				if (shared && shared !== registry) {
+					const wasJoined = registry.includes(live);
+					leave();
+					registry = shared;
+					if (wasJoined) join();
+				}
+				return true;
+			}
 			if (typeof instance.set_config !== "function") return false;
-			const hook = autotelBeforeSend(options);
-			hook[MARKER] = true;
+			const hook = autotelBeforeSend({
+				...options,
+				fallbackSpanContext
+			});
+			hook[MARKER] = registry;
 			instance.set_config({ before_send: [...hooks, hook] });
 			return true;
 		} catch {
 			return false;
 		}
 	};
+	/**
+	* Spans that have started and not yet ended, newest last.
+	*
+	* The browser drops the active context at the first `await`, so by the time
+	* the fetch fails and the page captures the event, `context.active()` is
+	* root again. These are the spans still in flight, and the newest of them is
+	* the one the user is inside — the same answer the active context would have
+	* given, recovered from what the processor already sees.
+	*
+	* An array, not a single slot: spans do not end in the order they start, and
+	* an inner span ending must not erase the outer one that is still open.
+	* Concurrent *sibling* spans are the one case this cannot tell apart, and it
+	* picks the most recent — a wrong span in the same trace, never a wrong
+	* trace.
+	*/
+	const live = [];
+	/**
+	* The registry the installed hook reads. Starts as this call's own and is
+	* replaced by the installed hook's the moment `wire()` finds one, so every
+	* call ends up pointing at the same list.
+	*/
+	let registry = [];
+	/**
+	* Membership is earned by having a span, not by existing.
+	*
+	* Every re-render calls `joinPostHog` again and only the processor the app
+	* registers is ever handed a span — so a slot per call is a slot per render,
+	* growing what each PostHog capture has to walk and holding it for the life
+	* of the page. Joining on the first span and leaving on the last keeps the
+	* registry the size of what is actually in flight.
+	*/
+	const join = () => {
+		if (!registry.includes(live)) registry.push(live);
+	};
+	const leave = () => {
+		const at = registry.indexOf(live);
+		if (at !== -1) registry.splice(at, 1);
+	};
+	let warnedAmbiguous = false;
+	const fallbackSpanContext = () => {
+		const open = registry.flat();
+		const newest = open.at(-1);
+		if (!newest) return void 0;
+		if (open.some((candidate) => candidate.traceId !== newest.traceId)) {
+			if ((options.debug ?? isDevelopment()) && !warnedAmbiguous) {
+				warnedAmbiguous = true;
+				console.warn("[autotel-posthog] No $trace_id on a PostHog event: more than one trace was in flight and the browser had already lost the active context, so which one this event belongs to is unknowable. Fix: read traceProperties() before the first await and spread it onto the capture — const t = traceProperties(); ... posthog.capture(name, { ...t }).");
+			}
+			return;
+		}
+		return newest;
+	};
+	/**
+	* Same defensiveness as every other read here: a processor that throws on a
+	* span it did not expect takes the span down with it.
+	*/
+	const contextOf = (span) => {
+		try {
+			return typeof span.spanContext === "function" ? span.spanContext() : void 0;
+		} catch {
+			return;
+		}
+	};
+	const remember = (span) => {
+		const spanContext = contextOf(span);
+		if (!spanContext) return;
+		join();
+		live.push(spanContext);
+		if (live.length > MAX_LIVE_SPANS) live.shift();
+	};
+	const forget = (span) => {
+		const spanId = contextOf(span)?.spanId;
+		if (!spanId) return;
+		const at = live.findIndex((candidate) => candidate.spanId === spanId);
+		if (at !== -1) live.splice(at, 1);
+		if (live.length === 0) leave();
+	};
 	let wired = wire();
 	const enricher = posthogCompatibility({
 		...options,
 		posthog
 	});
+	let lastPropagated;
+	/**
+	* Copy PostHog's session id into baggage, once per session.
+	*
+	* Called at construction as well as on every span, because the baggage
+	* header is decided before the span exists: the wrapped fetch checks for
+	* baggage and only then hands off to the instrumented fetch that opens the
+	* span. Waiting for `onStart` means the page's first request leaves without
+	* `session.id` and only later ones carry it — and with no application span
+	* around the call, that is every first request.
+	*
+	* Still called from `onStart` too: at construction PostHog may be the loader
+	* snippet's stub with nothing to read yet, and sessions rotate after 30
+	* minutes idle.
+	*/
+	const propagate = () => {
+		if (options.propagateSession === false) return;
+		try {
+			const instance = resolve();
+			if (!instance) return;
+			const sessionId = readSessionId(instance);
+			if (!sessionId || sessionId === lastPropagated) return;
+			lastPropagated = sessionId;
+			(0, autotel_web_baggage.setBaggage)({ "session.id": sessionId });
+		} catch {}
+	};
+	propagate();
 	return {
 		onStart(span, context) {
+			remember(span);
 			if (!wired) wired = wire();
 			enricher.onStart(span, context);
+			propagate();
+		},
+		onEnd: (span) => {
+			forget(span);
+			enricher.onEnd(span);
 		},
-		onEnd: (span) => enricher.onEnd(span),
 		forceFlush: () => enricher.forceFlush(),
-		shutdown: () => enricher.shutdown()
+		shutdown: () => {
+			live.length = 0;
+			leave();
+			return enricher.shutdown();
+		},
+		/**
+		* How many spans the fallback is holding. Bookkeeping, exposed so a test
+		* can prove the bound holds; nothing reads it at runtime.
+		* @internal
+		*/
+		liveCount: () => live.length,
+		/**
+		* How many processors currently have spans in flight. Bookkeeping, exposed
+		* so a test can prove repeated calls do not accumulate.
+		* @internal
+		*/
+		registeredCount: () => registry.length
 	};
 }
 //#endregion
@@ -265,3 +510,4 @@ exports.autotelBeforeSend = autotelBeforeSend;
 exports.joinPostHog = joinPostHog;
 exports.posthogCompatibility = posthogCompatibility;
 exports.posthogSessionId = posthogSessionId;
+exports.traceProperties = traceProperties;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { PostHog } from "posthog-js";
+import { SpanContext } from "@opentelemetry/api";
 //#region src/posthog-like.d.ts
 /** Exactly the members read, with PostHog's own signatures. */
 declare global {
@@ -44,31 +45,28 @@ interface PostHogCompatibilityOptions {
    * turns into a cardinality bill.
    */
   featureFlags?: string[];
+  /**
+   * Explain, once per distinct reason, why a span that should have carried a
+   * replay link did not.
+   *
+   * Every exit on this path is deliberately quiet — a missing PostHog, a
+   * session that rotated, a project with replay switched off all just produce
+   * no attribute. In production that is correct. While wiring it up it is
+   * indistinguishable from success, which is how a broken join survives a
+   * green test suite.
+   *
+   * On by default in development and silent in production, the way React and
+   * Redux warn: a diagnostic nobody switches on is a diagnostic nobody reads.
+   * Development is `process.env.NODE_ENV` where a bundler substituted one, and
+   * a localhost page otherwise. Set it explicitly to override either way.
+   *
+   * @default true in development, false in production
+   */
+  debug?: boolean;
 }
 declare function posthogCompatibility(options?: PostHogCompatibilityOptions): SpanProcessor;
 //#endregion
 //#region src/before-send.d.ts
-/**
- * The other half of the join: PostHog events that know which trace they
- * happened inside.
- *
- * `posthogCompatibility()` teaches the trace about the session. This teaches
- * the session about the trace, so a `$exception` or a funnel drop-off in
- * PostHog carries the trace id that explains it, and the property names match
- * the ones autotel's server-side subscriber already writes — one set of names
- * whichever side captured the event.
- *
- * @example
- * ```ts
- * posthog.init('<key>', {
- *   before_send: [
- *     autotelBeforeSend({
- *       traceUrl: ({ traceId }) => `https://traces.example.com/${traceId}`,
- *     }),
- *   ],
- * });
- * ```
- */
 /**
  * Structural copy of PostHog's `CaptureResult`. Only `properties` is touched;
  * everything else is passed through untouched.
@@ -97,7 +95,42 @@ interface AutotelBeforeSendOptions {
     traceId: string;
     spanId: string;
   }) => string | undefined;
+  /**
+   * Where to look when the active context is empty.
+   *
+   * Node keeps the active span across `await` through AsyncLocalStorage; the
+   * browser has no equivalent, so `context.active()` is back to root by the
+   * time the fetch resolves and the interesting event fires. Without this the
+   * hook would silently add nothing to exactly the events worth joining.
+   *
+   * `joinPostHog()` supplies one backed by the spans it has seen start and not
+   * yet end. Left unset, the hook uses only the active context.
+   */
+  fallbackSpanContext?: () => SpanContext | undefined;
 }
+/**
+ * The ids of the span in progress, shaped to spread straight onto a capture.
+ *
+ * The hook recovers the span by itself in every case it can be sure of. This
+ * is for the case it cannot: two overlapping user actions, each its own trace,
+ * with no active context left to say which one an event belongs to. Read it
+ * while the span is still active — before the first `await` — and spread it:
+ *
+ * ```ts
+ * await span('checkout.click', async () => {
+ *   const trace = traceProperties();
+ *   await fetch('/checkout', { method: 'POST' });
+ *   posthog.capture('checkout_failed', { ...trace });
+ * });
+ * ```
+ *
+ * Returns `{}` when nothing is being traced, so the spread is always safe.
+ * Properties the caller sets are never overwritten, so this always wins.
+ */
+declare function traceProperties(): {
+  $trace_id?: string;
+  $span_id?: string;
+};
 /**
  * A PostHog `before_send` hook that adds `$trace_id` and `$span_id` from the
  * span in progress.
@@ -113,10 +146,20 @@ declare function autotelBeforeSend(options?: AutotelBeforeSendOptions): BeforeSe
  * configured — the loader snippet's stub has no `set_config`, and the trace
  * side is worth having even when the PostHog side cannot be wired.
  */
-interface JoinPostHogOptions extends Omit<PostHogCompatibilityOptions, 'posthog'>, AutotelBeforeSendOptions {}
+interface JoinPostHogOptions extends Omit<PostHogCompatibilityOptions, 'posthog'>, AutotelBeforeSendOptions {
+  /**
+   * Copy PostHog's session id onto subsequent same-origin fetches as W3C
+   * `baggage`, so the server span of a traced request carries `session.id`.
+   * The backend needs `init({ baggage: '' })` for the attribute to land under
+   * that name. Distinct id stays off: it can be an email.
+   *
+   * @default true
+   */
+  propagateSession?: boolean;
+}
 declare function joinPostHog(posthog: PostHogLike | (() => PostHogLike | undefined), options?: JoinPostHogOptions): SpanProcessor;
 //#endregion
 //#region src/session-id.d.ts
 declare function posthogSessionId(posthog?: PostHogLike): string | undefined;
 //#endregion
-export { type AutotelBeforeSendOptions, type BeforeSendLike, type CaptureResultLike, type JoinPostHogOptions, type PostHogCompatibilityOptions, type PostHogLike, autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId };
+export { type AutotelBeforeSendOptions, type BeforeSendLike, type CaptureResultLike, type JoinPostHogOptions, type PostHogCompatibilityOptions, type PostHogLike, autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId, traceProperties };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { SpanContext } from "@opentelemetry/api";
 import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { PostHog } from "posthog-js";
 //#region src/posthog-like.d.ts
@@ -44,31 +45,28 @@ interface PostHogCompatibilityOptions {
    * turns into a cardinality bill.
    */
   featureFlags?: string[];
+  /**
+   * Explain, once per distinct reason, why a span that should have carried a
+   * replay link did not.
+   *
+   * Every exit on this path is deliberately quiet — a missing PostHog, a
+   * session that rotated, a project with replay switched off all just produce
+   * no attribute. In production that is correct. While wiring it up it is
+   * indistinguishable from success, which is how a broken join survives a
+   * green test suite.
+   *
+   * On by default in development and silent in production, the way React and
+   * Redux warn: a diagnostic nobody switches on is a diagnostic nobody reads.
+   * Development is `process.env.NODE_ENV` where a bundler substituted one, and
+   * a localhost page otherwise. Set it explicitly to override either way.
+   *
+   * @default true in development, false in production
+   */
+  debug?: boolean;
 }
 declare function posthogCompatibility(options?: PostHogCompatibilityOptions): SpanProcessor;
 //#endregion
 //#region src/before-send.d.ts
-/**
- * The other half of the join: PostHog events that know which trace they
- * happened inside.
- *
- * `posthogCompatibility()` teaches the trace about the session. This teaches
- * the session about the trace, so a `$exception` or a funnel drop-off in
- * PostHog carries the trace id that explains it, and the property names match
- * the ones autotel's server-side subscriber already writes — one set of names
- * whichever side captured the event.
- *
- * @example
- * ```ts
- * posthog.init('<key>', {
- *   before_send: [
- *     autotelBeforeSend({
- *       traceUrl: ({ traceId }) => `https://traces.example.com/${traceId}`,
- *     }),
- *   ],
- * });
- * ```
- */
 /**
  * Structural copy of PostHog's `CaptureResult`. Only `properties` is touched;
  * everything else is passed through untouched.
@@ -97,7 +95,42 @@ interface AutotelBeforeSendOptions {
     traceId: string;
     spanId: string;
   }) => string | undefined;
+  /**
+   * Where to look when the active context is empty.
+   *
+   * Node keeps the active span across `await` through AsyncLocalStorage; the
+   * browser has no equivalent, so `context.active()` is back to root by the
+   * time the fetch resolves and the interesting event fires. Without this the
+   * hook would silently add nothing to exactly the events worth joining.
+   *
+   * `joinPostHog()` supplies one backed by the spans it has seen start and not
+   * yet end. Left unset, the hook uses only the active context.
+   */
+  fallbackSpanContext?: () => SpanContext | undefined;
 }
+/**
+ * The ids of the span in progress, shaped to spread straight onto a capture.
+ *
+ * The hook recovers the span by itself in every case it can be sure of. This
+ * is for the case it cannot: two overlapping user actions, each its own trace,
+ * with no active context left to say which one an event belongs to. Read it
+ * while the span is still active — before the first `await` — and spread it:
+ *
+ * ```ts
+ * await span('checkout.click', async () => {
+ *   const trace = traceProperties();
+ *   await fetch('/checkout', { method: 'POST' });
+ *   posthog.capture('checkout_failed', { ...trace });
+ * });
+ * ```
+ *
+ * Returns `{}` when nothing is being traced, so the spread is always safe.
+ * Properties the caller sets are never overwritten, so this always wins.
+ */
+declare function traceProperties(): {
+  $trace_id?: string;
+  $span_id?: string;
+};
 /**
  * A PostHog `before_send` hook that adds `$trace_id` and `$span_id` from the
  * span in progress.
@@ -113,10 +146,20 @@ declare function autotelBeforeSend(options?: AutotelBeforeSendOptions): BeforeSe
  * configured — the loader snippet's stub has no `set_config`, and the trace
  * side is worth having even when the PostHog side cannot be wired.
  */
-interface JoinPostHogOptions extends Omit<PostHogCompatibilityOptions, 'posthog'>, AutotelBeforeSendOptions {}
+interface JoinPostHogOptions extends Omit<PostHogCompatibilityOptions, 'posthog'>, AutotelBeforeSendOptions {
+  /**
+   * Copy PostHog's session id onto subsequent same-origin fetches as W3C
+   * `baggage`, so the server span of a traced request carries `session.id`.
+   * The backend needs `init({ baggage: '' })` for the attribute to land under
+   * that name. Distinct id stays off: it can be an email.
+   *
+   * @default true
+   */
+  propagateSession?: boolean;
+}
 declare function joinPostHog(posthog: PostHogLike | (() => PostHogLike | undefined), options?: JoinPostHogOptions): SpanProcessor;
 //#endregion
 //#region src/session-id.d.ts
 declare function posthogSessionId(posthog?: PostHogLike): string | undefined;
 //#endregion
-export { type AutotelBeforeSendOptions, type BeforeSendLike, type CaptureResultLike, type JoinPostHogOptions, type PostHogCompatibilityOptions, type PostHogLike, autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId };
+export { type AutotelBeforeSendOptions, type BeforeSendLike, type CaptureResultLike, type JoinPostHogOptions, type PostHogCompatibilityOptions, type PostHogLike, autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId, traceProperties };

package/dist/index.js

@@ -1,4 +1,30 @@
+import { setBaggage } from "autotel-web/baggage";
 import { context, trace } from "@opentelemetry/api";
+//#region src/dev-mode.ts
+/**
+* Whether to say something when the join cannot do its job.
+*
+* Diagnostics behind an opt-in flag are read by people who already know
+* something is wrong, and the failure here is not knowing: every exit on this
+* path produces a missing property and nothing else, which looks exactly like
+* a working integration until someone queries for it weeks later.
+*
+* So it follows the convention React and Redux use — loud while you build,
+* silent once you ship — rather than off until asked.
+*/
+function isDevelopment() {
+	try {
+		const env = typeof process !== "undefined" ? process.env?.NODE_ENV : void 0;
+		if (typeof env === "string" && env.length > 0) return env !== "production";
+	} catch {}
+	try {
+		const host = globalThis.location?.hostname;
+		return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host?.endsWith(".local") === true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/posthog-like.ts
 /**
 * Whether this object can actually answer questions yet.
@@ -85,6 +111,24 @@ const STATUS_ERROR = 2;
 function failed(span) {
 	return span.status?.code === STATUS_ERROR || span.attributes["exception.type"] !== void 0 || span.events?.some((event) => event.name === "exception") === true;
 }
+const EXPLANATION = {
+	"no-posthog": "no usable PostHog on the page. Pass the instance to joinPostHog(), or check posthog.init() runs before the first span.",
+	"session-rotated": "the PostHog session rotated after this span started, so a link would point at a different recording than the one the span belongs to.",
+	"not-recording": "session replay is not recording. Check it is enabled for the project, that this session was not sampled out, and that the recorder has started. Note posthog-js does not record bots or headless browsers."
+};
+/**
+* One warning per reason, not per span. A failing join fails on every span,
+* and a console with a thousand copies of the same line is the same as a
+* console with none.
+*/
+function explainer(enabled) {
+	const said = /* @__PURE__ */ new Set();
+	return (reason) => {
+		if (!enabled || said.has(reason)) return;
+		said.add(reason);
+		console.warn(`[autotel-posthog] No session.replay.url on a failed span: ${EXPLANATION[reason]}`);
+	};
+}
 function resolvePostHog(options) {
 	const configured = typeof options.posthog === "function" ? options.posthog() : options.posthog;
 	if (isUsable(configured)) return configured;
@@ -92,6 +136,7 @@ function resolvePostHog(options) {
 	return isUsable(global) ? global : void 0;
 }
 function posthogCompatibility(options = {}) {
+	const explain = explainer(options.debug ?? isDevelopment());
 	return {
 		/**
 		* Identity is read here, not in `onEnd`, because it is a fact about when
@@ -119,13 +164,23 @@ function posthogCompatibility(options = {}) {
 		onEnd(span) {
 			if (!failed(span)) return;
 			const posthog = resolvePostHog(options);
-			if (!posthog) return;
+			if (!posthog) {
+				explain("no-posthog");
+				return;
+			}
 			const attributes = span.attributes;
 			if (attributes["session.replay.url"] !== void 0) return;
 			const current = readSessionId(posthog);
-			if (current === void 0 || current !== attributes["session.id"]) return;
+			if (current === void 0 || current !== attributes["session.id"]) {
+				explain("session-rotated");
+				return;
+			}
 			const url = readReplayUrl(posthog);
-			if (url !== void 0) attributes["session.replay.url"] = url;
+			if (url === void 0) {
+				explain("not-recording");
+				return;
+			}
+			attributes["session.replay.url"] = url;
 		},
 		forceFlush() {
 			return Promise.resolve();
@@ -159,21 +214,60 @@ function posthogCompatibility(options = {}) {
 * ```
 */
 /**
+* The ids of the span in progress, shaped to spread straight onto a capture.
+*
+* The hook recovers the span by itself in every case it can be sure of. This
+* is for the case it cannot: two overlapping user actions, each its own trace,
+* with no active context left to say which one an event belongs to. Read it
+* while the span is still active — before the first `await` — and spread it:
+*
+* ```ts
+* await span('checkout.click', async () => {
+*   const trace = traceProperties();
+*   await fetch('/checkout', { method: 'POST' });
+*   posthog.capture('checkout_failed', { ...trace });
+* });
+* ```
+*
+* Returns `{}` when nothing is being traced, so the spread is always safe.
+* Properties the caller sets are never overwritten, so this always wins.
+*/
+function traceProperties() {
+	const spanContext = trace.getSpanContext(context.active());
+	if (!spanContext) return {};
+	return {
+		$trace_id: spanContext.traceId,
+		$span_id: spanContext.spanId
+	};
+}
+/** The active context wins; this only answers when there is nothing active. */
+function readFallback(options) {
+	try {
+		return options.fallbackSpanContext?.();
+	} catch {
+		return;
+	}
+}
+/**
 * A PostHog `before_send` hook that adds `$trace_id` and `$span_id` from the
 * span in progress.
 */
 function autotelBeforeSend(options = {}) {
 	return (event) => {
 		if (event === null) return null;
-		const spanContext = trace.getSpanContext(context.active());
-		if (!spanContext) return event;
 		const properties = event.properties;
-		if (properties["$trace_id"] === void 0) properties["$trace_id"] = spanContext.traceId;
-		if (properties["$span_id"] === void 0) properties["$span_id"] = spanContext.spanId;
+		const spanContext = trace.getSpanContext(context.active()) ?? readFallback(options);
+		if (spanContext) {
+			if (properties["$trace_id"] === void 0) properties["$trace_id"] = spanContext.traceId;
+			if (properties["$span_id"] === void 0) properties["$span_id"] = spanContext.spanId;
+		}
+		const traceId = properties["$trace_id"];
+		const spanId = properties["$span_id"];
+		if (typeof traceId !== "string" || typeof spanId !== "string") return event;
 		if (options.traceUrl && properties["$trace_url"] === void 0) try {
 			const url = options.traceUrl({
-				traceId: spanContext.traceId,
-				spanId: spanContext.spanId
+				traceId,
+				spanId
 			});
 			if (url !== void 0) properties["$trace_url"] = url;
 		} catch {}
@@ -186,8 +280,21 @@ function autotelBeforeSend(options = {}) {
 * Marks our hook so a second call recognises it. Framework code runs more than
 * once — strict mode, HMR, a re-render — and a chain that grows on every render
 * stamps the same properties again and again.
+*
+* The marker is not a flag but the hook's registry of live-span lists. Only one
+* hook is ever installed, while every call returns its own processor tracking
+* its own spans — and the app registers whichever one it was handed last. A
+* later call therefore has to join the installed hook's registry rather than
+* keep its spans to itself, or the join stops working after the first
+* re-render, silently, in exactly the frameworks that re-render.
 */
 const MARKER = "__autotelBeforeSend";
+/**
+* How many started-but-not-ended spans to keep for the fallback. Deep enough
+* for any real nesting on a page, shallow enough that leaked spans cost
+* nothing.
+*/
+const MAX_LIVE_SPANS = 128;
 function existingHooks(posthog) {
 	const current = posthog.config?.before_send;
 	if (Array.isArray(current)) return current;
@@ -209,29 +316,167 @@ function joinPostHog(posthog, options = {}) {
 			const instance = resolve();
 			if (!instance) return false;
 			const hooks = existingHooks(instance);
-			if (hooks.some((hook) => hook[MARKER])) return true;
+			const installed = hooks.find((hook) => hook[MARKER]);
+			if (installed) {
+				const shared = installed[MARKER];
+				if (shared && shared !== registry) {
+					const wasJoined = registry.includes(live);
+					leave();
+					registry = shared;
+					if (wasJoined) join();
+				}
+				return true;
+			}
 			if (typeof instance.set_config !== "function") return false;
-			const hook = autotelBeforeSend(options);
-			hook[MARKER] = true;
+			const hook = autotelBeforeSend({
+				...options,
+				fallbackSpanContext
+			});
+			hook[MARKER] = registry;
 			instance.set_config({ before_send: [...hooks, hook] });
 			return true;
 		} catch {
 			return false;
 		}
 	};
+	/**
+	* Spans that have started and not yet ended, newest last.
+	*
+	* The browser drops the active context at the first `await`, so by the time
+	* the fetch fails and the page captures the event, `context.active()` is
+	* root again. These are the spans still in flight, and the newest of them is
+	* the one the user is inside — the same answer the active context would have
+	* given, recovered from what the processor already sees.
+	*
+	* An array, not a single slot: spans do not end in the order they start, and
+	* an inner span ending must not erase the outer one that is still open.
+	* Concurrent *sibling* spans are the one case this cannot tell apart, and it
+	* picks the most recent — a wrong span in the same trace, never a wrong
+	* trace.
+	*/
+	const live = [];
+	/**
+	* The registry the installed hook reads. Starts as this call's own and is
+	* replaced by the installed hook's the moment `wire()` finds one, so every
+	* call ends up pointing at the same list.
+	*/
+	let registry = [];
+	/**
+	* Membership is earned by having a span, not by existing.
+	*
+	* Every re-render calls `joinPostHog` again and only the processor the app
+	* registers is ever handed a span — so a slot per call is a slot per render,
+	* growing what each PostHog capture has to walk and holding it for the life
+	* of the page. Joining on the first span and leaving on the last keeps the
+	* registry the size of what is actually in flight.
+	*/
+	const join = () => {
+		if (!registry.includes(live)) registry.push(live);
+	};
+	const leave = () => {
+		const at = registry.indexOf(live);
+		if (at !== -1) registry.splice(at, 1);
+	};
+	let warnedAmbiguous = false;
+	const fallbackSpanContext = () => {
+		const open = registry.flat();
+		const newest = open.at(-1);
+		if (!newest) return void 0;
+		if (open.some((candidate) => candidate.traceId !== newest.traceId)) {
+			if ((options.debug ?? isDevelopment()) && !warnedAmbiguous) {
+				warnedAmbiguous = true;
+				console.warn("[autotel-posthog] No $trace_id on a PostHog event: more than one trace was in flight and the browser had already lost the active context, so which one this event belongs to is unknowable. Fix: read traceProperties() before the first await and spread it onto the capture — const t = traceProperties(); ... posthog.capture(name, { ...t }).");
+			}
+			return;
+		}
+		return newest;
+	};
+	/**
+	* Same defensiveness as every other read here: a processor that throws on a
+	* span it did not expect takes the span down with it.
+	*/
+	const contextOf = (span) => {
+		try {
+			return typeof span.spanContext === "function" ? span.spanContext() : void 0;
+		} catch {
+			return;
+		}
+	};
+	const remember = (span) => {
+		const spanContext = contextOf(span);
+		if (!spanContext) return;
+		join();
+		live.push(spanContext);
+		if (live.length > MAX_LIVE_SPANS) live.shift();
+	};
+	const forget = (span) => {
+		const spanId = contextOf(span)?.spanId;
+		if (!spanId) return;
+		const at = live.findIndex((candidate) => candidate.spanId === spanId);
+		if (at !== -1) live.splice(at, 1);
+		if (live.length === 0) leave();
+	};
 	let wired = wire();
 	const enricher = posthogCompatibility({
 		...options,
 		posthog
 	});
+	let lastPropagated;
+	/**
+	* Copy PostHog's session id into baggage, once per session.
+	*
+	* Called at construction as well as on every span, because the baggage
+	* header is decided before the span exists: the wrapped fetch checks for
+	* baggage and only then hands off to the instrumented fetch that opens the
+	* span. Waiting for `onStart` means the page's first request leaves without
+	* `session.id` and only later ones carry it — and with no application span
+	* around the call, that is every first request.
+	*
+	* Still called from `onStart` too: at construction PostHog may be the loader
+	* snippet's stub with nothing to read yet, and sessions rotate after 30
+	* minutes idle.
+	*/
+	const propagate = () => {
+		if (options.propagateSession === false) return;
+		try {
+			const instance = resolve();
+			if (!instance) return;
+			const sessionId = readSessionId(instance);
+			if (!sessionId || sessionId === lastPropagated) return;
+			lastPropagated = sessionId;
+			setBaggage({ "session.id": sessionId });
+		} catch {}
+	};
+	propagate();
 	return {
 		onStart(span, context) {
+			remember(span);
 			if (!wired) wired = wire();
 			enricher.onStart(span, context);
+			propagate();
+		},
+		onEnd: (span) => {
+			forget(span);
+			enricher.onEnd(span);
 		},
-		onEnd: (span) => enricher.onEnd(span),
 		forceFlush: () => enricher.forceFlush(),
-		shutdown: () => enricher.shutdown()
+		shutdown: () => {
+			live.length = 0;
+			leave();
+			return enricher.shutdown();
+		},
+		/**
+		* How many spans the fallback is holding. Bookkeeping, exposed so a test
+		* can prove the bound holds; nothing reads it at runtime.
+		* @internal
+		*/
+		liveCount: () => live.length,
+		/**
+		* How many processors currently have spans in flight. Bookkeeping, exposed
+		* so a test can prove repeated calls do not accumulate.
+		* @internal
+		*/
+		registeredCount: () => registry.length
 	};
 }
 //#endregion
@@ -260,4 +505,4 @@ function posthogSessionId(posthog) {
 	return instance ? readSessionId(instance) : void 0;
 }
 //#endregion
-export { autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId };
+export { autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId, traceProperties };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-posthog",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Everything PostHog for autotel: browser session/replay join, server-side event subscriber, and trace links in both directions",
   "type": "module",
   "sideEffects": false,
@@ -30,21 +30,25 @@
     "@opentelemetry/sdk-trace-base": ">=2.0.0",
     "posthog-js": ">=1.200.0",
     "posthog-node": ">=4.0.0",
-    "autotel": "7.0.0",
-    "autotel-subscribers": "50.0.0"
+    "autotel": "7.1.0",
+    "autotel-subscribers": "51.0.0",
+    "autotel-web": "1.13.1"
   },
   "devDependencies": {
     "@opentelemetry/context-async-hooks": "^2.10.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-web": "2.10.0",
     "@types/node": "^26.1.2",
+    "jsdom": "29.1.1",
     "posthog-js": "1.417.1",
     "posthog-node": "^4.18.0",
     "rimraf": "^6.1.3",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "autotel": "7.0.0",
-    "autotel-subscribers": "50.0.0"
+    "autotel": "7.1.0",
+    "autotel-web": "1.13.1",
+    "autotel-subscribers": "51.0.0"
   },
   "keywords": [
     "opentelemetry",