Add aiTraceSampleRate to posthog-node to sample AI observability events by trace id

[jakesciotto]

Is your feature request related to a problem?

Teams whose AI observability volume is mostly $ai_* events have no supported way to keep a fraction of traces. The only path today is a hand-written before_send hook that hashes $ai_trace_id. Most teams do not write one. A hook that samples per event splits a trace, so the trace view shows partial trees.

Related: PostHog/posthog-python#965 for the same option in the Python client.

Describe the solution you'd like

One posthog-node client option, default off:

new PostHog(key, { aiTraceSampleRate: 0.1 })

Env var POSTHOG_AI_TRACE_SAMPLE_RATE, option > env > default.

Behavior:

1. Applies to events named $ai_* that carry $ai_trace_id.
2. FNV-1a 32-bit hash of the trace id. Keep when hash / 2^32 < rate. Same hash in every SDK, so a mixed Node and Python stack makes one decision per trace.
3. Runs in the node client before before_send, so a customer hook sees only kept events.
4. Adds $ai_trace_sample_rate to kept events, so the server can scale totals later.
5. Events with no trace id are kept. Rate unset or 1 means no sampling. Out-of-range values log a warning and are ignored.

flowchart LR
  W["@posthog/ai integrations"] --> C[captureAiEvent]
  M["Manual capture of $ai_* events"] --> E[posthog-node client]
  C --> E
  E --> S{aiTraceSampleRate}
  S -- drop --> X[Dropped]
  S -- keep --> B[before_send] --> Q[Queue]

Loading

Describe alternatives you've considered

A helper in @posthog/ai that returns a before_send function. Rejected because it does not cover manual capture, and it does not give one rule across SDKs.

Related sub-libraries

• All of them
• posthog-js (web)
• posthog-js-lite (web lite)
• posthog-node
• posthog-react-native
• @posthog/react
• @posthog/ai
• @posthog/convex
• @posthog/nextjs-config
• @posthog/nuxt
• @posthog/rollup-plugin
• @posthog/webpack-plugin

Additional context

Impact

• Gives AI observability users a supported volume lever that keeps traces whole.
• Removes the need for a custom hook that is easy to get wrong.

Blast radius

• Default off. No behavior change for any existing caller.
• Touches the posthog-node client options and its enqueue path only. @posthog/ai integrations do not change.
• Affects $ai_* events only. Other events never reach the sampler.
• Kept $ai_* events gain one property when the option is set.
• Public API grows by one option and one env var. posthog-node references regenerate.

Not in this issue

Tail sampling that keeps errored traces. A per-call override. Server-side upweighting of cost dashboards.