Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

2.8 KB
Raw Blame
// Resolve the person and session a whole trace belongs to, so the drawer can answer "who was
// this?" in its header instead of leaving the answer in a span's attribute table.

// The per-span precedence and the convention key lists are shared with Logs, because both
// products resolve the same SDK-emitted attribute keys (posthogDistinctId, sessionId, ...).
import { getDistinctIdWithKey, getSessionIdWithKey } from 'products/logs/frontend/utils'

import type { Span } from './types'

export interface TraceIdentity {
    readonly distinctId: string | null
    readonly sessionId: string | null
}

// One shared instance, so a caller that resolves nothing does not invalidate its consumers.
export const EMPTY_TRACE_IDENTITY: TraceIdentity = { distinctId: null, sessionId: null }

type IdentityResolver = typeof getDistinctIdWithKey

function singleValueAcrossSpans(
    spans: Span[],
    resolve: IdentityResolver,
    configuredKeys: string[] | undefined
): string | null {
    let resolved: string | null = null

    for (const span of spans) {
        const value = resolve(span.attributes, span.resource_attributes, configuredKeys)?.value
        if (!value) {
            continue
        }
        if (resolved !== null && resolved !== value) {
            // A trace that touches more than one identity, which a batch consumer working
            // through several users' items does. Promoting either value would state a fact the
            // trace does not support, so the span attribute table stays the only place it appears.
            return null
        }
        resolved = value
    }
    return resolved
}

export function resolveTraceIdentity(
    spans: Span[],
    configuredDistinctIdKeys: string[] | undefined,
    configuredSessionIdKeys: string[] | undefined
): TraceIdentity {
    if (spans.length === 0) {
        return EMPTY_TRACE_IDENTITY
    }
    return {
        distinctId: singleValueAcrossSpans(spans, getDistinctIdWithKey, configuredDistinctIdKeys),
        sessionId: resolveTraceSessionId(spans, configuredSessionIdKeys),
    }
}

// The session half on its own, for callers that need no person. It keeps the same
// disagreement rule as `resolveTraceIdentity`, so both surfaces resolve one session or none.
export function resolveTraceSessionId(spans: Span[], configuredSessionIdKeys: string[] | undefined): string | null {
    return singleValueAcrossSpans(spans, getSessionIdWithKey, configuredSessionIdKeys)
}

// One span's session, for a caller that answers a row rather than a whole trace. A single span
// carries at most one session, so there is nothing here for the disagreement rule to decide.
export function resolveSpanSessionId(span: Span, configuredSessionIdKeys: string[] | undefined): string | null {
    return getSessionIdWithKey(span.attributes, span.resource_attributes, configuredSessionIdKeys)?.value ?? null
}