feat(node): distributed tracing spans

.changeset/node-distributed-tracing.md

@@ -0,0 +1,9 @@
+---
+'posthog-node': minor
+'@posthog/core': minor
+'@posthog/types': minor
+---
+
+Add distributed tracing to posthog-node behind a new `traces` client option. `withSpan` / `startSpan` / `getActiveSpan` create OpenTelemetry-shaped spans that export to PostHog with no OpenTelemetry dependency, and spans created inside a request context automatically carry `posthogDistinctId` and `sessionId` so traces link back to people and sessions. Tracing stays off until `traces` is configured, and the API is marked `@experimental` while PostHog's tracing product is in beta.
+
+Spans, logs and metrics now share one OTLP attribute encoder, so a `bigint` attribute is sent as an int64 rather than a plain string, and an attribute whose getter throws costs only that key instead of the whole record.

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

@@ -23,9 +23,8 @@ export {
   buildResourceAttributes,
   getOtlpSeverityNumber,
   getOtlpSeverityText,
-  toOtlpAnyValue,
-  toOtlpKeyValueList,
 } from './logs/logs-utils'
+export { toOtlpAnyValue, toOtlpKeyValueList } from './utils/otlp-any-value'
 export { PostHogLogs } from './logs'
 export type {
   BeforeSendLogFn,
@@ -68,6 +67,30 @@ export type {
   Metrics,
   MetricsConfig,
 } from './metrics/types'
+export { PostHogTraces } from './traces'
+export { SyncSpanContextManager } from './traces/context'
+export { NOOP_SPAN } from './traces/span'
+// The OTLP builders are exported for host adapters that bypass the core flush
+// path, mirroring what the logs module exposes for the browser's beacon drain.
+export { buildOtlpSpan, buildOtlpTracesPayload, buildTracesResourceAttributes } from './traces/otlp'
+export type {
+  ResolvedTracesConfig,
+  SendTracesBatchOutcome,
+  SpanContextManager,
+  TraceSdkContext,
+  TracesHost,
+} 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'