@zuplo/cli 7.7.7 → 7.7.9

package/node_modules/@posthog/core/src/traces/live-spans.spec.ts

@@ -0,0 +1,69 @@
+import { PostHogTraces } from './index'
+import { SyncSpanContextManager } from './context'
+import type { ResolvedTracesConfig } from './types'
+import type { Logger } from '../types'
+
+// Live-span accounting keeps an id and a timestamp per span, never the span, so a
+// handle the caller drops stays collectable. This probe is what stops a later
+// change from turning that accounting into a registry of span objects.
+const gc = (globalThis as { gc?: () => void }).gc
+
+// `--expose-gc` is set by the `test:unit` script. A runner that invokes vitest
+// directly has no `gc`, and a probe that cannot force a collection proves nothing.
+const itWithGc = gc ? it : process.env.CI ? it : it.skip
+
+describe('live spans', () => {
+  const config: ResolvedTracesConfig = {
+    serviceName: 'svc',
+    flushIntervalMs: 5000,
+    maxExportBatchSize: 512,
+    maxQueueSize: 2048,
+    maxLiveSpans: 10000,
+    maxSpanAgeMs: 3600000,
+    beforeSpanSend: [],
+    maxAttributesPerSpan: 128,
+    maxEventsPerSpan: 128,
+    maxAttributesPerEvent: 128,
+    maxAttributeValueLength: 8192,
+  }
+
+  const createTraces = (): PostHogTraces =>
+    new PostHogTraces(
+      {
+        isDisabled: false,
+        optedOut: false,
+        getLibraryId: () => 'posthog-core',
+        getLibraryVersion: () => '0.0.0',
+        _sendTracesBatch: async () => ({ kind: 'ok' }),
+      },
+      config,
+      { debug: vi.fn(), warn: vi.fn() } as unknown as Logger,
+      () => ({}),
+      new SyncSpanContextManager()
+    )
+
+  itWithGc('does not retain spans that never end', async () => {
+    if (!gc) {
+      throw new Error('Run this suite with NODE_OPTIONS=--expose-gc; see packages/core test:unit')
+    }
+    vi.useRealTimers()
+    try {
+      const traces = createTraces()
+      // Started in their own frame so the handles are unreachable once it returns.
+      const refs = ((): WeakRef<object>[] =>
+        Array.from({ length: 1000 }, (_unused, i) => new WeakRef(traces.startSpan(`leaked-${i}`) as object)))()
+
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      gc()
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      gc()
+
+      // A threshold, not zero: collection timing is not guaranteed, but a registry
+      // holding every span would keep all 1000 alive.
+      const alive = refs.filter((ref) => ref.deref() !== undefined).length
+      expect(alive).toBeLessThan(100)
+    } finally {
+      vi.useFakeTimers()
+    }
+  })
+})

package/node_modules/@posthog/core/src/traces/otlp.spec.ts

