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.

17.6 KB
Raw Blame
import { MakeLogicType, connect, kea, key, listeners, path, props, reducers, selectors } from 'kea'
import { loaders } from 'kea-loaders'

import { usableId } from 'lib/components/ViewTraceButton/usableId'
import { chunk } from 'lib/utils/arrays'
import { teamLogic } from 'scenes/teamLogic'

import { type ErrorScope, sessionErrorsWindow, traceErrorsWindow } from './errorCorrelation'
import { tracingSpansErrorCountsCreate } from './generated/api'
import type { TeamTracingConfigApi } from './generated/api.schemas'
import { tracingSpansErrorCountsCreateBodySpanIdsMax } from './generated/api.zod'
import { resolveSpanSessionId } from './traceIdentity'
import { tracingCorrelationConfigLogic } from './tracingCorrelationConfigLogic'
import { tracingDataLogic } from './tracingDataLogic'
import { TRACING_SCENE_VIEWER_ID } from './tracingFiltersLogic'
import type { Span } from './types'

const MAX_IDS_PER_LOOKUP = tracingSpansErrorCountsCreateBodySpanIdsMax

// A kea breakpoint cancels a superseded lookup, and the one that survives asks about every id
// still unanswered, so this wait coalesces fast paging into a single query.
const LOOKUP_DEBOUNCE_MS = 300

// One shared instance, so the selectors below keep their identity while the feature is off.
const NO_SESSIONS: Map<string, string> = new Map()

/** Which join produced a row's count. The badge says a different thing for each. */
export type SpanErrorTier = ErrorScope

export interface SpanErrorBadge {
    tier: SpanErrorTier
    count: number
    /**
     * The session's own total, when the row matched on a narrower tier. It is a separate count
     * over a separate set, not a remainder: the session query matches `$session_id` and the trace
     * query matches `$trace_id`, so a backend exception can be in one and not the other.
     */
    alsoInSession?: number
}

export interface SpanErrorCounts {
    trace: Record<string, number>
    span: Record<string, number>
    session: Record<string, number>
}

type ExactCounts = Pick<SpanErrorCounts, 'trace' | 'span'>

