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.

15.0 KB
Raw Blame
// The Usage tab renders these charts inline for flags without a usage dashboard. Event names,
// property keys, breakdown, and math must stay identical to the insights on existing usage
// dashboards, so that both surfaces report the same numbers. The test fixture in
// products/feature_flags/backend/test/usage_dashboard_fixtures.py reproduces the total volume and
// unique calls insights. The function add_enriched_insights_to_feature_flag_dashboard in
// posthog/helpers/dashboard_templates.py adds the enriched insights.
// Titles differ on purpose: update_feature_flag_dashboard looks tiles up by name, so the Python
// names are pinned, while these use sentence case. The interval here follows the user's date range
// rather than the saved dashboards' fixed "day".
import { dateMapping, dateStringToDayJs, getDefaultInterval } from 'lib/utils/dateFilters'
import { escapeHogQLString } from 'lib/utils/hogql'
import { BREAKDOWN_NULL_DISPLAY } from 'scenes/insights/utils'

import { Noun } from '~/models/groupsModel'
import { setLatestVersionsOnQuery } from '~/queries/schema/query-versions'
import {
    ChartSettings,
    DataVisualizationNode,
    DateRange,
    EventsNode,
    InsightVizNode,
    NodeKind,
    ProductKey,
    TrendsQuery,
} from '~/queries/schema/schema-general'
import { QueryContext } from '~/queries/types'
import {
    AnyPropertyFilter,
    BaseMathType,
    ChartDisplayType,
    DateMappingOption,
    GroupMathType,
    GroupTypeIndex,
    PropertyFilterType,
    PropertyOperator,
} from '~/types'

import {
    FLAG_EVALUATIONS_RETENTION_DAYS,
    FLAG_EVALUATIONS_TABLE,
    flagEvaluationsRetentionStart,
    reachesPastFlagEvaluationsRetention,
} from './flagEvaluationsTable'

export interface FlagUsageQueryOptions {
    flagKey: string
    aggregationGroupTypeIndex: number | null | undefined
    /** Noun matching aggregationGroupTypeIndex, e.g. from groupsModel's aggregationLabel(index, true). */
    callerNoun: Noun
    dateRange: DateRange
}

export const DEFAULT_USAGE_DATE_RANGE: DateRange = { date_from: '-30d', date_to: null }

export type FlagUsageQuery = InsightVizNode<TrendsQuery> | DataVisualizationNode

export interface FlagUsageChart<Q extends FlagUsageQuery = FlagUsageQuery> {
    key: string
    title: string
    description: string
    query: Q
    emptyState?: Pick<QueryContext, 'emptyStateHeading' | 'emptyStateDetail'>
}

// A cached empty daily result can hide new calls for hours, so point at Reload and the log, not the query.
const FLAG_CALLS_EMPTY_STATE: FlagUsageChart['emptyState'] = {
    emptyStateHeading: 'No calls to this flag in this date range',
    emptyStateDetail:
        'New calls can take a few minutes to show in the charts. Click Reload to check again. The log below lists calls as they arrive.',
}

function flagCalledProperties({ flagKey, aggregationGroupTypeIndex }: FlagUsageQueryOptions): AnyPropertyFilter[] {
    const properties: AnyPropertyFilter[] = [
        {
            key: '$feature_flag',
            type: PropertyFilterType.Event,
            operator: PropertyOperator.Exact,
            value: flagKey,
        },
    ]
    if (aggregationGroupTypeIndex != null) {
        properties.push({
            key: `$group_${aggregationGroupTypeIndex}`,
            type: PropertyFilterType.Event,
            operator: PropertyOperator.IsSet,
            value: 'is_set',
        })
    }
    return properties
}

function buildUsageQuery(
    dateRange: DateRange,
    source: Pick<TrendsQuery, 'series' | 'properties' | 'breakdownFilter'>,
    display: ChartDisplayType
): InsightVizNode<TrendsQuery> {
    return setLatestVersionsOnQuery({
        kind: NodeKind.InsightVizNode,
        source: {
            kind: NodeKind.TrendsQuery,
            ...source,
            dateRange,
            interval: getDefaultInterval(dateRange.date_from ?? null, dateRange.date_to ?? null),
            filterTestAccounts: false,
            trendsFilter: { display, aggregationAxisFormat: 'numeric' },
            tags: { productKey: ProductKey.FEATURE_FLAGS },
        },
    })
}

export function buildFlagCalledTotalVolumeChart(
    options: FlagUsageQueryOptions
): FlagUsageChart<InsightVizNode<TrendsQuery>> {
    return {
        key: 'total-volume',
        title: 'Feature flag called total volume',
        description: `Shows the number of total calls made on feature flag with key: ${options.flagKey}`,
        query: buildUsageQuery(
            options.dateRange,
            {
                series: [{ kind: NodeKind.EventsNode, event: '$feature_flag_called', name: '$feature_flag_called' }],
                breakdownFilter: { breakdown: '$feature_flag_response', breakdown_type: 'event' },
                properties: flagCalledProperties(options),
            },
            ChartDisplayType.ActionsLineGraph
        ),
        emptyState: FLAG_CALLS_EMPTY_STATE,
    }
}

