: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
// 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,
},
]
}