feat(node): cap attributes and events per span

.changeset/node-span-limits.md

@@ -0,0 +1,7 @@
+---
+'posthog-node': minor
+'@posthog/core': minor
+'@posthog/types': minor
+---
+
+Cap spans at 128 user attributes and 128 events, configurable with `traces.maxAttributesPerSpan` and `traces.maxEventsPerSpan`.

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

@@ -18,6 +18,8 @@ const resolveForTest = (partial?: Partial<ResolvedTracesConfig>): ResolvedTraces
   flushIntervalMs: 5000,
   maxExportBatchSize: 512,
   maxQueueSize: 2048,
+  maxAttributesPerSpan: 128,
+  maxEventsPerSpan: 128,
   ...partial,
 })
 
@@ -498,6 +500,157 @@ describe('PostHogTraces', () => {
     })
   })
 
+  describe('span limits', () => {
+    it('keeps the earliest attributes and counts the rest', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 3 })
+      const span = traces.startSpan('checkout')
+      for (let i = 0; i < 5; i++) {
+        span.setAttribute(`key-${i}`, i)
+      }
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes!.map((attribute) => attribute.key)).toEqual(['key-0', 'key-1', 'key-2'])
+      expect(sent.droppedAttributesCount).toBe(2)
+    })
+
+    it('never evicts the auto-context keys', async () => {
+      context = { distinctId: 'alice', sessionId: 'session-1' }
+      const traces = createTraces({ maxAttributesPerSpan: 1 })
+      const span = traces.startSpan('checkout')
+      for (let i = 0; i < 5; i++) {
+        span.setAttribute(`key-${i}`, i)
+      }
+      span.end()
+      await traces.flush()
+
+      const keys = sentSpans()[0].attributes!.map((attribute) => attribute.key)
+      expect(keys).toEqual(expect.arrayContaining(['posthogDistinctId', 'sessionId', 'key-0']))
+      expect(keys).not.toContain('key-1')
+    })
+
+    it('caps events and counts the rest', async () => {
+      const traces = createTraces({ maxEventsPerSpan: 2 })
+      const span = traces.startSpan('checkout')
+      for (let i = 0; i < 4; i++) {
+        span.addEvent(`event-${i}`)
+      }
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.events!.map((event) => event.name)).toEqual(['event-0', 'event-1'])
+      expect(sent.droppedEventsCount).toBe(2)
+    })
+
+    it('lets a caller overwrite an attribute it already set while at the cap', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 1 })
+      const span = traces.startSpan('checkout')
+      span.setAttribute('plan', 'free')
+      span.setAttribute('plan', 'pro')
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes).toEqual([{ key: 'plan', value: { stringValue: 'pro' } }])
+      expect(sent.droppedAttributesCount).toBeUndefined()
+    })
+
+    it('omits the counters when nothing was dropped', async () => {
+      const traces = createTraces()
+      traces.startSpan('checkout', { attributes: { plan: 'pro' } }).end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent).not.toHaveProperty('droppedAttributesCount')
+      expect(sent).not.toHaveProperty('droppedEventsCount')
+    })
+
+    it('counts a parsed __proto__ key against the cap instead of smuggling it through', async () => {
+      // JSON.parse produces an own `__proto__` key; a plain object store would
+      // swap its prototype and leak every nested key past the cap.
+      const traces = createTraces({ maxAttributesPerSpan: 2 })
+      const parsed = JSON.parse('{"__proto__": {"leaked": 1}, "orderId": "abc"}')
+      traces.startSpan('checkout', { attributes: parsed }).end()
+      await traces.flush()
+
+      const keys = sentSpans()[0].attributes!.map((attribute) => attribute.key)
+      expect(keys).not.toContain('leaked')
+      expect(keys).toContain('orderId')
+    })
+
+    it('does not let reserved property names bypass the cap', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 1 })
+      const span = traces.startSpan('checkout')
+      span.setAttribute('kept', 1)
+      span.setAttribute('toString', 'nope')
+      span.setAttribute('constructor', 'nope')
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes!.map((attribute) => attribute.key)).toEqual(['kept'])
+      expect(sent.droppedAttributesCount).toBe(2)
+    })
+
+    it('does not spend cap budget on values that are dropped at encode time', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 2 })
+      const span = traces.startSpan('checkout')
+      span.setAttribute('skipped-a', undefined)
+      span.setAttribute('skipped-b', null)
+      span.setAttribute('orderId', 'abc-123')
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes!.map((attribute) => attribute.key)).toEqual(['orderId'])
+      expect(sent.droppedAttributesCount).toBeUndefined()
+    })
+
+    it('still caps a key first seen with an optional value', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 2 })
+      const span = traces.startSpan('checkout')
+      for (let i = 0; i < 5; i++) {
+        span.setAttribute(`field-${i}`, undefined)
+      }
+      for (let i = 0; i < 5; i++) {
+        span.setAttribute(`field-${i}`, i)
+      }
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes).toHaveLength(2)
+      expect(sent.droppedAttributesCount).toBe(3)
+    })
+
+    it('clears a key that is set back to null', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 2 })
+      const span = traces.startSpan('checkout')
+      span.setAttribute('orderId', 'abc-123')
+      span.setAttribute('orderId', null)
+      span.setAttribute('a', 1)
+      span.setAttribute('b', 2)
+      span.end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes!.map((attribute) => attribute.key)).toEqual(['a', 'b'])
+      expect(sent.droppedAttributesCount).toBeUndefined()
+    })
+
+    it('caps attributes supplied at start', async () => {
+      const traces = createTraces({ maxAttributesPerSpan: 2 })
+      traces.startSpan('checkout', { attributes: { a: 1, b: 2, c: 3 } }).end()
+      await traces.flush()
+
+      const [sent] = sentSpans()
+      expect(sent.attributes!.map((attribute) => attribute.key)).toEqual(['a', 'b'])
+      expect(sent.droppedAttributesCount).toBe(1)
+    })
+  })
+
   describe('export', () => {
     it('flushes when the queue reaches the batch size', async () => {
       const traces = createTraces({ maxExportBatchSize: 2 })

packages/core/src/traces/index.ts

@@ -78,6 +78,8 @@ export class PostHogTraces {
     const now = Date.now()
     const startTime = resolveStartTime(options?.startTime, now, this._logger)
 
+    const autoAttributes = this._autoContextAttributes()
+
     return new PostHogSpan(
       {
         traceId: parent?.traceId ?? newTraceId(),
@@ -87,7 +89,10 @@ export class PostHogTraces {
         name: sanitizeName(name, 'Span name', this._logger),
         kind: options?.kind ?? 'internal',
         // Auto-context first so user-supplied attributes win on collision.
-        attributes: assignUserAttributes(this._autoContextAttributes(), options?.attributes),
+        attributes: assignUserAttributes({ ...autoAttributes }, options?.attributes),
+        autoAttributeKeys: Object.keys(autoAttributes),
+        maxAttributes: this._config.maxAttributesPerSpan,
+        maxEvents: this._config.maxEventsPerSpan,
         startTime,
         backdated: startTime !== now,
       },

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

@@ -118,6 +118,8 @@ describe('OTLP span encoding', () => {
       flushIntervalMs: 5000,
       maxExportBatchSize: 512,
       maxQueueSize: 2048,
+      maxAttributesPerSpan: 128,
+      maxEventsPerSpan: 128,
       ...partial,
     })
 

packages/core/src/traces/otlp.ts

@@ -87,6 +87,12 @@ export function buildOtlpSpan(record: SpanRecord, logger?: Logger): OtlpSpan {
   if (record.events.length) {
     span.events = record.events.map((event) => toOtlpEvent(event, logger))
   }
+  if (record.droppedAttributesCount) {
+    span.droppedAttributesCount = record.droppedAttributesCount
+  }
+  if (record.droppedEventsCount) {
+    span.droppedEventsCount = record.droppedEventsCount
+  }
   // An unset status is omitted rather than sent as code 0.
   if (record.status) {
     span.status = {

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

@@ -21,6 +21,9 @@ describe('PostHogSpan', () => {
         attributes: {},
         startTime: Date.now(),
         backdated: false,
+        autoAttributeKeys: [],
+        maxAttributes: 128,
+        maxEvents: 128,
         ...init,
       },
       (record) => ended.push(record),
@@ -284,6 +287,59 @@ describe('NoopSpan', () => {
   })
 })
 
+describe('attribute store', () => {
+  it('hands out a record whose attributes behave like an ordinary object', () => {
+    const ended: SpanRecord[] = []
+    const span = new PostHogSpan(
+      {
+        traceId: TRACE_ID,
+        spanId: SPAN_ID,
+        name: 'checkout',
+        kind: 'internal',
+        attributes: { plan: 'pro' },
+        startTime: Date.now(),
+        backdated: false,
+        autoAttributeKeys: [],
+        maxAttributes: 128,
+        maxEvents: 128,
+      },
+      (record) => ended.push(record)
+    )
+    span.end()
+
+    const { attributes } = ended[0]
+    expect(Object.getPrototypeOf(attributes)).toBe(Object.prototype)
+    expect(Object.prototype.hasOwnProperty.call(attributes, 'plan')).toBe(true)
+    expect(() => JSON.stringify(attributes)).not.toThrow()
+  })
+
+  it('keeps a parsed __proto__ key as an ordinary attribute', () => {
+    const ended: SpanRecord[] = []
+    const span = new PostHogSpan(
+      {
+        traceId: TRACE_ID,
+        spanId: SPAN_ID,
+        name: 'checkout',
+        kind: 'internal',
+        attributes: JSON.parse('{"__proto__": {"leaked": 1}, "orderId": "abc"}'),
+        startTime: Date.now(),
+        backdated: false,
+        autoAttributeKeys: [],
+        maxAttributes: 128,
+        maxEvents: 128,
+      },
+      (record) => ended.push(record)
+    )
+    span.end()
+
+    const keys: string[] = []
+    for (const key in ended[0].attributes) {
+      keys.push(key)
+    }
+    expect(keys).not.toContain('leaked')
+  })
+})
+
 describe('describeError', () => {
   it.each([
     ['an Error', new Error('boom'), { type: 'Error', message: 'boom' }],