export function buildFlagCalledUniqueCallersChart(
    options: FlagUsageQueryOptions
): FlagUsageChart<InsightVizNode<TrendsQuery>> {
    const mathProperties: Pick<EventsNode, 'math' | 'math_group_type_index'> =
        options.aggregationGroupTypeIndex != null
            ? {
                  math: GroupMathType.UniqueGroup,
                  math_group_type_index: options.aggregationGroupTypeIndex as GroupTypeIndex,
              }
            : { math: BaseMathType.UniqueUsers }
    return {
        key: 'unique-callers',
        title: `Feature flag calls made by unique ${options.callerNoun.plural} per variant`,
        description: `Shows the number of unique ${options.callerNoun.singular} calls made on feature flag per variant with key: ${options.flagKey}`,
        query: buildUsageQuery(
            options.dateRange,
            {
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$feature_flag_called',
                        name: '$feature_flag_called',
                        ...mathProperties,
                    },
                ],
                breakdownFilter: { breakdown: '$feature_flag_response', breakdown_type: 'event' },
                properties: flagCalledProperties(options),
            },
            ChartDisplayType.ActionsTable
        ),
        emptyState: FLAG_CALLS_EMPTY_STATE,
    }
}

export function buildEnrichedUsageCharts(
    options: Pick<FlagUsageQueryOptions, 'flagKey' | 'dateRange'>
): FlagUsageChart<InsightVizNode<TrendsQuery>>[] {
    return [
        {
            key: 'feature-view',
            title: 'Feature viewed total volume',
            description: 'Shows the total number of times this feature was viewed',
            query: buildUsageQuery(
                options.dateRange,
                {
                    series: enrichedSeries('$feature_view', 'Feature view'),
                    properties: enrichedProperties(options.flagKey),
                },
                ChartDisplayType.ActionsLineGraph
            ),
        },
        {
            key: 'feature-interaction',
            title: 'Feature interaction total volume',
            description: 'Shows the total number of times this feature was interacted with',
            query: buildUsageQuery(
                options.dateRange,
                {
                    series: enrichedSeries('$feature_interaction', 'Feature interaction'),
                    properties: enrichedProperties(options.flagKey),
                },
                ChartDisplayType.ActionsLineGraph
            ),
        },
    ]
}

function enrichedSeries(event: '$feature_view' | '$feature_interaction', seriesLabel: string): EventsNode[] {
    return [
        { kind: NodeKind.EventsNode, event, name: `${seriesLabel} - Total` },
        { kind: NodeKind.EventsNode, event, name: `${seriesLabel} - Unique users`, math: BaseMathType.UniqueUsers },
    ]
}

// The table reads a null or missing $feature_flag_response as NULL. The events-mode breakdown labels that
// bucket BREAKDOWN_NULL_DISPLAY, so these charts do the same.
// The label is in the query because the SQL line chart names a NULL series "[No value]" and the SQL
// table draws a NULL cell as a dash. A variant whose key equals the label merges into this bucket. The flag
// editor rejects that key, but the API accepts it.
const FLAG_EVALUATIONS_VARIANT = `ifNull(response, ${escapeHogQLString(BREAKDOWN_NULL_DISPLAY)})`

/** Pulls a range back inside the retention window, where it cannot quietly show fewer rows than the events table. */
export function clampToFlagEvaluationsRetention(dateRange: DateRange): DateRange {
    if (!reachesPastFlagEvaluationsRetention(dateRange.date_from ?? null)) {
        return dateRange
    }
    const earliest = flagEvaluationsRetentionStart()
    const dateTo = dateStringToDayJs(dateRange.date_to ?? null)
    return {
        date_from: `-${FLAG_EVALUATIONS_RETENTION_DAYS}d`,
        // A range that ended before the window holds nothing, and the clamped start would sit
        // after its end. Run to now instead of showing a backwards range.
        date_to: dateTo?.isBefore(earliest) ? null : (dateRange.date_to ?? null),
    }
}

/** The presets that stay inside the retention window, plus the custom-range entry. */
export function flagEvaluationsDateOptions(): DateMappingOption[] {
    return dateMapping.filter(({ values }) => {
        const dateFrom = values[0]
        return dateFrom === undefined || !reachesPastFlagEvaluationsRetention(dateFrom)
    })
}

function flagEvaluationsConditions(
    { aggregationGroupTypeIndex, flagKey }: FlagUsageQueryOptions,
    indent: string = '    '
): string {
    // The flag key is an escaped literal rather than a placeholder because HogQLQueryRunner compiles
    // every placeholder while it parses, and `{filters(...)}` is not compilable, so a query that
    // carries both fails before it reaches replace_filters.
    // `{filters(... AS timestamp)}` binds the tab's date range to this table's own timestamp column.
    // The bare `{filters}` placeholder only knows a fixed set of tables, and this is not one of them.
    const conditions = [`flag_key = ${escapeHogQLString(flagKey)}`, '{filters(timestamp AS timestamp)}']
    if (aggregationGroupTypeIndex != null) {
        // The group columns are non-nullable and hold an empty string when the evaluation
        // carried no group, so this is the equivalent of the events path's is_set filter.
        conditions.push(`\`$group_${aggregationGroupTypeIndex}\` != ''`)
    }
    return conditions.join(`\n${indent}AND `)
}

