feat(node): distributed tracing spans

.changeset/metrics-resource-attribute-getters.md

@@ -0,0 +1,6 @@
+---
+'posthog-node': patch
+'@posthog/core': patch
+---
+
+Stop a throwing getter in `metrics.resourceAttributes` from breaking every metrics export — the key is recorded as `[Unserializable]` instead.

.changeset/node-distributed-tracing.md

@@ -0,0 +1,7 @@
+---
+'posthog-node': minor
+'@posthog/core': minor
+'@posthog/types': minor
+---
+
+Add experimental distributed tracing to `posthog-node`: `startSpan`, `withSpan` and `getActiveSpan` record spans against a new `traces` client option. A service with tracing off still forwards an inbound `traceparent`, including from spans nested inside the one that received it, so a distributed trace is not severed. A `traceparent` may be passed as the one-element array `req.headersDistinct` gives. A `beforeSpanSend` hook sees every span before it is exported and may edit or drop it, and `maxAttributesPerSpan`, `maxEventsPerSpan`, `maxAttributeValueLength`, `maxLiveSpans` and `maxSpanAgeMs` bound what a single span and a single process may hold.

packages/core/package.json

@@ -43,7 +43,7 @@
     "lint:fix": "oxlint --report-unused-disable-directives-severity error src --fix",
     "build": "rslib build",
     "dev": "rslib build -w",
-    "test:unit": "vitest run",
+    "test:unit": "NODE_OPTIONS=--expose-gc vitest run",
     "package": "pnpm pack --out $PACKAGE_DEST/%s.tgz"
   },
   "exports": {

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

@@ -761,11 +761,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/__tests__/posthog.otlp-auth.spec.ts

@@ -0,0 +1,49 @@
+import { createTestClient, PostHogCoreTestClient, PostHogCoreTestClientMocks } from '@/testing'
+
+// One `_sendOtlpBatch` serves logs, metrics and traces, and the endpoint each one
+// authenticates against is a single argument away from the wrong scheme. These pin
+// all three so a flipped argument fails here rather than shipping the project key
+// in a header the logs endpoint does not expect.
+describe('OTLP batch auth', () => {
+  let posthog: PostHogCoreTestClient
+  let mocks: PostHogCoreTestClientMocks
+
+  beforeEach(() => {
+    ;[posthog, mocks] = createTestClient('TEST_API_KEY', {
+      host: 'http://example.com',
+      preloadFeatureFlags: false,
+      disableCompression: true,
+    })
+    mocks.fetch.mockResolvedValue({
+      status: 200,
+      text: () => Promise.resolve('ok'),
+      json: () => Promise.resolve({ status: 'ok' }),
+    })
+  })
+
+  const lastCall = (): [string, any] => mocks.fetch.mock.calls[mocks.fetch.mock.calls.length - 1] as [string, any]
+
+  it('sends logs to the query-token endpoint with no Authorization header', async () => {
+    await posthog._sendLogsBatch({ resourceLogs: [] } as any)
+
+    const [url, options] = lastCall()
+    expect(url).toBe('http://example.com/i/v1/logs?token=TEST_API_KEY')
+    expect(options.headers).not.toHaveProperty('Authorization')
+  })
+
+  it('sends metrics to the query-token endpoint with no Authorization header', async () => {
+    await posthog._sendMetricsBatch({ resourceMetrics: [] } as any)
+
+    const [url, options] = lastCall()
+    expect(url).toBe('http://example.com/i/v1/metrics?token=TEST_API_KEY')
+    expect(options.headers).not.toHaveProperty('Authorization')
+  })
+
+  it('sends traces with bearer auth and no token in the query string', async () => {
+    await posthog._sendTracesBatch({ resourceSpans: [] } as any)
+
+    const [url, options] = lastCall()
+    expect(url).toBe('http://example.com/i/v1/traces')
+    expect(options.headers.Authorization).toBe('Bearer TEST_API_KEY')
+  })
+})

packages/core/src/index.ts

@@ -87,6 +87,24 @@ export type {
   Metrics,
   MetricsConfig,
 } from './metrics/types'
+export { PostHogTraces } from './traces'
+export { SyncSpanContextManager } from './traces/context'
+export { inertSpan, runWithActiveSpan } from './traces/span'
+export { resolveTracesConfig } from './traces/config'
+export type { ResolvedTracesConfig, SpanContextManager, TraceSdkContext } from './traces/types'
+// The `beforeSpanSend` shapes come straight from @posthog/types: hooks see the
+// public record, not core's internal one, which also carries `traceState`.
+export type { SpanRecord, BeforeSpanSendFn } from '@posthog/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>(