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.

12.3 KB
Raw Blame
import { formatDateRangeLabel } from 'lib/components/DateFilter/DateRangePicker/utils'
import { isValidPropertyFilter } from 'lib/components/PropertyFilters/utils'
import { dayjs } from 'lib/dayjs'
import { capitalizeFirstLetter } from 'lib/utils/strings'

import { AnyPropertyFilter, PropertyOperator } from '~/types'

import { LogsViewerFilters } from 'products/logs/frontend/components/LogsViewer/config/types'
import {
    FacetFilterTarget,
    SERVICE_NAME_FILTER,
    SEVERITY_LEVEL_FILTER,
    facetSelection,
} from 'products/logs/frontend/components/LogsViewer/FacetRail/facetFilters'

/**
 * A level or service selection reaches a summary in one of two shapes: the dedicated
 * `severityLevels`/`serviceNames` field, which saved views, alerts and persisted filter history can
 * carry, or the `exact` log filter in `filterGroup`, which is what the viewer writes. Read both, so
 * an entry in either shape summarizes identically.
 */
export function summaryColumnSelection(
    filters: Record<string, any>,
    legacyField: 'severityLevels' | 'serviceNames',
    target: FacetFilterTarget
): string[] {
    const legacy = filters[legacyField]
    if (Array.isArray(legacy) && legacy.length > 0) {
        return legacy as string[]
    }
    return facetSelection(filters.filterGroup, target).included
}

/**
 * One `key=value` string per property filter in the group. `skipIncludes` drops the `exact` filters
 * under the given targets, for callers that summarize those selections under their own label.
 */
export function formatFilterGroupValues(
    filterGroup: Record<string, any> | undefined,
    skipIncludes: FacetFilterTarget[] = []
): string[] {
    const group = filterGroup?.values?.[0]
    if (!group || !('values' in group)) {
        return []
    }

    const isSkipped = (filter: AnyPropertyFilter): boolean =>
        'operator' in filter &&
        filter.operator === PropertyOperator.Exact &&
        skipIncludes.some((target) => filter.type === target.type && filter.key === target.key)

    return group.values
        .filter(isValidPropertyFilter)
        .filter((filter: AnyPropertyFilter) => !isSkipped(filter))
        .map((filter: AnyPropertyFilter) => {
            const key = filter.key || '?'
            const value = Array.isArray(filter.value) ? filter.value.join(', ') : String(filter.value ?? '')
            const truncatedValue = value.length > 15 ? `${value.slice(0, 15)}...` : value
            return `${key}=${truncatedValue}`
        })
}

export interface FiltersSummaryLine {
    label: string
    value: string
}

export function getFiltersSummaryLines(filters: Record<string, any>): FiltersSummaryLine[] {
    const lines: FiltersSummaryLine[] = []

    if (filters.dateRange) {
        const label = formatDateRangeLabel(filters.dateRange, Intl.DateTimeFormat().resolvedOptions().timeZone, [])
        lines.push({ label: 'Date range', value: label })
    }

    const severityLevels = summaryColumnSelection(filters, 'severityLevels', SEVERITY_LEVEL_FILTER)
    if (severityLevels.length > 0) {
        lines.push({
            label: 'Severity',
            value: severityLevels.map((l: string) => capitalizeFirstLetter(l)).join(', '),
        })
    }

    const serviceNames = summaryColumnSelection(filters, 'serviceNames', SERVICE_NAME_FILTER)
    if (serviceNames.length > 0) {
        const maxDisplayed = 3
        const displayed = serviceNames.slice(0, maxDisplayed)
        const remaining = serviceNames.length - displayed.length
        const serviceText = displayed.join(', ')
        lines.push({
            label: serviceNames.length === 1 ? 'Service' : 'Services',
            value: remaining > 0 ? `${serviceText} +${remaining} more` : serviceText,
        })
    }

    if (filters.searchTerm) {
        const truncated = filters.searchTerm.length > 30 ? `${filters.searchTerm.slice(0, 30)}...` : filters.searchTerm
        lines.push({ label: 'Search', value: `"${truncated}"` })
    }

    // Skips the `exact` log filters the Severity and Service lines above already cover, so a
    // group-stored selection isn't reported twice. Only where the line came from the group: a line
    // read off the legacy field says nothing about the group, so skipping there would drop a
    // `severity_level =` chip from the summary entirely. Exclusions always show here.
    const usedLegacyField = (legacyField: 'severityLevels' | 'serviceNames'): boolean =>
        Array.isArray(filters[legacyField]) && filters[legacyField].length > 0
    const attributeFilters = formatFilterGroupValues(filters.filterGroup, [
        ...(usedLegacyField('severityLevels') ? [] : [SEVERITY_LEVEL_FILTER]),
        ...(usedLegacyField('serviceNames') ? [] : [SERVICE_NAME_FILTER]),
    ])
    if (attributeFilters.length > 0) {
        lines.push({
            label: attributeFilters.length === 1 ? 'Filter' : 'Filters',
            value: attributeFilters.join(', '),
        })
    }

    return lines
}