function buildFlagEvaluationsQuery(
    options: FlagUsageQueryOptions,
    query: string,
    display: ChartDisplayType,
    chartSettings?: ChartSettings
): DataVisualizationNode {
    const { dateRange } = options
    return setLatestVersionsOnQuery({
        kind: NodeKind.DataVisualizationNode,
        source: {
            kind: NodeKind.HogQLQuery,
            query,
            filters: { dateRange },
            // The backend infers a product from the event or table a query reads, and knows neither
            // posthog.flag_evaluations nor this scene, so the tag has to be explicit. An untagged
            // ClickHouse query raises under DEBUG and records with no product in production.
            tags: { productKey: ProductKey.FEATURE_FLAGS },
        },
        display,
        chartSettings,
    })
}

/**
 * A HogQL query without a LIMIT falls back to 100 rows, which would cut the newest periods off a
 * period-ascending chart. The volume query returns one row per period per variant: at most 90 days
 * of the retention window at the shortest interval the presets reach, times the 50 series the
 * breakdown renders.
 */
export const FLAG_EVALUATIONS_VOLUME_ROW_LIMIT = 10000

export function buildFlagEvaluationsTotalVolumeChart(
    options: FlagUsageQueryOptions
): FlagUsageChart<DataVisualizationNode> {
    // dateTrunc needs a literal unit, so the interval is written into the query rather than
    // passed as a value. getDefaultInterval only returns members of IntervalType.
    const interval = getDefaultInterval(options.dateRange.date_from ?? null, options.dateRange.date_to ?? null)
    return {
        key: 'total-volume',
        title: 'Feature flag called total volume',
        description: `Shows the number of total calls made on feature flag with key: ${options.flagKey}`,
        query: buildFlagEvaluationsQuery(
            options,
            // GROUP BY only emits the periods that hold evaluations, and the chart builds its time
            // axis from the rows it gets back, so a quiet period would vanish instead of reading
            // zero. WITH FILL puts the missing periods back for each variant, and the outer query
            // restores the ascending period order the axis needs.
            `SELECT period, variant, total
FROM (
    SELECT
        dateTrunc('${interval}', timestamp) AS period,
        ${FLAG_EVALUATIONS_VARIANT} AS variant,
        count() AS total
    FROM ${FLAG_EVALUATIONS_TABLE}
    WHERE ${flagEvaluationsConditions(options, '        ')}
    GROUP BY period, variant
    ORDER BY variant, period WITH FILL STEP INTERVAL 1 ${interval}
)
ORDER BY period
LIMIT ${FLAG_EVALUATIONS_VOLUME_ROW_LIMIT}`,
            ChartDisplayType.ActionsLineGraph,
            {
                xAxis: { column: 'period' },
                yAxis: [{ column: 'total' }],
                seriesBreakdownColumn: 'variant',
                // A variant that starts or stops mid-range sits outside its own filled span.
                showNullsAsZero: true,
            }
        ),
    }
}

export function buildFlagEvaluationsUniqueCallersChart(
    options: FlagUsageQueryOptions
): FlagUsageChart<DataVisualizationNode> {
    const { aggregationGroupTypeIndex, callerNoun, flagKey } = options
    // `person_id` is not the column the row stores. HogQL resolves it through
    // person_distinct_id_overrides, so a person who evaluated the flag before and after logging in
    // counts once. That join is bounded by neither the date range nor the flag key, which means the
    // retention clamp does not make this query cheaper.
    const caller = aggregationGroupTypeIndex != null ? `\`$group_${aggregationGroupTypeIndex}\`` : 'person_id'
    return {
        key: 'unique-callers',
        title: `Feature flag calls made by unique ${callerNoun.plural} per variant`,
        description: `Shows the number of unique ${callerNoun.singular} calls made on feature flag per variant with key: ${flagKey}`,
        query: buildFlagEvaluationsQuery(
            options,
            `SELECT
    ${FLAG_EVALUATIONS_VARIANT} AS \`Variant\`,
    uniq(${caller}) AS \`Unique callers\`
FROM ${FLAG_EVALUATIONS_TABLE}
WHERE ${flagEvaluationsConditions(options)}
GROUP BY \`Variant\`
ORDER BY \`Unique callers\` DESC`,
            ChartDisplayType.ActionsTable
        ),
    }
}

// Enriched analytics events carry the flag key in the bare `feature_flag` property,
// unlike $feature_flag_called which uses `$feature_flag`.
function enrichedProperties(flagKey: string): AnyPropertyFilter[] {
    return [
        {
            key: 'feature_flag',
            type: PropertyFilterType.Event,
            operator: PropertyOperator.Exact,
            value: flagKey,
        },
    ]
}