export interface SpanErrorsLogicProps {
    id: string
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface spanErrorsLogicValues {
    currentTeamId: number | null // teamLogic
    configuredSessionIdKeys: string[] | undefined // tracingCorrelationConfigLogic
    sessionErrorBadgesEnabled: boolean // tracingCorrelationConfigLogic
    listRows: Span[] // tracingDataLogic
    errorBadgeByRow: Map<string, SpanErrorBadge>
    errorCounts: SpanErrorCounts
    errorCountsLoading: boolean
    sessionIdByRow: Map<string, string>
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface spanErrorsLogicActions {
    loadTracingConfigSuccess: (
        tracingConfig: TeamTracingConfigApi,
        payload?: any
    ) => {
        payload?: any
        tracingConfig: TeamTracingConfigApi
    } // tracingCorrelationConfigLogic
    fetchNextPageSuccess: (
        spans: Span[],
        payload?:
            | {
                  value: true
              }
            | undefined
    ) => {
        payload?: {
            value: true
        }
        spans: Span[]
    } // tracingDataLogic
    fetchSpansSuccess: (
        spans: Span[],
        payload?: any
    ) => {
        payload?: any
        spans: Span[]
    } // tracingDataLogic
    loadErrorCounts: (_: void) => void
    loadErrorCountsFailure: (
        error: string,
        errorObject?: any
    ) => {
        error: string
        errorObject?: any
    }
    loadErrorCountsSuccess: (
        errorCounts: SpanErrorCounts,
        payload?: void
    ) => {
        errorCounts: SpanErrorCounts
        payload?: void
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface spanErrorsLogicMeta {
    key: string
    __keaTypeGenInternalSelectorTypes: {
        sessionIdByRow: (
            listRows: Span[],
            configuredSessionIdKeys: string[] | undefined,
            sessionErrorBadgesEnabled: boolean
        ) => Map<string, string>
        errorBadgeByRow: (
            listRows: Span[],
            sessionIdByRow: Map<string, string>,
            errorCounts: SpanErrorCounts
        ) => Map<string, SpanErrorBadge>
    }
}

export type spanErrorsLogicType = MakeLogicType<
    spanErrorsLogicValues,
    spanErrorsLogicActions,
    SpanErrorsLogicProps,
    spanErrorsLogicMeta
>

const EMPTY_COUNTS: SpanErrorCounts = { trace: {}, span: {}, session: {} }

function distinct(ids: (string | null)[]): string[] {
    return Array.from(new Set(ids.filter((id): id is string => !!id)))
}

// hasOwn, not `in`, because `in` walks the prototype chain, so an id that collides with an Object
// member would read as answered.
function unanswered(ids: (string | null)[], known: Record<string, number>): string[] {
    return distinct(ids).filter((id) => !Object.hasOwn(known, id))
}

// Every id looked up lands a count even when it is zero, which is what stops the next page asking
// about it again.
function seedZeros(ids: string[]): Record<string, number> {
    return Object.fromEntries(ids.map((id) => [id, 0]))
}

function exactCountsFor(span: Span, counts: ExactCounts): { spanCount: number; traceCount: number } {
    const spanId = usableId(span.span_id)
    const traceId = usableId(span.trace_id)
    return {
        spanCount: spanId ? (counts.span[spanId] ?? 0) : 0,
        traceCount: traceId ? (counts.trace[traceId] ?? 0) : 0,
    }
}

/** Counts keyed on the ids the rows carry, which name the span or the request that threw. */
async function lookUpExactCounts(rows: Span[], known: SpanErrorCounts, teamId: number): Promise<ExactCounts> {
    const exact: ExactCounts = { trace: { ...known.trace }, span: { ...known.span } }
    // A row needs the lookup while either of its ids is unanswered. Chunking by row rather than by
    // id keeps a span and the trace it belongs to in the same request, which the endpoint requires:
    // a span id is only unique in its trace.
    const exactRows = rows.filter((span) => {
        const traceId = usableId(span.trace_id)
        // Without a trace id neither tier can answer: the endpoint needs one, and a span id alone
        // is ambiguous across traces. Such a row would otherwise never be recorded as looked up,
        // so every later page would ask about it again.
        if (!traceId) {
            return false
        }
        const spanId = usableId(span.span_id)
        return !Object.hasOwn(known.trace, traceId) || (!!spanId && !Object.hasOwn(known.span, spanId))
    })
    if (exactRows.length === 0) {
        return exact
    }
    // Only the rows this query asks about set the range. Taking every loaded row instead would
    // widen it with each page and re-scan the time the earlier pages already covered.
    const range = traceErrorsWindow(exactRows.map((span) => span.timestamp))
    if (!range) {
        return exact
    }

    // The endpoint, not a HogQL query from here, because it checks the caller's Error Tracking
    // access before it answers.
    const asks = chunk(exactRows, MAX_IDS_PER_LOOKUP).map((rowChunk) => ({
        traceIds: distinct(rowChunk.map((span) => usableId(span.trace_id))),
        spanIds: distinct(rowChunk.map((span) => usableId(span.span_id))),
    }))
    const responses = await Promise.all(
        asks.map((ask) =>
            tracingSpansErrorCountsCreate(String(teamId), {
                ...ask,
                dateFrom: range.date_from,
                dateTo: range.date_to,
            }).catch(() => null)
        )
    )

    asks.forEach((ask, index) => {
        const response = responses[index]
        if (!response) {
            return
        }
        // Only the ids this run had no answer for. The rest rode along to scope the span match, and
        // their counts were measured over their own page's window, so this narrower one must not
        // overwrite them.
        const freshTraces = new Set(unanswered(ask.traceIds, known.trace))
        const freshSpans = new Set(unanswered(ask.spanIds, known.span))
        Object.assign(exact.trace, seedZeros([...freshTraces]))
        Object.assign(exact.span, seedZeros([...freshSpans]))
        for (const { trace_id, exceptions } of response.traceResults) {
            if (freshTraces.has(trace_id)) {
                exact.trace[trace_id] = exceptions
            }
        }
        for (const { span_id, exceptions } of response.spanResults) {
            if (freshSpans.has(span_id)) {
                exact.span[span_id] = exceptions
            }
        }
    })
    return exact
}

/**
 * Every row's session, not only the rows the exact lookup left blank. One exception carrying a
 * trace id is enough to answer a row, which would hide the rest of its session from an SDK that
 * stamps none. Only `posthog-python` stamps them today, so mixed traces are the normal case.
 */
async function lookUpSessionCounts(
    rows: Span[],
    known: SpanErrorCounts,
    sessionIdByRow: Map<string, string>,
    teamId: number
): Promise<Record<string, number>> {
    const askSessionIds = unanswered(
        rows.map((span) => sessionIdByRow.get(span.uuid) ?? null),
        known.session
    )
    if (askSessionIds.length === 0) {
        return {}
    }
    const asked = new Set(askSessionIds)
    const range = sessionErrorsWindow(
        rows
            .filter((span) => {
                const sessionId = sessionIdByRow.get(span.uuid)
                return !!sessionId && asked.has(sessionId)
            })
            .map((span) => span.timestamp)
    )
    if (!range) {
        return {}
    }

    // One request per cap-sized chunk, all in flight together, so a page with more sessions than
    // one request allows is answered in one run rather than one chunk per debounce.
    const responses = await Promise.all(
        chunk(askSessionIds, MAX_IDS_PER_LOOKUP).map((idChunk) =>
            tracingSpansErrorCountsCreate(String(teamId), {
                sessionIds: idChunk,
                dateFrom: range.date_from,
                dateTo: range.date_to,
            }).catch(() => null)
        )
    )

    const counts = seedZeros(askSessionIds)
    for (const response of responses) {
        if (!response) {
            continue
        }
        for (const { session_id, exceptions } of response.sessionResults) {
            if (Object.hasOwn(counts, session_id)) {
                counts[session_id] = exceptions
            }
        }
    }
    return counts
}

// Three joins, in falling order of confidence. An exception from an SDK that propagated the trace
// context carries `$trace_id` and `$span_id`, which names the span that threw. Without those the
// only join left is the session the span belongs to plus a time window, which is co-occurring
// evidence rather than a cause, so the badge says something weaker for it.
//
// Only exceptions error tracking linked to an issue count: an event with no issue id failed
// ingestion parsing, so the Errors tab this badge opens can never list it. The two still disagree
// at the edges, because the tab anchors its window to the open trace rather than the whole page,
// caps at 100 issues, and resolves issues through fingerprint state this query cannot see.
export const spanErrorsLogic = kea<spanErrorsLogicType>([
    props({ id: TRACING_SCENE_VIEWER_ID } as SpanErrorsLogicProps),
    key((props) => props.id),
    path((key) => ['products', 'tracing', 'frontend', 'spanErrorsLogic', key]),

    connect(({ id }: SpanErrorsLogicProps) => ({
        values: [
            tracingDataLogic({ id }),
            ['listRows'],
            tracingCorrelationConfigLogic,
            ['configuredSessionIdKeys', 'sessionErrorBadgesEnabled'],
            teamLogic,
            ['currentTeamId'],
        ],
        actions: [
            tracingDataLogic({ id }),
            ['fetchSpansSuccess', 'fetchNextPageSuccess'],
            tracingCorrelationConfigLogic,
            ['loadTracingConfigSuccess'],
        ],
    })),

    loaders(({ values }) => ({
        errorCounts: [
            EMPTY_COUNTS,
            {
                loadErrorCounts: async (_: void, breakpoint): Promise<SpanErrorCounts> => {
                    // Wait first, so a lookup a faster page supersedes pays for none of the work
                    // below. Everything after this reads one snapshot, which keeps the ids and the
                    // range in agreement.
                    await breakpoint(LOOKUP_DEBOUNCE_MS)

                    const known = values.errorCounts
                    const teamId = values.currentTeamId
                    if (!teamId) {
                        return known
                    }
                    const rows = values.listRows

                    // Both lookups read the same snapshot and neither needs the other's answer, so
                    // they go out together rather than one after the other.
                    //
                    // A failure in either is swallowed because the badge is decoration on a list
                    // that stays useful without it, and a toast would repeat on every page. The ids
                    // stay unanswered, so the next page asks again.
                    const [exact, session] = await Promise.all([
                        lookUpExactCounts(rows, known, teamId),
                        lookUpSessionCounts(rows, known, values.sessionIdByRow, teamId),
                    ])
                    breakpoint()

                    return { ...known, ...exact, session: { ...known.session, ...session } }
                },
            },
        ],
    })),

    reducers({
        errorCounts: {
            // A fresh page answers different filters, so the counts stop applying the moment it
            // lands. Clearing here rather than inside the lookup keeps that true even when a next
            // page supersedes the lookup before its debounce elapses.
            fetchSpansSuccess: () => EMPTY_COUNTS,
        },
    }),

    selectors({
        sessionIdByRow: [
            (s) => [s.listRows, s.configuredSessionIdKeys, s.sessionErrorBadgesEnabled],
            (
                listRows: Span[],
                configuredSessionIdKeys: string[] | undefined,
                sessionErrorBadgesEnabled: boolean
            ): Map<string, string> => {
                // The scan reads every attribute of every loaded row, so it must not run for a
                // team that does not have the badges.
                if (!sessionErrorBadgesEnabled) {
                    return NO_SESSIONS
                }
                const byRow = new Map<string, string>()
                for (const span of listRows) {
                    // One row at a time, not the trace's other loaded spans: the list prefetches a
                    // capped number of spans per trace, so scanning them could resolve a session
                    // that a span still to load contradicts.
                    const sessionId = resolveSpanSessionId(span, configuredSessionIdKeys)
                    if (sessionId) {
                        byRow.set(span.uuid, sessionId)
                    }
                }
                return byRow
            },
        ],

        // What each row badges, and on which join. A row is absent until one of its ids is looked
        // up and comes back with exceptions, so an absent row is never a claim that it is clean.
        errorBadgeByRow: [
            (s) => [s.listRows, s.sessionIdByRow, s.errorCounts],
            (
                listRows: Span[],
                sessionIdByRow: Map<string, string>,
                errorCounts: SpanErrorCounts
            ): Map<string, SpanErrorBadge> => {
                const byRow = new Map<string, SpanErrorBadge>()
                for (const span of listRows) {
                    const { spanCount, traceCount } = exactCountsFor(span, errorCounts)
                    const sessionId = sessionIdByRow.get(span.uuid)
                    const sessionCount = sessionId ? (errorCounts.session[sessionId] ?? 0) : 0
                    // One chain, so the tier and the count it names cannot drift apart.
                    const match =
                        spanCount > 0
                            ? { tier: 'span' as const, count: spanCount }
                            : traceCount > 0
                              ? { tier: 'trace' as const, count: traceCount }
                              : sessionCount > 0
                                ? { tier: 'session' as const, count: sessionCount }
                                : null
                    if (!match) {
                        continue
                    }
                    // The narrower tier stays the label, because it names what threw. The two
                    // counts are never compared, for the reason on `alsoInSession`.
                    byRow.set(
                        span.uuid,
                        match.tier !== 'session' && sessionCount > 0 ? { ...match, alsoInSession: sessionCount } : match
                    )
                }
                return byRow
            },
        ],
    }),

    listeners(({ actions, values }) => {
        // Either way the lookup asks only about ids with no count yet. A fresh page has none,
        // because the reducer above cleared them.
        const lookUpNewIds = (): void => {
            if (values.sessionErrorBadgesEnabled) {
                actions.loadErrorCounts()
            }
        }
        return {
            fetchSpansSuccess: lookUpNewIds,
            fetchNextPageSuccess: lookUpNewIds,
            // The configured session keys can land after the first page. Rows that resolved no
            // session under the built-in keys may resolve one now, and no page event follows.
            loadTracingConfigSuccess: lookUpNewIds,
        }
    }),
])