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.

9.6 KB
Raw Blame
import type {
    ErrorTrackingIssueListItemApi,
    ErrorTrackingIssuesListQueryRequestApi,
    ErrorTrackingIssuesListResponseApi,
} from '../../../error_tracking/frontend/generated/api.schemas'
import type { SignalsReportsListParams } from '../../../signals/frontend/generated/api.schemas'

import { apiJson, projectPath } from './client'
import { type InboxPageApi, type ProjectScope, scopeKey } from './reports'

// Shapes follow the serializers in `products/error_tracking/backend/presentation/views/`: `query_serializers.py` for
// the compact `error_tracking/query/` reads, `issues.py` for the issue resource and `spike_events.py`. Every endpoint
// here needs `error_tracking:read`, and the writes need `error_tracking:write`.

export type IssueStatusApi = 'active' | 'resolved' | 'suppressed' | 'archived' | 'pending_release'
export type WritableIssueStatus = 'active' | 'resolved' | 'suppressed'

/** `ErrorTrackingIssueAssigneeReadSerializer`: a user's numeric id, or a role's UUID. */
export interface IssueAssigneeApi {
    id?: number | string | null
    type?: 'user' | 'role' | string | null
}

/** `ErrorTrackingAggregationsSerializer`. Counts arrive as floats. */
export interface IssueAggregationsApi {
    occurrences?: number
    users?: number
    sessions?: number
    volumeRange?: number[]
}

export type IssueListItemApi = ErrorTrackingIssueListItemApi
export type IssuesListResponseApi = ErrorTrackingIssuesListResponseApi

export interface IssueReleaseApi {
    version?: string
    commit_id?: string
    branch?: string
}

export interface IssueTrendApi {
    direction: 'increasing' | 'decreasing' | 'stable' | 'new'
    change_percent?: number
}

export interface IssueSummaryApi extends IssueListItemApi {
    impact?: { occurrences?: number; users?: number; sessions?: number }
    trend?: IssueTrendApi
    sparkline?: number[]
    latest_release?: IssueReleaseApi
    first_release?: IssueReleaseApi
}

export interface BreakdownValueApi {
    value: string
    count: number
}

/** `ErrorTrackingIssueBreakdownSerializer`. A dimension with no values is left out of `top_values`. */
export interface IssueBreakdownApi {
    occurrences: number
    sample_session_ids: string[]
    top_values: Partial<
        Record<'path' | 'url' | 'screen' | 'browser' | 'os' | 'library' | 'app_version', BreakdownValueApi[]>
    >
}

export interface StackFrameApi {
    resolved_name?: string | null
    mangled_name?: string | null
    function?: string | null
    source?: string | null
    line?: number | null
    in_app?: boolean
}

export interface ExceptionApi {
    type?: string
    value?: string
    /** `same_as_event` replaces a stack the page already returned; the app reads frames from the first copy only. */
    stacktrace?: { frames?: StackFrameApi[] } | null
}

export interface IssueEventApi {
    uuid?: string
    timestamp?: string
    properties?: {
        $exception_list?: ExceptionApi[]
        $session_id?: string | null
        $browser?: string | null
        $os?: string | null
    }
}

export interface IssueEventsResponseApi {
    results: IssueEventApi[]
}

export interface IssueApi {
    id: string
    status: IssueStatusApi
    name: string | null
    description: string | null
    first_seen: string | null
    assignee: IssueAssigneeApi | null
}

export interface SpikeEventApi {
    issue: { id: string }
    detected_at: string
}

export interface SpikeEventsResponseApi {
    results: SpikeEventApi[]
}

export type ErrorsWindow = '24h' | '7d'

export const ISSUE_BUCKETS: Record<ErrorsWindow, number> = { '24h': 24, '7d': 28 }
export const ISSUES_PAGE_SIZE = 15
export const ISSUE_EVENTS_LIMIT = 10

export function windowDateRange(window: ErrorsWindow): { date_from: string } {
    return { date_from: window === '24h' ? '-24h' : '-7d' }
}

export interface IssuesListInput {
    window: ErrorsWindow
    assigneeUserId?: number
}

export function issuesListBody(
    { window, assigneeUserId }: IssuesListInput,
    offset = 0
): ErrorTrackingIssuesListQueryRequestApi {
    return {
        dateRange: windowDateRange(window),
        status: 'active',
        orderBy: 'users',
        orderDirection: 'DESC',
        limit: ISSUES_PAGE_SIZE,
        offset,
        volumeResolution: 0,
        ...(assigneeUserId === undefined ? {} : { assignee: { type: 'user', id: assigneeUserId } }),
    }
}

export function fetchIssues(input: IssuesListInput, signal?: AbortSignal, offset = 0): Promise<IssuesListResponseApi> {
    return apiJson<IssuesListResponseApi>(projectPath('error_tracking/query/issues/'), {
        method: 'POST',
        json: issuesListBody(input, offset),
        signal,
    })
}

export function fetchIssueSummary(
    issueId: string,
    window: ErrorsWindow,
    signal?: AbortSignal
): Promise<IssueSummaryApi> {
    return apiJson<IssueSummaryApi>(projectPath('error_tracking/query/issue/'), {
        method: 'POST',
        json: {
            issueId,
            dateRange: windowDateRange(window),
            includeSparkline: true,
            volumeResolution: ISSUE_BUCKETS[window],
        },
        signal,
    })
}

