autotel-posthog 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,122 @@
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { PostHog } from "posthog-js";
+//#region src/posthog-like.d.ts
+/** Exactly the members read, with PostHog's own signatures. */
+declare global {
+  /**
+   * PostHog installs itself on the page - as the loader snippet's array stub
+   * first, then as the real instance. Declaring it here is what lets the rest
+   * of this package read `globalThis.posthog` without asserting a shape.
+   */
+  var posthog: PostHogLike | undefined;
+}
+type PostHogLike = Partial<Pick<PostHog, 'get_session_id' | 'get_distinct_id' | 'get_session_replay_url' | 'getFeatureFlag' | 'sessionRecordingStarted' | 'set_config'>> & {
+  /**
+   * Pre-`sessionRecordingStarted()` fallback. Not part of the public type —
+   * PostHog exposes only `_forceAllowLocalhostNetworkCapture` on this object —
+   * so it is declared here and read defensively, never preferred.
+   */
+  sessionRecording?: {
+    started?: boolean;
+  };
+  config?: Partial<PostHog['config']>;
+};
+//#endregion
+//#region src/compatibility.d.ts
+interface PostHogCompatibilityOptions {
+  /**
+   * The PostHog instance, or a function returning it.
+   *
+   * Defaults to `globalThis.posthog`, which is where the snippet and
+   * `posthog-js` both leave it. An instance passed here is preferred — two
+   * PostHog instances on one page is a real setup and an explicit argument is a
+   * decision — but only while it can answer: hand in the loader snippet's array
+   * stub and this falls back to the global once posthog-js swaps the real
+   * library in over the top of it.
+   */
+  posthog?: PostHogLike | (() => PostHogLike | undefined);
+  /**
+   * Flag keys to stamp on every span as `feature_flag.<key>`, so error rate and
+   * latency can be split by variant in whichever backend receives the spans.
+   *
+   * Named explicitly rather than read wholesale: every flag is another
+   * attribute on every span, and "all of them" is how an analytics convenience
+   * turns into a cardinality bill.
+   */
+  featureFlags?: string[];
+}
+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.
+ */
+/** What a PostHog event property can hold: JSON, since that is what is sent. */
+type PostHogPropertyValue = string | number | boolean | null | undefined | Array<PostHogPropertyValue> | {
+  [key: string]: PostHogPropertyValue;
+};
+interface CaptureResultLike {
+  properties: Record<string, PostHogPropertyValue>;
+  [key: string]: PostHogPropertyValue;
+}
+type BeforeSendLike = (event: CaptureResultLike | null) => CaptureResultLike | null;
+interface AutotelBeforeSendOptions {
+  /**
+   * Build a link to the trace in your own backend.
+   *
+   * Ids correlate; they do not navigate. Whoever reads a PostHog event wants
+   * one click back to the trace, and only the app knows whether that is
+   * Traceway, Grafana, Honeycomb or a local devtools port — so the URL shape
+   * is yours to supply.
+   *
+   * Return `undefined` to add nothing for this event.
+   */
+  traceUrl?: (context: {
+    traceId: string;
+    spanId: string;
+  }) => string | undefined;
+}
+/**
+ * A PostHog `before_send` hook that adds `$trace_id` and `$span_id` from the
+ * span in progress.
+ */
+declare function autotelBeforeSend(options?: AutotelBeforeSendOptions): BeforeSendLike;
+//#endregion
+//#region src/join.d.ts
+/**
+ * Wire PostHog to stamp trace context on its events, and return the span
+ * enricher for the other direction.
+ *
+ * Safe to call more than once, and safe to call on an instance that cannot be
+ * 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 {}
+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 };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { PostHog } from "posthog-js";
+//#region src/posthog-like.d.ts
+/** Exactly the members read, with PostHog's own signatures. */
+declare global {
+  /**
+   * PostHog installs itself on the page - as the loader snippet's array stub
+   * first, then as the real instance. Declaring it here is what lets the rest
+   * of this package read `globalThis.posthog` without asserting a shape.
+   */
+  var posthog: PostHogLike | undefined;
+}
+type PostHogLike = Partial<Pick<PostHog, 'get_session_id' | 'get_distinct_id' | 'get_session_replay_url' | 'getFeatureFlag' | 'sessionRecordingStarted' | 'set_config'>> & {
+  /**
+   * Pre-`sessionRecordingStarted()` fallback. Not part of the public type —
+   * PostHog exposes only `_forceAllowLocalhostNetworkCapture` on this object —
+   * so it is declared here and read defensively, never preferred.
+   */
+  sessionRecording?: {
+    started?: boolean;
+  };
+  config?: Partial<PostHog['config']>;
+};
+//#endregion
+//#region src/compatibility.d.ts
+interface PostHogCompatibilityOptions {
+  /**
+   * The PostHog instance, or a function returning it.
+   *
+   * Defaults to `globalThis.posthog`, which is where the snippet and
+   * `posthog-js` both leave it. An instance passed here is preferred — two
+   * PostHog instances on one page is a real setup and an explicit argument is a
+   * decision — but only while it can answer: hand in the loader snippet's array
+   * stub and this falls back to the global once posthog-js swaps the real
+   * library in over the top of it.
+   */
+  posthog?: PostHogLike | (() => PostHogLike | undefined);
+  /**
+   * Flag keys to stamp on every span as `feature_flag.<key>`, so error rate and
+   * latency can be split by variant in whichever backend receives the spans.
+   *
+   * Named explicitly rather than read wholesale: every flag is another
+   * attribute on every span, and "all of them" is how an analytics convenience
+   * turns into a cardinality bill.
+   */
+  featureFlags?: string[];
+}
+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.
+ */
+/** What a PostHog event property can hold: JSON, since that is what is sent. */
+type PostHogPropertyValue = string | number | boolean | null | undefined | Array<PostHogPropertyValue> | {
+  [key: string]: PostHogPropertyValue;
+};
+interface CaptureResultLike {
+  properties: Record<string, PostHogPropertyValue>;
+  [key: string]: PostHogPropertyValue;
+}
+type BeforeSendLike = (event: CaptureResultLike | null) => CaptureResultLike | null;
+interface AutotelBeforeSendOptions {
+  /**
+   * Build a link to the trace in your own backend.
+   *
+   * Ids correlate; they do not navigate. Whoever reads a PostHog event wants
+   * one click back to the trace, and only the app knows whether that is
+   * Traceway, Grafana, Honeycomb or a local devtools port — so the URL shape
+   * is yours to supply.
+   *
+   * Return `undefined` to add nothing for this event.
+   */
+  traceUrl?: (context: {
+    traceId: string;
+    spanId: string;
+  }) => string | undefined;
+}
+/**
+ * A PostHog `before_send` hook that adds `$trace_id` and `$span_id` from the
+ * span in progress.
+ */
+declare function autotelBeforeSend(options?: AutotelBeforeSendOptions): BeforeSendLike;
+//#endregion
+//#region src/join.d.ts
+/**
+ * Wire PostHog to stamp trace context on its events, and return the span
+ * enricher for the other direction.
+ *
+ * Safe to call more than once, and safe to call on an instance that cannot be
+ * 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 {}
+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 };

package/dist/index.js

@@ -0,0 +1,263 @@
+import { context, trace } from "@opentelemetry/api";
+//#region src/posthog-like.ts
+/**
+* Whether this object can actually answer questions yet.
+*
+* The loader snippet leaves an array on `window.posthog` that queues calls, and
+* posthog-js later *replaces* it with the real instance. An integration holding
+* the array from before the swap holds something that will never answer, so the
+* only useful test is whether the methods are there.
+*/
+function isUsable(posthog) {
+	return typeof posthog?.get_session_id === "function";
+}
+/**
+* Call a PostHog getter without letting the page's analytics break the page's
+* tracing. A stub throws `TypeError`, a partly-initialized instance returns an
+* empty string, and neither is worth an attribute.
+*/
+function readString(fn, receiver) {
+	if (typeof fn !== "function") return void 0;
+	try {
+		const value = fn.call(receiver);
+		return typeof value === "string" && value.length > 0 ? value : void 0;
+	} catch {
+		return;
+	}
+}
+function readSessionId(posthog) {
+	return readString(posthog.get_session_id, posthog);
+}
+function readDistinctId(posthog) {
+	return readString(posthog.get_distinct_id, posthog);
+}
+/**
+* Whether a replay actually exists to link to.
+*
+* `get_session_replay_url()` composes a URL out of the session id whether or
+* not anything was recorded — replay disabled, sampled out, or simply not
+* started yet all still produce a link, and it lands on an empty player. Only
+* an affirmative answer counts, so an instance too old or too stubbed to say
+* produces no link rather than a confident wrong one.
+*/
+function isRecording(posthog) {
+	try {
+		if (typeof posthog.sessionRecordingStarted === "function") return posthog.sessionRecordingStarted() === true;
+		return posthog.sessionRecording?.started === true;
+	} catch {
+		return false;
+	}
+}
+function readReplayUrl(posthog) {
+	if (!isRecording(posthog)) return void 0;
+	const fn = posthog.get_session_replay_url;
+	if (typeof fn !== "function") return void 0;
+	try {
+		const value = fn.call(posthog, { withTimestamp: true });
+		return typeof value === "string" && value.length > 0 ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* An evaluated flag value.
+*
+* `false` is an answer — "this person is not in the variant" — and is kept as a
+* boolean so a query can ask for it. Only `undefined`, meaning PostHog has no
+* opinion yet, is dropped: an attribute that says nothing is worse than an
+* absent one.
+*/
+function readFeatureFlag(posthog, key) {
+	const fn = posthog.getFeatureFlag;
+	if (typeof fn !== "function") return void 0;
+	try {
+		const value = fn.call(posthog, key);
+		if (value === void 0) return void 0;
+		return typeof value === "boolean" ? value : String(value);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/compatibility.ts
+/** `SpanStatusCode.ERROR`, without importing the enum for one comparison. */
+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;
+}
+function resolvePostHog(options) {
+	const configured = typeof options.posthog === "function" ? options.posthog() : options.posthog;
+	if (isUsable(configured)) return configured;
+	const global = globalThis.posthog;
+	return isUsable(global) ? global : void 0;
+}
+function posthogCompatibility(options = {}) {
+	return {
+		/**
+		* Identity is read here, not in `onEnd`, because it is a fact about when
+		* the operation happened. PostHog rotates a session after 30 minutes idle,
+		* and `identify()` can land mid-request; a long span asking at the end
+		* would be filed under whoever the visitor had become by then rather than
+		* who started it.
+		*/
+		onStart(span, _context) {
+			const posthog = resolvePostHog(options);
+			if (!posthog) return;
+			const sessionId = readSessionId(posthog);
+			if (sessionId !== void 0) span.setAttribute("session.id", sessionId);
+			const attributes = span.attributes;
+			const fill = (key, value) => {
+				if (value !== void 0 && attributes[key] === void 0) span.setAttribute(key, value);
+			};
+			fill("user.id", readDistinctId(posthog));
+			for (const key of options.featureFlags ?? []) fill(`feature_flag.${key}`, readFeatureFlag(posthog, key));
+		},
+		/**
+		* Only the replay link is left for the end, because only the end knows
+		* whether the span failed.
+		*/
+		onEnd(span) {
+			if (!failed(span)) return;
+			const posthog = resolvePostHog(options);
+			if (!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;
+			const url = readReplayUrl(posthog);
+			if (url !== void 0) attributes["session.replay.url"] = url;
+		},
+		forceFlush() {
+			return Promise.resolve();
+		},
+		shutdown() {
+			return Promise.resolve();
+		}
+	};
+}
+//#endregion
+//#region src/before-send.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}`,
+*     }),
+*   ],
+* });
+* ```
+*/
+/**
+* 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;
+		if (options.traceUrl && properties["$trace_url"] === void 0) try {
+			const url = options.traceUrl({
+				traceId: spanContext.traceId,
+				spanId: spanContext.spanId
+			});
+			if (url !== void 0) properties["$trace_url"] = url;
+		} catch {}
+		return event;
+	};
+}
+//#endregion
+//#region src/join.ts
+/**
+* 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.
+*/
+const MARKER = "__autotelBeforeSend";
+function existingHooks(posthog) {
+	const current = posthog.config?.before_send;
+	if (Array.isArray(current)) return current;
+	return current ? [current] : [];
+}
+function joinPostHog(posthog, options = {}) {
+	const resolve = () => resolvePostHog({
+		...options,
+		posthog
+	});
+	/**
+	* Returns true once the hook is in place. Kept retryable because the loader
+	* snippet's stub has no `set_config`: giving up at call time would leave
+	* every PostHog event on that page without its trace for the life of the
+	* page, and the real library usually arrives a moment later.
+	*/
+	const wire = () => {
+		try {
+			const instance = resolve();
+			if (!instance) return false;
+			const hooks = existingHooks(instance);
+			if (hooks.some((hook) => hook[MARKER])) return true;
+			if (typeof instance.set_config !== "function") return false;
+			const hook = autotelBeforeSend(options);
+			hook[MARKER] = true;
+			instance.set_config({ before_send: [...hooks, hook] });
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	let wired = wire();
+	const enricher = posthogCompatibility({
+		...options,
+		posthog
+	});
+	return {
+		onStart(span, context) {
+			if (!wired) wired = wire();
+			enricher.onStart(span, context);
+		},
+		onEnd: (span) => enricher.onEnd(span),
+		forceFlush: () => enricher.forceFlush(),
+		shutdown: () => enricher.shutdown()
+	};
+}
+//#endregion
+//#region src/session-id.ts
+/**
+* PostHog's session id, shaped for `autotel-web`'s `session.id` provider.
+*
+* The span enricher covers full mode, where there is an OpenTelemetry pipeline
+* to hang a processor on. The minimal browser build has no such pipeline — it
+* writes spans straight to OTLP — so it takes the id from a function instead,
+* and this is that function:
+*
+* ```ts
+* import { init } from 'autotel-web';
+* import { posthogSessionId } from 'autotel-posthog';
+*
+* init({ service: 'web', session: { id: posthogSessionId } });
+* ```
+*
+* Returns `undefined` when PostHog is absent or not yet initialized, which is
+* the signal for autotel-web to fall back to minting its own id rather than
+* emitting spans with no session at all.
+*/
+function posthogSessionId(posthog) {
+	const instance = posthog ?? globalThis.posthog ?? void 0;
+	return instance ? readSessionId(instance) : void 0;
+}
+//#endregion
+export { autotelBeforeSend, joinPostHog, posthogCompatibility, posthogSessionId };