feat(traces): propagate the inbound sampled flag and parent remoteness

A continued trace now carries the caller's trace-flags byte in both
`traceparent()` and the exported span, rather than always sending `01`,
so a downstream parent-based sampler is not handed a decision this SDK
invented. Exported spans also set OTel's parent-remoteness bits.

Author: turnipdabeets

.changeset/traces-flags-fidelity.md

@@ -0,0 +1,7 @@
+---
+'posthog-node': minor
+'@posthog/core': minor
+'@posthog/types': minor
+---
+
+Propagate the inbound W3C sampled flag on a continued trace instead of always sending `01`, so a downstream parent-based sampler sees the decision the head sampler made. Spans are still recorded and exported either way. Exported spans also carry OpenTelemetry's parent-remoteness bits, so a span that entered the service over HTTP is distinguishable from one started locally.

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

@@ -192,6 +192,40 @@ describe('PostHogTraces', () => {
       expect(sentSpans()[0].traceId).toBe(TRACE_ID)
     })
 
+    it('propagates the sampled-out flag onward rather than upgrading it to 01', async () => {
+      // A downstream parent-based sampler would otherwise record a trace its own
+      // head sampler had already rejected.
+      const traces = createTraces()
+      const span = traces.startSpan('handler', { parent: `00-${TRACE_ID}-${REMOTE_SPAN_ID}-00` })
+      const child = traces.startSpan('inner', { parent: span })
+
+      expect(span.traceparent()!.startsWith(`00-${TRACE_ID}-`)).toBe(true)
+      expect(span.traceparent()!.endsWith('-00')).toBe(true)
+      // The whole chain agrees, not just the span that read the header.
+      expect(child.traceparent()!.endsWith('-00')).toBe(true)
+
+      child.end()
+      span.end()
+      await traces.flush()
+
+      // Recorded and exported all the same, with the wire agreeing with the header.
+      const byName = Object.fromEntries(sentSpans().map((sent) => [sent.name, sent.flags]))
+      expect(byName).toEqual({ handler: 0x300, inner: 0x100 })
+    })
+
+    it('marks a header parent remote and a handle parent local', async () => {
+      const traces = createTraces()
+      const remote = traces.startSpan('handler', { parent: `00-${TRACE_ID}-${REMOTE_SPAN_ID}-01` })
+      const local = traces.startSpan('inner', { parent: remote })
+
+      local.end()
+      remote.end()
+      await traces.flush()
+
+      const byName = Object.fromEntries(sentSpans().map((span) => [span.name, span.flags]))
+      expect(byName).toEqual({ handler: 0x301, inner: 0x101 })
+    })
+
     it('preserves tracestate opaquely and passes it to children', async () => {
       const traces = createTraces()
       const parent = traces.startSpan('handler', {

packages/core/src/traces/index.ts

@@ -53,6 +53,9 @@ interface ParentContext {
   traceId: string
   parentSpanId?: string
   traceState?: string
+  traceFlags?: string
+  /** True when the parent arrived as a `traceparent` header. */
+  isRemote?: boolean
 }
 
 /**
@@ -147,6 +150,8 @@ export class PostHogTraces {
         spanId,
         parentSpanId: parent?.parentSpanId,
         traceState: parent?.traceState,
+        traceFlags: parent?.traceFlags,
+        parentIsRemote: parent?.isRemote,
         name: sanitizeName(name, 'Span name', this._logger),
         kind: options?.kind ?? 'internal',
         // Auto-context first so user-supplied attributes win on collision.
@@ -280,6 +285,8 @@ export class PostHogTraces {
         traceId: remote.traceId,
         parentSpanId: remote.spanId,
         traceState: sanitizeTracestate(options?.tracestate),
+        traceFlags: remote.flags,
+        isRemote: true,
       }
     }
 

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

@@ -12,6 +12,8 @@ const record = (overrides: Partial<SpanRecord> = {}): SpanRecord => ({
   spanId: '00f067aa0ba902b7',
   name: 'checkout',
   kind: 'internal',
+  traceFlags: '01',
+  parentIsRemote: false,
   attributes: {},
   events: [],
   startTime: 1_700_000_000_000,
@@ -77,7 +79,7 @@ describe('OTLP span encoding', () => {
         kind: 1,
         startTimeUnixNano: '1700000000000000000',
         endTimeUnixNano: '1700000000080000000',
-        flags: 1,
+        flags: 0x101,
       })
     })
 
@@ -108,8 +110,22 @@ describe('OTLP span encoding', () => {
       expect(span.events).toEqual([{ name: 'cache miss', timeUnixNano: '1700000000040000000' }])
     })
 
-    it('always sets the sampled trace flag', () => {
-      expect(buildOtlpSpan(record()).flags).toBe(1)
+    it('sets the sampled bit and marks a local parent as known-not-remote', () => {
+      expect(buildOtlpSpan(record()).flags).toBe(0x101)
+    })
+
+    it('marks a parent that arrived as a header as remote', () => {
+      expect(buildOtlpSpan(record({ parentSpanId: 'b7ad6b7169203331', parentIsRemote: true })).flags).toBe(0x301)
+    })
+
+    it('propagates an inbound sampled-out flag rather than overriding it', () => {
+      // The span is still recorded and exported; what the wire says is the
+      // decision the head sampler made.
+      expect(buildOtlpSpan(record({ traceFlags: '00', parentIsRemote: true })).flags).toBe(0x300)
+    })
+
+    it('falls back to sampled when the flags byte is unusable', () => {
+      expect(buildOtlpSpan(record({ traceFlags: 'zz' })).flags).toBe(0x101)
     })
   })
 
@@ -232,7 +248,7 @@ describe('OTLP span encoding', () => {
                     kind: 2,
                     startTimeUnixNano: '1700000000000000000',
                     endTimeUnixNano: '1700000000080000000',
-                    flags: 1,
+                    flags: 0x101,
                     attributes: [
                       { key: 'posthogDistinctId', value: { stringValue: 'user-123' } },
                       { key: 'sessionId', value: { stringValue: 'session-123' } },

packages/core/src/traces/otlp.ts

@@ -26,8 +26,24 @@ const SPAN_STATUS_TO_OTLP: Record<SpanStatusCode, number> = {
   error: 2,
 }
 
-/** W3C trace flags: the sampled bit, always set because every captured span is recorded. */
-const TRACE_FLAGS_SAMPLED = 1
+/** W3C trace flags live in the low byte; the sampled bit is `0x01`. */
+const TRACE_FLAGS_SAMPLED = 0x01
+// OTel's span flags, above the W3C byte: one bit says the parent's remoteness is
+// known, the other says it is remote. Both unset reads as "unknown", which this
+// SDK never has to say — a string parent is remote, a handle parent is local.
+const SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE = 0x100
+const SPAN_FLAGS_CONTEXT_IS_REMOTE = 0x200
+
+/**
+ * The `flags` field for a span: its W3C trace-flags byte, plus OTel's
+ * parent-remoteness bits. Nothing reads the remoteness today, but a span
+ * exported without it can never be backfilled with it.
+ */
+function spanFlags(record: SpanRecord): number {
+  const traceFlags = parseInt(record.traceFlags, 16)
+  const w3c = Number.isFinite(traceFlags) ? traceFlags & 0xff : TRACE_FLAGS_SAMPLED
+  return w3c | SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE | (record.parentIsRemote ? SPAN_FLAGS_CONTEXT_IS_REMOTE : 0)
+}
 
 /**
  * Every free-text string this encoder puts on the wire. A lone surrogate survives
@@ -97,7 +113,7 @@ export function buildOtlpSpan(record: SpanRecord, logger?: Logger): OtlpSpan {
     kind: spanKindToOtlp(record.kind),
     startTimeUnixNano: msToUnixNanoString(record.startTime),
     endTimeUnixNano: msToUnixNanoString(record.endTime),
-    flags: TRACE_FLAGS_SAMPLED,
+    flags: spanFlags(record),
   }
   if (record.parentSpanId) {
     span.parentSpanId = record.parentSpanId

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

@@ -309,11 +309,21 @@ describe('PostHogSpan', () => {
       expect(createSpan({ traceState: 'vendor=abc' }).tracestate()).toBe('vendor=abc')
     })
 
+    it('propagates the trace flags it was started with', () => {
+      expect(createSpan({ traceFlags: '00' }).traceparent()).toBe(`00-${TRACE_ID}-${SPAN_ID}-00`)
+      expect(createSpan().traceparent()).toBe(`00-${TRACE_ID}-${SPAN_ID}-01`)
+    })
+
+    it('hands a child the flags it propagates, so the whole chain agrees', () => {
+      expect(createSpan({ traceFlags: '00' }).childContext().traceFlags).toBe('00')
+    })
+
     it('exposes a child context carrying its own span id as the parent', () => {
       expect(createSpan({ traceState: 'vendor=abc' }).childContext()).toEqual({
         traceId: TRACE_ID,
         parentSpanId: SPAN_ID,
         traceState: 'vendor=abc',
+        traceFlags: '01',
       })
     })
   })

packages/core/src/traces/span.ts

@@ -1,7 +1,7 @@
 import type { Span, SpanAttributes, SpanAttributeValue, SpanKind, SpanStatusCode, SpanTimeInput } from '@posthog/types'
 import type { Logger } from '../types'
 import type { SpanEventRecord, SpanRecord } from './types'
-import { formatTraceparent, normalizeTraceparent, sanitizeTracestate } from './traceparent'
+import { formatTraceparent, normalizeTraceparent, sanitizeTracestate, TRACE_FLAGS_SAMPLED } from './traceparent'
 import { assignUserAttributes, clampEndTime, resolveSuppliedTime, sanitizeName } from './sanitize'
 import { isError } from '../utils'
 
@@ -19,6 +19,10 @@ export interface SpanInit {
   spanId: string
   parentSpanId?: string
   traceState?: string
+  /** The trace-flags byte to propagate; the inbound one when continuing a remote trace. */
+  traceFlags?: string
+  /** True when the parent came from a `traceparent` header rather than a local handle. */
+  parentIsRemote?: boolean
   name: string
   kind: SpanKind
   attributes: SpanAttributes
@@ -33,6 +37,8 @@ export class PostHogSpan implements Span {
   private readonly _spanId: string
   private readonly _parentSpanId?: string
   private readonly _traceState?: string
+  private readonly _traceFlags: string
+  private readonly _parentIsRemote: boolean
   private readonly _startTime: number
   // Absent on backdated spans and on platforms with no monotonic source.
   private readonly _startMono?: number
@@ -53,6 +59,8 @@ export class PostHogSpan implements Span {
     this._spanId = init.spanId
     this._parentSpanId = init.parentSpanId
     this._traceState = init.traceState
+    this._traceFlags = init.traceFlags ?? TRACE_FLAGS_SAMPLED
+    this._parentIsRemote = init.parentIsRemote ?? false
     this._name = init.name
     this._kind = init.kind
     this._attributes = init.attributes
@@ -147,16 +155,22 @@ export class PostHogSpan implements Span {
   }
 
   traceparent(): string | null {
-    return formatTraceparent(this._traceId, this._spanId)
+    return formatTraceparent(this._traceId, this._spanId, this._traceFlags)
   }
 
   tracestate(): string | null {
     return this._traceState ?? null
   }
 
   /** Context a child span inherits when this handle is its parent. */
-  childContext(): { traceId: string; parentSpanId: string; traceState?: string } {
-    return { traceId: this._traceId, parentSpanId: this._spanId, traceState: this._traceState }
+  childContext(): { traceId: string; parentSpanId: string; traceState?: string; traceFlags: string } {
+    return {
+      traceId: this._traceId,
+      parentSpanId: this._spanId,
+      traceState: this._traceState,
+      // A child of a continued trace keeps propagating the caller's decision.
+      traceFlags: this._traceFlags,
+    }
   }
 
   end(endTime?: SpanTimeInput): void {
@@ -174,6 +188,8 @@ export class PostHogSpan implements Span {
       spanId: this._spanId,
       ...(this._parentSpanId && { parentSpanId: this._parentSpanId }),
       ...(this._traceState && { traceState: this._traceState }),
+      traceFlags: this._traceFlags,
+      parentIsRemote: this._parentIsRemote,
       name: this._name,
       kind: this._kind,
       ...(this._status && { status: this._status }),

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

@@ -6,26 +6,37 @@ const SPAN_ID = '00f067aa0ba902b7'
 describe('traceparent', () => {
   describe('parseTraceparent', () => {
     it('parses a sampled header', () => {
-      expect(parseTraceparent(`00-${TRACE_ID}-${SPAN_ID}-01`)).toEqual({ traceId: TRACE_ID, spanId: SPAN_ID })
+      expect(parseTraceparent(`00-${TRACE_ID}-${SPAN_ID}-01`)).toEqual({
+        traceId: TRACE_ID,
+        spanId: SPAN_ID,
+        flags: '01',
+      })
     })
 
-    it('continues the trace even when the caller sampled it out', () => {
-      // Every captured span is recorded, so honouring an inbound `00` would
-      // orphan our own spans rather than save anything.
-      expect(parseTraceparent(`00-${TRACE_ID}-${SPAN_ID}-00`)).toEqual({ traceId: TRACE_ID, spanId: SPAN_ID })
+    it('continues the trace even when the caller sampled it out, and keeps the flag', () => {
+      // Every captured span is recorded, so honouring an inbound `00` by
+      // dropping the parentage would orphan our own spans. The flag itself is
+      // kept, so what we propagate onward still says what the caller decided.
+      expect(parseTraceparent(`00-${TRACE_ID}-${SPAN_ID}-00`)).toEqual({
+        traceId: TRACE_ID,
+        spanId: SPAN_ID,
+        flags: '00',
+      })
     })
 
     it('accepts a future version with extra fields', () => {
       expect(parseTraceparent(`01-${TRACE_ID}-${SPAN_ID}-01-something`)).toEqual({
         traceId: TRACE_ID,
         spanId: SPAN_ID,
+        flags: '01',
       })
     })
 
     it('normalizes case and surrounding whitespace', () => {
       expect(parseTraceparent(`  00-${TRACE_ID.toUpperCase()}-${SPAN_ID.toUpperCase()}-01 `)).toEqual({
         traceId: TRACE_ID,
         spanId: SPAN_ID,
+        flags: '01',
       })
     })
 
@@ -45,12 +56,20 @@ describe('traceparent', () => {
   })
 
   describe('formatTraceparent', () => {
-    it('always sets the sampled flag', () => {
+    it('sets the sampled flag on a trace started here', () => {
       expect(formatTraceparent(TRACE_ID, SPAN_ID)).toBe(`00-${TRACE_ID}-${SPAN_ID}-01`)
     })
 
+    it('propagates the flags byte it was given', () => {
+      expect(formatTraceparent(TRACE_ID, SPAN_ID, '00')).toBe(`00-${TRACE_ID}-${SPAN_ID}-00`)
+    })
+
     it('round-trips through the parser', () => {
-      expect(parseTraceparent(formatTraceparent(TRACE_ID, SPAN_ID))).toEqual({ traceId: TRACE_ID, spanId: SPAN_ID })
+      expect(parseTraceparent(formatTraceparent(TRACE_ID, SPAN_ID))).toEqual({
+        traceId: TRACE_ID,
+        spanId: SPAN_ID,
+        flags: '01',
+      })
     })
   })
 

packages/core/src/traces/traceparent.ts

@@ -3,6 +3,8 @@ import { isValidSpanId, isValidTraceId } from './ids'
 export interface RemoteSpanContext {
   traceId: string
   spanId: string
+  /** The inbound trace-flags byte, e.g. `01` sampled, `00` sampled out. */
+  flags: string
 }
 
 // `00-<32 hex>-<16 hex>-<2 hex>`. Version `ff` is invalid per the spec; other
@@ -13,13 +15,13 @@ const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2
  * Parses an incoming `traceparent` header value, returning `undefined` for
  * anything malformed so a bad header starts a fresh root rather than throwing.
  *
- * Incoming trace flags are deliberately ignored: we continue the trace even when
- * the caller sampled it out (`00`), because PostHog records every captured span
- * and dropping the parentage would orphan our own spans.
+ * A trace the caller sampled out (`00`) is still continued — PostHog records
+ * every captured span — but the inbound flag rides along, so what this SDK
+ * propagates onward says what the caller decided rather than overriding it.
  */
 export function parseTraceparent(value: unknown): RemoteSpanContext | undefined {
   const fields = matchTraceparent(value)
-  return fields && { traceId: fields.traceId, spanId: fields.spanId }
+  return fields && { traceId: fields.traceId, spanId: fields.spanId, flags: fields.flags }
 }
 
 interface TraceparentFields {
@@ -57,12 +59,17 @@ export function normalizeTraceparent(value: unknown): string | undefined {
   return fields && `${fields.version}-${fields.traceId}-${fields.spanId}-${fields.flags}`
 }
 
+/** The W3C sampled bit, set on a trace this SDK started. */
+export const TRACE_FLAGS_SAMPLED = '01'
+
 /**
- * Builds the `traceparent` header value for a span. The sampled flag is always
- * set, because a span we exported is by definition recorded.
+ * Builds the `traceparent` header value for a span. A span continuing a remote
+ * trace propagates the flags byte it was handed: a downstream parent-based
+ * sampler must see the decision the head sampler actually made, not one this
+ * SDK invented. A trace started here is sampled, because it is recorded.
  */
-export function formatTraceparent(traceId: string, spanId: string): string {
-  return `00-${traceId}-${spanId}-01`
+export function formatTraceparent(traceId: string, spanId: string, flags: string = TRACE_FLAGS_SAMPLED): string {
+  return `00-${traceId}-${spanId}-${flags}`
 }
 
 // tracestate is a comma-separated list of at most 32 `key=value` members, and

packages/core/src/traces/types.ts

@@ -64,6 +64,10 @@ export interface SpanRecord {
   spanId: string
   parentSpanId?: string
   traceState?: string
+  /** The W3C trace-flags byte this span propagates, e.g. `01` sampled. */
+  traceFlags: string
+  /** True when the parent came from a `traceparent` header rather than a local handle. */
+  parentIsRemote: boolean
   name: string
   kind: SpanKind
   status?: { code: SpanStatusCode; message?: string }