feat(node): distributed tracing spans

Adds startSpan, withSpan and getActiveSpan to posthog-node behind a new
traces client option, encoding spans as OTLP JSON without an OpenTelemetry
dependency.

Author: turnipdabeets

.changeset/node-distributed-tracing.md

@@ -0,0 +1,7 @@
+---
+'posthog-node': minor
+'@posthog/core': minor
+'@posthog/types': minor
+---
+
+Add distributed tracing to `posthog-node`: `withSpan`, `startSpan` and `getActiveSpan`, enabled by a new `traces` client option. `IPostHog` gains these three members, so anything implementing that interface (hand-written test doubles, DI wrappers) needs them added.

packages/core/package.json

@@ -43,7 +43,7 @@
     "lint:fix": "eslint src --fix",
     "build": "rslib build",
     "dev": "rslib build -w",
-    "test:unit": "jest",
+    "test:unit": "NODE_OPTIONS=--expose-gc jest",
     "package": "pnpm pack --out $PACKAGE_DEST/%s.tgz"
   },
   "exports": {

packages/core/src/__tests__/posthog.flush.spec.ts

@@ -762,11 +762,12 @@ describe('PostHog Core', () => {
   })
 
   describe('OTLP batch senders', () => {
-    // Both share one `_sendOtlpBatch`; the table pins them to the same
+    // All three share one `_sendOtlpBatch`; the table pins them to the same
     // classification so a wrapper can't reintroduce a per-signal retry policy.
     const senders = {
       logs: (client: PostHogCoreTestClient) => client._sendLogsBatch({ resourceLogs: [] }),
       metrics: (client: PostHogCoreTestClient) => client._sendMetricsBatch({ resourceMetrics: [] }),
+      traces: (client: PostHogCoreTestClient) => client._sendTracesBatch({ resourceSpans: [] }),
     }
 
     const cases: [number, string][] = [

packages/core/src/index.ts

@@ -86,6 +86,21 @@ export type {
   Metrics,
   MetricsConfig,
 } from './metrics/types'
+export { PostHogTraces } from './traces'
+export { SyncSpanContextManager } from './traces/context'
+export { NOOP_SPAN } from './traces/span'
+export type { ResolvedTracesConfig, SpanContextManager, TraceSdkContext } from './traces/types'
+// Same barrel convention as logs and metrics for the user-facing tracing types.
+export type {
+  Span,
+  SpanAttributes,
+  SpanAttributeValue,
+  SpanKind,
+  SpanStatusCode,
+  SpanTimeInput,
+  StartSpanOptions,
+  TracesConfig,
+} from './traces/types'
 export { uuidv7 } from './vendor/uuidv7'
 export * from './cookie'
 export * from './posthog-core'

packages/core/src/posthog-core-stateless.ts

@@ -1,5 +1,6 @@
-import type { OtlpLogsPayload, OtlpMetricsPayload } from '@posthog/types'
+import type { OtlpLogsPayload, OtlpMetricsPayload, OtlpTracesPayload } from '@posthog/types'
 import type { SendMetricsBatchOutcome } from './metrics/types'
+import type { SendTracesBatchOutcome } from './traces/types'
 import { SimpleEventEmitter } from './eventemitter'
 import { getFeatureFlagValue, minimizeFlagCalledEventProperties, normalizeFlagsResponse } from './featureFlagUtils'
 import { gzipCompress, isGzipSupported } from './gzip'
@@ -238,8 +239,8 @@ export type SendLogsBatchOutcome =
 
 /**
  * Each signal keeps its own exported outcome type because each belongs to a
- * separate host contract. The wrappers return this value directly, so one
- * drifting out of shape fails to compile.
+ * separate host contract. The wrappers return this value directly, so any of
+ * the three drifting out of shape fails to compile.
  */
 type SendOtlpBatchOutcome =
   | { kind: 'ok' }
@@ -1642,9 +1643,9 @@ export abstract class PostHogCoreStateless {
   }
 
   /**
-   * Shared implementation behind the OTLP senders, which differ only in path.
-   * Returns a tagged outcome instead of throwing so the queue owners don't
-   * have to know the core's error class hierarchy.
+   * Shared implementation behind the three OTLP senders, which differ only in
+   * path and auth style. Returns a tagged outcome instead of throwing so the
+   * queue owners don't have to know the core's error class hierarchy.
    *
    * Exhausted 408/429/5xx stay `retry-later`, unlike the events `_flush()`
    * which drops anything that isn't a network error: every OTLP queue is
@@ -1653,24 +1654,30 @@ export abstract class PostHogCoreStateless {
    */
   private async _sendOtlpBatch({
     path,
+    auth,
     payload,
   }: {
-    path: 'logs' | 'metrics'
-    payload: OtlpLogsPayload | OtlpMetricsPayload
+    path: 'logs' | 'metrics' | 'traces'
+    auth: 'query-token' | 'bearer'
+    payload: OtlpLogsPayload | OtlpMetricsPayload | OtlpTracesPayload
   }): Promise<SendOtlpBatchOutcome> {
     if (this.disabled) {
       return { kind: 'fatal', error: new Error('The client is disabled') }
     }
 
     const serialized = JSON.stringify(payload)
-    const url = `${this.host}/i/v1/${path}?token=${encodeURIComponent(this.apiKey)}`
+    const url =
+      auth === 'bearer'
+        ? `${this.host}/i/v1/${path}`
+        : `${this.host}/i/v1/${path}?token=${encodeURIComponent(this.apiKey)}`
 
     const gzippedPayload = !this.disableCompression ? await this.compressPayload(serialized) : null
     const fetchOptions: PostHogFetchOptions = {
       method: 'POST',
       headers: {
         ...this.getCustomHeaders(),
         'Content-Type': 'application/json',
+        ...(auth === 'bearer' && { Authorization: `Bearer ${this.apiKey}` }),
         ...(gzippedPayload !== null && { 'Content-Encoding': 'gzip' }),
       },
       body: gzippedPayload || serialized,
@@ -1703,11 +1710,23 @@ export abstract class PostHogCoreStateless {
   }
 
   async _sendLogsBatch(payload: OtlpLogsPayload): Promise<SendLogsBatchOutcome> {
-    return this._sendOtlpBatch({ path: 'logs', payload })
+    return this._sendOtlpBatch({ path: 'logs', auth: 'query-token', payload })
   }
 
   async _sendMetricsBatch(payload: OtlpMetricsPayload): Promise<SendMetricsBatchOutcome> {
-    return this._sendOtlpBatch({ path: 'metrics', payload })
+    return this._sendOtlpBatch({ path: 'metrics', auth: 'query-token', payload })
+  }
+
+  /**
+   * The `TracesHost._sendTracesBatch` implementation, so `PostHogTraces` can
+   * use any core-based SDK as its host.
+   *
+   * Authenticates with `Authorization: Bearer` rather than the `?token=` query
+   * parameter the logs and metrics senders use: it's the service's primary auth
+   * path, and server runtimes have no CORS preflight to avoid.
+   */
+  async _sendTracesBatch(payload: OtlpTracesPayload): Promise<SendTracesBatchOutcome> {
+    return this._sendOtlpBatch({ path: 'traces', auth: 'bearer', payload })
   }
 
   private fetchWithRetry<T>(

packages/core/src/traces/context.ts

@@ -0,0 +1,28 @@
+import type { Span } from '@posthog/types'
+import type { SpanContextManager } from './types'
+
+/**
+ * Synchronous active-span tracking: restores the previous active span when the
+ * callback returns, which for an async callback means when it returns its
+ * promise — so spans started after an `await` won't see it as active.
+ *
+ * The fallback for runtimes with no ambient async context; Node injects an
+ * `AsyncLocalStorage`-backed manager instead. `parent` is the escape hatch.
+ */
+export class SyncSpanContextManager implements SpanContextManager {
+  private _active: Span | undefined
+
+  active(): Span | undefined {
+    return this._active
+  }
+
+  with<T>(span: Span, fn: () => T): T {
+    const previous = this._active
+    this._active = span
+    try {
+      return fn()
+    } finally {
+      this._active = previous
+    }
+  }
+}

packages/core/src/traces/ids.spec.ts

@@ -0,0 +1,115 @@
+import { getRandomBytes, isValidSpanId, isValidTraceId, newSpanId, newTraceId } from './ids'
+
+describe('trace and span ids', () => {
+  describe('newTraceId', () => {
+    it('is 32 lowercase hex characters', () => {
+      for (let i = 0; i < 50; i++) {
+        expect(newTraceId()).toMatch(/^[0-9a-f]{32}$/)
+      }
+    })
+
+    it('is never all zeros', () => {
+      for (let i = 0; i < 50; i++) {
+        expect(newTraceId()).not.toBe('0'.repeat(32))
+      }
+    })
+
+    it('does not repeat', () => {
+      const ids = new Set(Array.from({ length: 200 }, newTraceId))
+      expect(ids.size).toBe(200)
+    })
+  })
+
+  describe('newSpanId', () => {
+    it('is 16 lowercase hex characters', () => {
+      for (let i = 0; i < 50; i++) {
+        expect(newSpanId()).toMatch(/^[0-9a-f]{16}$/)
+      }
+    })
+
+    it('does not repeat', () => {
+      const ids = new Set(Array.from({ length: 200 }, newSpanId))
+      expect(ids.size).toBe(200)
+    })
+  })
+
+  describe('getRandomBytes', () => {
+    it('returns the requested length', () => {
+      expect(getRandomBytes(8)).toHaveLength(8)
+      expect(getRandomBytes(16)).toHaveLength(16)
+    })
+
+    it('falls back to Math.random when crypto is unavailable', () => {
+      const original = Object.getOwnPropertyDescriptor(globalThis, 'crypto')
+      // React Native has no global crypto without a polyfill — the fallback path
+      // is what keeps span ids working there.
+      Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+      try {
+        expect(newTraceId()).toMatch(/^[0-9a-f]{32}$/)
+        expect(newSpanId()).toMatch(/^[0-9a-f]{16}$/)
+      } finally {
+        if (original) {
+          Object.defineProperty(globalThis, 'crypto', original)
+        }
+      }
+    })
+
+    it('falls back when getRandomValues throws', () => {
+      const original = Object.getOwnPropertyDescriptor(globalThis, 'crypto')
+      Object.defineProperty(globalThis, 'crypto', {
+        value: {
+          getRandomValues: () => {
+            throw new Error('not allowed')
+          },
+        },
+        configurable: true,
+      })
+      try {
+        expect(newTraceId()).toMatch(/^[0-9a-f]{32}$/)
+      } finally {
+        if (original) {
+          Object.defineProperty(globalThis, 'crypto', original)
+        }
+      }
+    })
+
+    it('never emits an all-zero id even when the random source is broken', () => {
+      const original = Object.getOwnPropertyDescriptor(globalThis, 'crypto')
+      Object.defineProperty(globalThis, 'crypto', {
+        value: { getRandomValues: (array: Uint8Array) => array.fill(0) },
+        configurable: true,
+      })
+      try {
+        // The server zeroes ids it can't use, so an all-zero id would be stored
+        // and silently orphaned rather than rejected.
+        expect(newTraceId()).not.toBe('0'.repeat(32))
+        expect(newSpanId()).not.toBe('0'.repeat(16))
+      } finally {
+        if (original) {
+          Object.defineProperty(globalThis, 'crypto', original)
+        }
+      }
+    })
+  })
+
+  describe('validation', () => {
+    it.each([
+      ['a valid trace id', '4bf92f3577b34da6a3ce929d0e0e4736', true],
+      ['an all-zero trace id', '0'.repeat(32), false],
+      ['a short trace id', 'abc', false],
+      ['uppercase hex', '4BF92F3577B34DA6A3CE929D0E0E4736', false],
+      ['a non-hex string', 'zzf92f3577b34da6a3ce929d0e0e4736', false],
+      ['a non-string', 12345, false],
+    ])('isValidTraceId rejects/accepts %s', (_name, value, expected) => {
+      expect(isValidTraceId(value)).toBe(expected)
+    })
+
+    it.each([
+      ['a valid span id', '00f067aa0ba902b7', true],
+      ['an all-zero span id', '0'.repeat(16), false],
+      ['a trace-length id', '4bf92f3577b34da6a3ce929d0e0e4736', false],
+    ])('isValidSpanId rejects/accepts %s', (_name, value, expected) => {
+      expect(isValidSpanId(value)).toBe(expected)
+    })
+  })
+})

packages/core/src/traces/ids.ts

@@ -0,0 +1,73 @@
+// W3C Trace Context identifier generation. Trace ids are 16 bytes, span ids 8,
+// both lowercase hex on the JSON wire. The ingestion service *zeroes* ids that
+// aren't exactly the right length rather than rejecting them, silently orphaning
+// the span — so length is load-bearing and every id is validated before it ships.
+
+const TRACE_ID_BYTES = 16
+const SPAN_ID_BYTES = 8
+
+const TRACE_ID_HEX = TRACE_ID_BYTES * 2
+const SPAN_ID_HEX = SPAN_ID_BYTES * 2
+
+const INVALID_TRACE_ID = '0'.repeat(TRACE_ID_HEX)
+const INVALID_SPAN_ID = '0'.repeat(SPAN_ID_HEX)
+
+const HEX_RE = /^[0-9a-f]+$/
+
+type CryptoLike = { getRandomValues?: (array: Uint8Array) => Uint8Array }
+
+/**
+ * Random bytes from the platform's CSPRNG, falling back to `Math.random`.
+ *
+ * The fallback exists for React Native, which has no global `crypto` without a
+ * polyfill. Trace ids need collision resistance, not unpredictability.
+ */
+export function getRandomBytes(byteLength: number): Uint8Array {
+  const bytes = new Uint8Array(byteLength)
+  const cryptoLike = (globalThis as { crypto?: CryptoLike }).crypto
+  if (cryptoLike && typeof cryptoLike.getRandomValues === 'function') {
+    try {
+      cryptoLike.getRandomValues(bytes)
+      return bytes
+    } catch {}
+  }
+  for (let i = 0; i < byteLength; i++) {
+    bytes[i] = Math.floor(Math.random() * 256)
+  }
+  return bytes
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let hex = ''
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0')
+  }
+  return hex
+}
+
+function randomHexId(byteLength: number): string {
+  const hex = bytesToHex(getRandomBytes(byteLength))
+  // An all-zero id is invalid per W3C and the server treats one as absent, so the
+  // span would be stored and silently orphaned. Only reachable from a broken source.
+  return /[^0]/.test(hex) ? hex : hex.slice(0, -1) + '1'
+}
+
+export function newTraceId(): string {
+  return randomHexId(TRACE_ID_BYTES)
+}
+
+export function newSpanId(): string {
+  return randomHexId(SPAN_ID_BYTES)
+}
+
+function isValidHexId(value: unknown, length: number, invalid: string): value is string {
+  return typeof value === 'string' && value.length === length && value !== invalid && HEX_RE.test(value)
+}
+
+export function isValidTraceId(value: unknown): value is string {
+  return isValidHexId(value, TRACE_ID_HEX, INVALID_TRACE_ID)
+}
+
+export function isValidSpanId(value: unknown): value is string {
+  return isValidHexId(value, SPAN_ID_HEX, INVALID_SPAN_ID)
+}