Adds PostHog IDs to application spans when they start.
Requires the optional {:opentelemetry, "~> 1.7"} dependency. Add
{PostHog.OpenTelemetry.ContextSpanProcessor, %{supervisor_name: PostHog}}
before the existing export processors in your OpenTelemetry :processors
configuration. Keep the application's provider, exporter, and sampler.
The processor reads the current process's PostHog context. :supervisor_name
selects a named PostHog instance and defaults to PostHog. Spans stay
unchanged when that instance is disabled or not started. It adds the
sessionId and posthogDistinctId attributes when their values are present.
Existing attributes with these names take precedence, with atom or string
keys. Empty and non-string IDs are omitted.
Initial span attributes named http.request.header.x-posthog-session-id
and http.request.header.x-posthog-distinct-id provide fallback IDs when
process context has none. The processor sanitizes those values with the
same rules as the PostHog plug. Existing canonical attributes take precedence,
followed by process context, then captured header attributes.
With Cowboy, explicitly allow only x-posthog-session-id and
x-posthog-distinct-id in the application's OpenTelemetry request_headers
option to cover its early request span. This processor does not enable
header capture. Keep PostHog.Integrations.Plug before the router for child
spans. A span that starts without context or captured headers remains
unchanged, even if PostHog extracts headers later.
Context has the same lifetime as existing PostHog process metadata. A standard request process loses its context when it exits. Reusing a process for unrelated work requires explicit context cleanup. Tasks and spawned processes do not automatically inherit PostHog context. Set context in the destination process when that propagation is required.