/**
 * The same endpoint with `includeBreakdown`, as its own request: the breakdown adds an aggregate query, and the server
 * fails the whole response when it cannot compute it, so it must not hold up or break the impact numbers.
 */
export async function fetchIssueBreakdown(
    issueId: string,
    window: ErrorsWindow,
    signal?: AbortSignal
): Promise<IssueBreakdownApi | null> {
    const summary = await apiJson<IssueSummaryApi & { breakdown?: IssueBreakdownApi }>(
        projectPath('error_tracking/query/issue/'),
        {
            method: 'POST',
            json: { issueId, dateRange: windowDateRange(window), includeBreakdown: true },
            signal,
        }
    )
    return summary.breakdown ?? null
}

export function fetchIssueEvents(
    issueId: string,
    window: ErrorsWindow,
    signal?: AbortSignal
): Promise<IssueEventsResponseApi> {
    return apiJson<IssueEventsResponseApi>(projectPath('error_tracking/query/issue_events/'), {
        method: 'POST',
        json: {
            issueId,
            dateRange: windowDateRange(window),
            limit: ISSUE_EVENTS_LIMIT,
            include: ['exception', 'stacktrace', 'environment', 'correlation'],
            onlyAppFrames: true,
        },
        signal,
    })
}

export function fetchIssue(issueId: string, signal?: AbortSignal): Promise<IssueApi> {
    return apiJson<IssueApi>(projectPath(`error_tracking/issues/${encodeURIComponent(issueId)}/`), { signal })
}

export function updateIssueStatus(issueId: string, status: WritableIssueStatus): Promise<IssueApi> {
    return apiJson<IssueApi>(projectPath(`error_tracking/issues/${encodeURIComponent(issueId)}/`), {
        method: 'PATCH',
        json: { status },
    })
}

/** `null` removes the assignment. */
export async function assignIssue(issueId: string, userId: number | null): Promise<void> {
    await apiJson<unknown>(projectPath(`error_tracking/issues/${encodeURIComponent(issueId)}/assign/`), {
        method: 'PATCH',
        json: { assignee: userId === null ? null : { type: 'user', id: userId } },
    })
}

export const SPIKE_EVENTS_LIMIT = 100

export function fetchSpikeEvents(
    issueIds: readonly string[],
    dateFrom: string,
    signal?: AbortSignal
): Promise<SpikeEventsResponseApi> {
    return apiJson<SpikeEventsResponseApi>(projectPath('error_tracking/spike_events/'), {
        query: { issue_ids: issueIds.join(','), date_from: dateFrom, limit: SPIKE_EVENTS_LIMIT },
        signal,
    })
}

/**
 * `GET signals/reports/` narrowed to reports built from this issue's signals: error tracking signals carry the issue
 * id as their `source_id`. Needs `task:read`, which the inbox already uses.
 */
export function fetchIssueReports(issueId: string, signal?: AbortSignal): Promise<InboxPageApi> {
    return apiJson<InboxPageApi>(projectPath('signals/reports/'), {
        query: {
            source_product: 'error_tracking',
            source_id: issueId,
            limit: 1,
            include_source_metadata: false,
        } satisfies SignalsReportsListParams,
        signal,
    })
}

/** Query keys. Every key carries the host and project so a project switch never shows stale data. */
export const errorTrackingKeys = {
    all: (scope: ProjectScope | null) => ['error_tracking', ...scopeKey(scope)] as const,
    lists: (scope: ProjectScope | null) => [...errorTrackingKeys.all(scope), 'issues'] as const,
    list: (scope: ProjectScope | null, input: IssuesListInput) =>
        [...errorTrackingKeys.lists(scope), input.window, input.assigneeUserId ?? null, 'pages'] as const,
    spikes: (scope: ProjectScope | null, window: ErrorsWindow, issueIds: readonly string[]) =>
        [...errorTrackingKeys.all(scope), 'spikes', window, issueIds.join(',')] as const,
    issueAll: (scope: ProjectScope | null, issueId: string) =>
        [...errorTrackingKeys.all(scope), 'issue', issueId] as const,
    issue: (scope: ProjectScope | null, issueId: string) =>
        [...errorTrackingKeys.issueAll(scope, issueId), 'detail'] as const,
    summary: (scope: ProjectScope | null, issueId: string, window: ErrorsWindow) =>
        [...errorTrackingKeys.issueAll(scope, issueId), 'summary', window] as const,
    breakdown: (scope: ProjectScope | null, issueId: string, window: ErrorsWindow) =>
        [...errorTrackingKeys.issueAll(scope, issueId), 'breakdown', window] as const,
    events: (scope: ProjectScope | null, issueId: string, window: ErrorsWindow) =>
        [...errorTrackingKeys.issueAll(scope, issueId), 'events', window] as const,
    reports: (scope: ProjectScope | null, issueId: string) =>
        [...errorTrackingKeys.issueAll(scope, issueId), 'reports'] as const,
}