@@ -0,0 +1,368 @@
+import {
+  buildOtlpSpan,
+  buildOtlpTracesPayload,
+  buildTracesResourceAttributes,
+  msToUnixNanoString,
+  spanKindToOtlp,
+} from './otlp'
+import type { OtlpSpan, ResolvedTracesConfig, SpanRecord } from './types'
+
+const record = (overrides: Partial<SpanRecord> = {}): SpanRecord => ({
+  traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+  spanId: '00f067aa0ba902b7',
+  name: 'checkout',
+  kind: 'internal',
+  traceFlags: '01',
+  parentIsRemote: false,
+  attributes: {},
+  events: [],
+  startTime: 1_700_000_000_000,
+  endTime: 1_700_000_000_080,
+  ...overrides,
+})
+
+describe('OTLP span encoding', () => {
+  describe('msToUnixNanoString', () => {
+    it('encodes milliseconds as a nanosecond string', () => {
+      expect(msToUnixNanoString(1_700_000_000_000)).toBe('1700000000000000000')
+    })
+
+    it('keeps sub-millisecond precision', () => {
+      expect(msToUnixNanoString(1_700_000_000_000.5)).toBe('1700000000000500000')
+    })
+
+    it('stays exact beyond Number.MAX_SAFE_INTEGER', () => {
+      // The whole point of string concatenation over `ms * 1e6`, which would
+      // silently lose precision at this magnitude.
+      const encoded = msToUnixNanoString(1_700_000_000_123)
+      expect(encoded).toBe('1700000000123000000')
+      expect(Number(encoded)).toBeGreaterThan(Number.MAX_SAFE_INTEGER)
+    })
+
+    it.each([0.9999999, 1.9999999, 999.9999999])(
+      'carries a rounded-up fraction into the next millisecond for %p',
+      (ms) => {
+        // Without the carry the padded fraction gains a seventh digit, producing
+        // a malformed timestamp that 400s the whole request. Unreachable from a
+        // real clock — float64 quantization at epoch-ms magnitude keeps the
+        // fraction well below the carry — but reachable via a caller-supplied
+        // `startTime`, which the validity check accepts anywhere in [0, MAX].
+        const encoded = msToUnixNanoString(ms)
+        expect(encoded).toHaveLength(String(Math.round(ms)).length + 6)
+        expect(encoded).toMatch(/^\d+$/)
+      }
+    )
+  })
+
+  describe('spanKindToOtlp', () => {
+    it.each([
+      ['internal', 1],
+      ['server', 2],
+      ['client', 3],
+      ['producer', 4],
+      ['consumer', 5],
+    ] as const)('maps %s to %i', (kind, expected) => {
+      expect(spanKindToOtlp(kind)).toBe(expected)
+    })
+
+    it('defaults to internal', () => {
+      expect(spanKindToOtlp(undefined)).toBe(1)
+    })
+  })
+
+  describe('buildOtlpSpan', () => {
+    it('builds the minimal shape', () => {
+      expect(buildOtlpSpan(record())).toEqual({
+        traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+        spanId: '00f067aa0ba902b7',
+        name: 'checkout',
+        kind: 1,
+        startTimeUnixNano: '1700000000000000000',
+        endTimeUnixNano: '1700000000080000000',
+        flags: 0x101,
+      })
+    })
+
+    it('omits status when it was never set', () => {
+      expect(buildOtlpSpan(record())).not.toHaveProperty('status')
+    })
+
+    it('encodes ok and error status codes', () => {
+      expect(buildOtlpSpan(record({ status: { code: 'ok' } })).status).toEqual({ code: 1 })
+      expect(buildOtlpSpan(record({ status: { code: 'error', message: 'boom' } })).status).toEqual({
+        code: 2,
+        message: 'boom',
+      })
+    })
+
+    it('includes parent, tracestate, attributes and events when present', () => {
+      const span = buildOtlpSpan(
+        record({
+          parentSpanId: 'b7ad6b7169203331',
+          traceState: 'vendor=abc',
+          attributes: { plan: 'pro' },
+          events: [{ name: 'cache miss', timestamp: 1_700_000_000_040 }],
+        })
+      )
+      expect(span.parentSpanId).toBe('b7ad6b7169203331')
+      expect(span.traceState).toBe('vendor=abc')
+      expect(span.attributes).toEqual([{ key: 'plan', value: { stringValue: 'pro' } }])
+      expect(span.events).toEqual([{ name: 'cache miss', timeUnixNano: '1700000000040000000' }])
+    })
+
+    it('carries an event attribute drop as the proto counter', () => {
+      const span = buildOtlpSpan(
+        record({
+          events: [{ name: 'query', timestamp: 1_700_000_000_040, droppedAttributesCount: 3 }],
+        })
+      )
+      expect(span.events?.[0]).toMatchObject({ name: 'query', droppedAttributesCount: 3 })
+    })
+
+    it.each([
+      ['none were dropped', 0],
+      ['a hook wrote a negative', -2],
+      ['a hook wrote a non-number', 'lots' as unknown as number],
+    ])('omits the event drop counter when %s', (_label, dropped) => {
+      // Coerced like the span's own counters: a non-integer here is refused for
+      // the whole request, taking unrelated spans with it.
+      const span = buildOtlpSpan(
+        record({
+          events: [{ name: 'query', timestamp: 1_700_000_000_040, droppedAttributesCount: dropped }],
+        })
+      )
+      expect(span.events?.[0].droppedAttributesCount).toBeUndefined()
+    })
+
+    it('sets the sampled bit and marks a root span as known-not-remote', () => {
+      // A root span has no parent context to be remote, which the OTel Go and
+      // Java exporters also report as known-not-remote rather than unknown.
+      expect(buildOtlpSpan(record()).flags).toBe(0x101)
+    })
+
+    it('marks a local parent as known-not-remote', () => {
+      expect(buildOtlpSpan(record({ parentSpanId: 'b7ad6b7169203331' })).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)
+    })
+  })
+
+  describe('buildTracesResourceAttributes', () => {
+    const config = (partial: Partial<ResolvedTracesConfig> = {}): ResolvedTracesConfig => ({
+      flushIntervalMs: 5000,
+      maxExportBatchSize: 512,
+      maxQueueSize: 2048,
+      beforeSpanSend: [],
+      maxAttributesPerSpan: 128,
+      maxEventsPerSpan: 128,
+      maxAttributesPerEvent: 128,
+      maxAttributeValueLength: 8192,
+      maxLiveSpans: 10000,
+      maxSpanAgeMs: 3600000,
+      ...partial,
+    })
+
+    it('always emits service.name', () => {
+      // The server reads service_name only from this attribute and stores an
+      // empty string when it's missing, leaving spans unattributable.
+      expect(buildTracesResourceAttributes(config(), 'posthog-node', '1.0.0')['service.name']).toBe('unknown_service')
+    })
+
+    it('uses the configured service name', () => {
+      expect(buildTracesResourceAttributes(config({ serviceName: 'checkout' }), 'posthog-node', '1.0.0')).toMatchObject(
+        {
+          'service.name': 'checkout',
+        }
+      )
+    })
+
+    it('includes environment and version only when set', () => {
+      const attributes = buildTracesResourceAttributes(
+        config({ environment: 'production', serviceVersion: '2.1.0' }),
+        'posthog-node',
+        '1.0.0'
+      )
+      expect(attributes['deployment.environment']).toBe('production')
+      expect(attributes['service.version']).toBe('2.1.0')
+      expect(buildTracesResourceAttributes(config(), 'posthog-node', '1.0.0')).not.toHaveProperty(
+        'deployment.environment'
+      )
+    })
+
+    it('protects SDK identity keys from user resource attributes', () => {
+      const attributes = buildTracesResourceAttributes(
+        config({ resourceAttributes: { 'telemetry.sdk.name': 'custom', 'host.name': 'web-01' } }),
+        'posthog-node',
+        '1.0.0'
+      )
+      expect(attributes['telemetry.sdk.name']).toBe('posthog-node')
+      expect(attributes['host.name']).toBe('web-01')
+    })
+  })
+
+  describe('buildOtlpTracesPayload', () => {
+    it('produces one resource, one scope, N spans', () => {
+      const spans = [buildOtlpSpan(record()), buildOtlpSpan(record({ name: 'other' }))]
+      const payload = buildOtlpTracesPayload(spans, { 'service.name': 'checkout' }, 'posthog-node', '1.0.0')
+
+      expect(payload.resourceSpans).toHaveLength(1)
+      expect(payload.resourceSpans[0].scopeSpans).toHaveLength(1)
+      expect(payload.resourceSpans[0].scopeSpans[0].spans).toHaveLength(2)
+      expect(payload.resourceSpans[0].scopeSpans[0].scope).toEqual({ name: 'posthog-node', version: '1.0.0' })
+      expect(payload.resourceSpans[0].resource.attributes).toEqual([
+        { key: 'service.name', value: { stringValue: 'checkout' } },
+      ])
+    })
+  })
+
+  describe('golden wire fixture', () => {
+    it('matches the shape the ingestion service accepts', () => {
+      // Pinned against the OTLP/JSON encoding the capture-logs service's own
+      // trace fixtures use: hex ids, string nanosecond timestamps, integer kind
+      // and status enums, and stringified int64 attribute values.
+      const payload = buildOtlpTracesPayload(
+        [
+          buildOtlpSpan(
+            record({
+              parentSpanId: 'b7ad6b7169203331',
+              name: 'GET /users/:id',
+              kind: 'server',
+              status: { code: 'error', message: 'boom' },
+              attributes: {
+                posthogDistinctId: 'user-123',
+                sessionId: 'session-123',
+                'http.status_code': 500,
+                'http.duration_ratio': 0.25,
+                cached: false,
+              },
+              events: [
+                {
+                  name: 'exception',
+                  timestamp: 1_700_000_000_040,
+                  attributes: { 'exception.type': 'TypeError', 'exception.message': 'boom' },
+                },
+              ],
+            })
+          ),
+        ],
+        { 'service.name': 'checkout-api', 'telemetry.sdk.name': 'posthog-node' },
+        'posthog-node',
+        '1.0.0'
+      )
+
+      expect(payload).toEqual({
+        resourceSpans: [
+          {
+            resource: {
+              attributes: [
+                { key: 'service.name', value: { stringValue: 'checkout-api' } },
+                { key: 'telemetry.sdk.name', value: { stringValue: 'posthog-node' } },
+              ],
+            },
+            scopeSpans: [
+              {
+                scope: { name: 'posthog-node', version: '1.0.0' },
+                spans: [
+                  {
+                    traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+                    spanId: '00f067aa0ba902b7',
+                    parentSpanId: 'b7ad6b7169203331',
+                    name: 'GET /users/:id',
+                    kind: 2,
+                    startTimeUnixNano: '1700000000000000000',
+                    endTimeUnixNano: '1700000000080000000',
+                    flags: 0x101,
+                    attributes: [
+                      { key: 'posthogDistinctId', value: { stringValue: 'user-123' } },
+                      { key: 'sessionId', value: { stringValue: 'session-123' } },
+                      { key: 'http.status_code', value: { intValue: '500' } },
+                      { key: 'http.duration_ratio', value: { doubleValue: 0.25 } },
+                      { key: 'cached', value: { boolValue: false } },
+                    ],
+                    events: [
+                      {
+                        name: 'exception',
+                        timeUnixNano: '1700000000040000000',
+                        attributes: [
+                          { key: 'exception.type', value: { stringValue: 'TypeError' } },
+                          { key: 'exception.message', value: { stringValue: 'boom' } },
+                        ],
+                      },
+                    ],
+                    status: { code: 2, message: 'boom' },
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      })
+    })
+  })
+})
+
+describe('wire string safety', () => {
+  const lone = 'value \u{1F680}'.slice(0, 7)
+
+  const encode = (record: Partial<SpanRecord> = {}): OtlpSpan =>
+    buildOtlpSpan({
+      traceId: 'a'.repeat(32),
+      spanId: 'b'.repeat(16),
+      name: 'checkout',
+      kind: 'internal',
+      attributes: {},
+      events: [],
+      startTime: 1,
+      endTime: 2,
+      ...record,
+    } as SpanRecord)
+
+  it('replaces a lone surrogate in every free-text field', () => {
+    const span = encode({
+      name: lone,
+      traceState: `vendor=${lone}`,
+      status: { code: 'error', message: lone },
+      events: [{ name: lone, timestamp: 1 }],
+    })
+
+    expect(span.name).not.toContain('\ud83d')
+    expect(span.events?.[0].name).not.toContain('\ud83d')
+    expect(span.status?.message).not.toContain('\ud83d')
+    expect(span.traceState).not.toContain('\ud83d')
+  })
+
+  it('keeps the span when a status message cannot be stringified', () => {
+    const hostile = {
+      toString() {
+        throw new Error('toString exploded')
+      },
+    }
+    const span = encode({ status: { code: 'error', message: hostile as unknown as string } })
+
+    expect(span.name).toBe('checkout')
+    expect(span.status?.message).toBe('[Unserializable]')
+  })
+
+  it('coerces a non-string status message', () => {
+    const span = encode({ status: { code: 'error', message: 500 as unknown as string } })
+
+    expect(span.status?.message).toBe('500')
+  })
+
+  it('falls back to internal for a prototype key passed as a kind', () => {
+    expect(spanKindToOtlp('__proto__' as never)).toBe(1)
+    expect(spanKindToOtlp('toString' as never)).toBe(1)
+  })
+})

package/node_modules/@posthog/core/src/traces/otlp.ts

@@ -0,0 +1,191 @@
+import type {
+  OtlpSpan,
+  OtlpSpanEvent,
+  OtlpSpanKeyValue,
+  OtlpTracesPayload,
+  SpanAttributes,
+  SpanKind,
+  SpanStatusCode,
+} from '@posthog/types'
+import type { Logger } from '../types'
+import type { ResolvedTracesConfig, SpanRecord } from './types'
+import { nonNegativeCount } from './span'
+import { toOtlpKeyValueList } from '../utils/otlp-any-value'
+import { UNSERIALIZABLE_VALUE, sanitizeString } from '../utils/json-utils'
+import { buildOtlpResourceAttributes, toOtlpResourceKeyValueList } from '../utils/otlp-resource'
+
+const SPAN_KIND_TO_OTLP: Record<SpanKind, number> = {
+  internal: 1,
+  server: 2,
+  client: 3,
+  producer: 4,
+  consumer: 5,
+}
+
+const SPAN_STATUS_TO_OTLP: Record<SpanStatusCode, number> = {
+  ok: 1,
+  error: 2,
+}
+
+/** 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, and
+// a root span's parent context is empty, which is not remote. Setting the known
+// bit on a root span is what the OTel Go and Java exporters do too.
+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. */
+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
+ * `JSON.stringify` as a `\uD800` escape that strict parsers refuse, and the
+ * ingestion service refuses the whole request rather than the one row — so the
+ * safe path has to be the default, not the exception.
+ */
+function wireString(value: unknown): string {
+  if (typeof value === 'string') {
+    return sanitizeString(value)
+  }
+  try {
+    return sanitizeString(String(value))
+  } catch {
+    // A hostile `toString` costs its own field, not the whole span.
+    return UNSERIALIZABLE_VALUE
+  }
+}
+
+export function spanKindToOtlp(kind: SpanKind | undefined): number {
+  // `hasOwnProperty`, not a plain lookup: `kind: '__proto__'` from an untyped
+  // caller otherwise resolves to `Object.prototype` and ships `"kind":{}`.
+  if (kind && Object.prototype.hasOwnProperty.call(SPAN_KIND_TO_OTLP, kind)) {
+    return SPAN_KIND_TO_OTLP[kind]
+  }
+  return SPAN_KIND_TO_OTLP.internal
+}
+
+/**
+ * Converts a millisecond epoch to the unix-nanosecond string OTLP expects.
+ * Concatenation rather than multiplication: `Date.now() * 1e6` exceeds
+ * `Number.MAX_SAFE_INTEGER`.
+ */
+export function msToUnixNanoString(ms: number): string {
+  let whole = Math.floor(ms)
+  let fractionalNanos = Math.round((ms - whole) * 1e6)
+  // Rounding can carry into the next millisecond. Without this the padded
+  // fraction gains a seventh digit and the concatenated timestamp is malformed,
+  // which 400s the entire request — the exact failure client-side validity
+  // exists to prevent.
+  if (fractionalNanos >= 1e6) {
+    whole += 1
+    fractionalNanos = 0
+  }
+  return String(whole) + String(fractionalNanos).padStart(6, '0')
+}
+
+function toOtlpEvent(event: SpanRecord['events'][number], logger?: Logger): OtlpSpanEvent {
+  const encoded: OtlpSpanEvent = {
+    name: wireString(event.name),
+    timeUnixNano: msToUnixNanoString(event.timestamp),
+  }
+  if (event.attributes) {
+    const attributes = toOtlpKeyValueList(event.attributes, logger)
+    if (attributes.length) {
+      encoded.attributes = attributes
+    }
+  }
+  const dropped = nonNegativeCount(event.droppedAttributesCount)
+  if (dropped) {
+    encoded.droppedAttributesCount = dropped
+  }
+  return encoded
+}
+
+export function buildOtlpSpan(record: SpanRecord, logger?: Logger): OtlpSpan {
+  const span: OtlpSpan = {
+    traceId: record.traceId,
+    spanId: record.spanId,
+    name: wireString(record.name),
+    kind: spanKindToOtlp(record.kind),
+    startTimeUnixNano: msToUnixNanoString(record.startTime),
+    endTimeUnixNano: msToUnixNanoString(record.endTime),
+    flags: spanFlags(record),
+  }
+  if (record.parentSpanId) {
+    span.parentSpanId = record.parentSpanId
+  }
+  if (record.traceState) {
+    span.traceState = wireString(record.traceState)
+  }
+  const attributes = toOtlpKeyValueList(record.attributes, logger)
+  if (attributes.length) {
+    span.attributes = attributes
+  }
+  if (record.events.length) {
+    span.events = record.events.map((event) => toOtlpEvent(event, logger))
+  }
+  // Coerced: a `beforeSpanSend` hook can write anything onto the record, and a
+  // non-integer here is refused for the whole request.
+  const droppedAttributes = nonNegativeCount(record.droppedAttributesCount)
+  if (droppedAttributes) {
+    span.droppedAttributesCount = droppedAttributes
+  }
+  const droppedEvents = nonNegativeCount(record.droppedEventsCount)
+  if (droppedEvents) {
+    span.droppedEventsCount = droppedEvents
+  }
+  if (record.status) {
+    span.status = {
+      code: SPAN_STATUS_TO_OTLP[record.status.code],
+      ...(record.status.message && { message: wireString(record.status.message) }),
+    }
+  }
+  return span
+}
+
+/**
+ * OTLP resource attributes for every batch. User `resourceAttributes` are spread
+ * first, then SDK-controlled identity keys on top so a stray key can't clobber
+ * them. `service.name` is always emitted: the server reads `service_name` only
+ * from that attribute, and spans are unattributable without it.
+ */
+export function buildTracesResourceAttributes(
+  config: ResolvedTracesConfig,
+  sdkName: string,
+  sdkVersion: string
+): SpanAttributes {
+  return buildOtlpResourceAttributes(config, sdkName, sdkVersion)
+}
+
+/**
+ * Wraps spans in the OTLP `resourceSpans` envelope: one resource, one scope, N
+ * spans per batch. The server flattens the scope to `{name}@{version}`.
+ */
+export function buildOtlpTracesPayload(
+  spans: OtlpSpan[],
+  resourceAttributes: SpanAttributes,
+  scopeName: string,
+  scopeVersion: string,
+  logger?: Logger
+): OtlpTracesPayload {
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: toOtlpResourceKeyValueList(resourceAttributes, logger) },
+        scopeSpans: [
+          {
+            scope: { name: scopeName, version: scopeVersion },
+            spans,
+          },
+        ],
+      },
+    ],
+  }
+}