// Mirror of DISTINCT_ID_ATTRIBUTE_KEY_CONVENTIONS in products/logs/backend/models.py — keep the
// two in sync. Values under these keys render as clickable person links here, and the person
// Logs tab scopes on them server-side so those logs appear on the person's tab.
const DISTINCT_ID_KEYS = [
    'distinct.id',
    'distinct_id',
    'distinctId',
    'distinctID',
    'posthogDistinctId',
    'posthogDistinctID',
    'posthog_distinct_id',
    'posthog.distinct.id',
    'posthog.distinct_id',
]
// Mirror of SESSION_ID_ATTRIBUTE_KEY_CONVENTIONS in products/logs/backend/models.py — keep the
// two in sync, or the impact counts stop covering logs this list renders as session links.
// Some pipelines emit `posthogSessionId` even though no SDK does. Removing it breaks them.
const SESSION_ID_KEYS = [
    'session.id',
    'session_id',
    'sessionId',
    'sessionID',
    '$session_id',
    'posthogSessionId',
    'posthogSessionID',
    'posthog_session_id',
    'posthog.session.id',
    'posthog.session_id',
]

// Built once at module scope: this runs per attribute key of every log row, and per attribute
// of every span of an open trace.
const DISTINCT_ID_EXACT_KEYS = new Set(DISTINCT_ID_KEYS)
const DISTINCT_ID_SUFFIXES = DISTINCT_ID_KEYS.map((candidate) => `.${candidate}`)
const SESSION_ID_EXACT_KEYS = new Set(SESSION_ID_KEYS)
const SESSION_ID_SUFFIXES = SESSION_ID_KEYS.map((candidate) => `.${candidate}`)

function matchesKey(key: string, exactKeys: Set<string>, suffixes: string[]): boolean {
    return exactKeys.has(key) || suffixes.some((suffix) => key.endsWith(suffix))
}

// Configured keys (the team's `logs_distinct_id_attribute_keys` setting) match exactly;
// only the built-in convention list gets dot-suffix matching.
export function isDistinctIdKey(key: string, configuredKeys?: string[]): boolean {
    return !!configuredKeys?.includes(key) || matchesKey(key, DISTINCT_ID_EXACT_KEYS, DISTINCT_ID_SUFFIXES)
}

// Configured keys (the team's `logs_session_id_attribute_keys` setting) match exactly;
// only the built-in convention list gets dot-suffix matching.
export function isSessionIdKey(key: string, configuredKeys?: string[]): boolean {
    return !!configuredKeys?.includes(key) || matchesKey(key, SESSION_ID_EXACT_KEYS, SESSION_ID_SUFFIXES)
}

export interface LogIdentityMatch {
    key: string
    value: string
    source: 'attribute' | 'resource_attribute'
}

// A configured key is an arbitrary team setting, so read it as an own property. Bare bracket
// access resolves a key like `constructor` or `valueOf` to the Object.prototype member, which is
// truthy and would be returned as though the attribute held it.
function ownValue(attributes: Record<string, unknown> | undefined, key: string): unknown {
    return attributes && Object.hasOwn(attributes, key) ? attributes[key] : undefined
}

function getIdentityMatch(
    attributes: Record<string, unknown> | undefined,
    resourceAttributes: Record<string, unknown> | undefined,
    configuredKeys: string[] | undefined,
    isConventionKey: (key: string) => boolean
): LogIdentityMatch | null {
    // Configured keys win over the built-in conventions, in list order: for each key,
    // attributes are checked before resource_attributes, and the first value found wins.
    for (const key of configuredKeys ?? []) {
        const attributeValue = ownValue(attributes, key)
        if (attributeValue) {
            return { key, value: String(attributeValue), source: 'attribute' }
        }
        const resourceAttributeValue = ownValue(resourceAttributes, key)
        if (resourceAttributeValue) {
            return { key, value: String(resourceAttributeValue), source: 'resource_attribute' }
        }
    }
    // Built-in convention fallback only — the configured-key pass already ran above, so
    // isConventionKey is deliberately called without the configured keys here.
    for (const key of Object.keys(attributes || {})) {
        const value = attributes?.[key]
        if (value && isConventionKey(key)) {
            return { key, value: String(value), source: 'attribute' }
        }
    }
    for (const key of Object.keys(resourceAttributes || {})) {
        const value = resourceAttributes?.[key]
        if (value && isConventionKey(key)) {
            return { key, value: String(value), source: 'resource_attribute' }
        }
    }
    return null
}

export function getSessionIdWithKey(
    attributes: Record<string, unknown> | undefined,
    resourceAttributes: Record<string, unknown> | undefined,
    configuredKeys?: string[]
): LogIdentityMatch | null {
    return getIdentityMatch(attributes, resourceAttributes, configuredKeys, (key) => isSessionIdKey(key))
}

/** The distinct-id counterpart of `getSessionIdWithKey`, resolved the same way. */
export function getDistinctIdWithKey(
    attributes: Record<string, unknown> | undefined,
    resourceAttributes: Record<string, unknown> | undefined,
    configuredKeys?: string[]
): LogIdentityMatch | null {
    return getIdentityMatch(attributes, resourceAttributes, configuredKeys, (key) => isDistinctIdKey(key))
}

export function getSessionIdFromLogAttributes(
    attributes: Record<string, unknown> | undefined,
    resourceAttributes: Record<string, unknown> | undefined,
    configuredKeys?: string[]
): string | null {
    return getSessionIdWithKey(attributes, resourceAttributes, configuredKeys)?.value ?? null
}

// Log timestamps are ISO strings, but some pipelines send epoch numbers instead. Shared so every
// surface reading `LogMessage.timestamp` parses it the same way.
export function parseLogTimestamp(timestamp: string): dayjs.Dayjs {
    const epoch = Number(timestamp)
    return Number.isNaN(epoch) ? dayjs(timestamp) : dayjs(epoch)
}

// How far either side of a log the Related errors lookup searches for exceptions in the same
// session. Shared so the drawer's tab and the row badge that opens it agree on the range.
export const RELATED_ERRORS_WINDOW_HOURS = 6

// Wide enough to cover a session around a single event without drowning it in unrelated logs.
export const SESSION_LOGS_WINDOW_MINUTES = 30

// Tighter than SESSION_LOGS_WINDOW_MINUTES because the exception card's Logs tab can run unscoped,
// where the range is all that holds it off the project's whole log volume.
export const EXCEPTION_LOGS_WINDOW_MINUTES = 5

export function buildDateRangeAround(timestamp: string, windowMinutes: number): { date_from: string; date_to: string } {
    const center = dayjs(timestamp)
    return {
        date_from: center.subtract(windowMinutes, 'minute').toISOString(),
        date_to: center.add(windowMinutes, 'minute').toISOString(),
    }
}

// Builds the viewer scope for one session, for other products surfacing logs (error tracking,
// session replay). The session id goes to the server as a scope rather than a filter group: it
// has to match across every configured and conventional key in both attribute maps, and the
// query runner reads a filter group's inner group as an AND of its leaves, so a group could only
// ever express "every key holds this id at once". A timestamp scopes the date range to
// windowMinutes either side, so old sessions aren't hidden by the viewer's default range.
export function buildLogsSessionScope(
    sessionId: string | undefined,
    timestamp?: string,
    windowMinutes: number = SESSION_LOGS_WINDOW_MINUTES
): { sessionId?: string; initialFilters?: Partial<LogsViewerFilters> } {
    return {
        sessionId,
        initialFilters: timestamp ? { dateRange: buildDateRangeAround(timestamp, windowMinutes) } : undefined,
    }
}