: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
from datetime import UTC, datetime, timedelta
from enum import StrEnum
from django.db.models import Q, QuerySet
import structlog
from posthog.dataclasses import frozen
from .facade.config import ConfigFormatError
from .facade.filters import condition_aggregation, condition_rollout_percentage, pinned_variant
from .models.feature_flag import FeatureFlag
logger = structlog.get_logger(__name__)
FeatureFlagStatusReason = str
STALE_FLAG_THRESHOLD_DAYS = 30
def stale_flag_threshold() -> datetime:
"""The cutoff that both staleness signals compare against.
A flag with usage data is stale when `last_called_at` is older than this. A flag with no
usage data is only considered at all when `created_at` is older than this.
"""
return datetime.now(UTC) - timedelta(days=STALE_FLAG_THRESHOLD_DAYS)
class FeatureFlagStatus(StrEnum):
ACTIVE = "active"
STALE = "stale"
ARCHIVED = "archived"
DELETED = "deleted"
UNKNOWN = "unknown"
@frozen
class FeatureFlagRolloutSummary:
# Whether the flag is effectively rolled out to everyone, independent of recent evaluation.
effectively_full_rollout: bool
# Whether any release condition has property filters (conditionally targeted vs. blanket rollout).
has_targeting_conditions: bool
# Highest rollout percentage across release conditions, or None when there are no conditions.
# A fractional rollout (e.g. 0.5) stays a float, matching how conditions store the value.
max_rollout_percentage: int | float | None
# Whether the flag serves multiple variants.
is_multivariate: bool
# Shared rollout-state vocabulary. The bulk-delete API response and the stale-flags
# health check both serve these strings, and the frontend consumes them as an enum,
# so the mapping in `rollout_state_and_variant` is the single place they come from.
ROLLOUT_FULLY_ROLLED_OUT = "fully_rolled_out"
ROLLOUT_NOT_ROLLED_OUT = "not_rolled_out"
ROLLOUT_PARTIAL = "partial"
def exclude_archived_unless_requested(queryset: QuerySet, *, requested: bool) -> QuerySet:
"""Hide archived flags unless the caller explicitly asked for them.
This is the API's default for the list, `matching_ids`, and filter-based `bulk_delete`
paths — archived flags stay out of "select all" / bulk-delete sets unless `archived` is
passed. `requested` is whether the caller asked to see archived flags: an `archived` param,
or the list's `deleted=true` view, which shows a deleted flag whether or not it was archived
first. The value filter itself is applied separately. The frontend `flagMatchesFilters` keeps
its own mirror.
"""
if not requested:
return queryset.filter(archived=False)
return queryset
# `jsonb_array_elements` and `jsonb_array_length` raise on a value that is not an array, and the
# error aborts the whole statement instead of skipping the row. A detection batch covers 250 teams,
# so one legacy flag storing `groups` as a scalar would take the query down for every team in it.
# These read a non-array as an empty array. `CASE` is the only construct that guarantees the type
# test runs before the array function; the planner is free to reorder the arms of `AND` and `OR`.
# Both predicates below interpolate these, so they are f-strings and every literal `{}` in their
# SQL is written `{{}}`.
def jsonb_array_or_empty(expr: str) -> str:
return f"CASE WHEN jsonb_typeof({expr}) = 'array' THEN {expr} ELSE '[]'::jsonb END"
_GROUPS_ARRAY = jsonb_array_or_empty("posthog_featureflag.filters->'groups'")
_VARIANTS_ARRAY = jsonb_array_or_empty("posthog_featureflag.filters->'multivariate'->'variants'")
# A release condition carries no targeting when `properties` is `[]`, absent, or JSON null, which
# is how `is_group_fully_rolled_out` and `is_boolean_flag_fully_rolled_out` read it. Postgres `->`
# returns SQL NULL for the absent key and the jsonb scalar `null` for the stored null, so each
# needs its own test. The editor and the filters serializer write `[]`, so only unedited legacy
# rows hold the other two.
_ELEM_HAS_NO_TARGETING = (
"("
"(elem->'properties')::text = '[]'::text "
"OR elem->'properties' IS NULL "
"OR jsonb_typeof(elem->'properties') = 'null'"
")"
)
# Every branch of `FeatureFlagStatusChecker.is_flag_fully_rolled_out` needs a release condition at
# an explicit 100% with no targeting, so both predicates below test for one. Keep it in one place,
# because a change to how the two read that shape has to reach the stale filter and the rollout
# prefilter together or they classify the same flag differently.
_HAS_UNTARGETED_FULL_ROLLOUT_GROUP = f"""
EXISTS (
SELECT 1 FROM jsonb_array_elements({_GROUPS_ARRAY}) AS elem
WHERE elem->>'rollout_percentage' = '100'
AND {_ELEM_HAS_NO_TARGETING}
)
"""
def filter_stale_flags(queryset: QuerySet, *, stale_threshold: datetime | None = None) -> QuerySet:
"""
Narrow a FeatureFlag queryset to the flags that count as stale.
Set-based counterpart to `FeatureFlagStatusChecker.get_status`, which answers the same
question for one flag and also produces the human-readable reason. The two are meant to
classify the same flags, so change them together. `STALE_ACTIVE_PARAM_DESCRIPTION` states
these branches in prose for the published API schemas, so change it with them too.
They do not agree on three shapes. First, the checker calls a flag with no release conditions
fully rolled out, so `filters` of `{"groups": []}` (the model default) is STALE to the checker
and not stale here, because the config branch below matches an empty `filters` only as `NULL`
or `{}`. Matching the model default would make every unconfigured flag in a project stale.
Second, a multivariate flag is stale here as soon as a variant sits at 100% under an
untargeted 100% condition, or that condition carries a variant override, while the checker
requires every reachable path to serve the same variant. A flag that serves two variants is
therefore stale to the SQL and not to the checker.
Third, the SQL does not read aggregation. In a flag of either type that mixes person and
group aggregation, it counts a group-aggregated condition at 100% with no property filters,
which the checker does not, because the matcher skips that condition for a request without
the group key.
The SQL stays as it is on purpose: it backs the public `active=STALE` filter, and reading
declaration order, cumulative variant slices and aggregation in raw SQL would cost more than
the filter is worth.
`test_stale_filter_agrees_with_status_checker` covers the shapes where the two do agree.
The caller supplies the scope, so pass a queryset already narrowed to the team.
Pass `stale_threshold` to hold one detection run to one cutoff, so the caller can compare
its other queries against the same instant. Without it the function reads the clock itself,
which is what the `active=STALE` filter wants.
The config branch's raw SQL rides on `.extra(where=...)`, and that clause stays on that
branch when the two querysets are OR-combined below. Applied to the combined query, it
would narrow the usage-based branch too and drop flags that are stale only by usage.
`test_filters_stale` covers that case.
Compose it by chaining `.filter()`, and keep the result a top-level queryset. The raw
predicate hard-codes the `posthog_featureflag` table name. Nesting the result aliases the
inner table, so the raw text resolves against the outer row instead.
`pk__in=<queryset>` survives that, because `id IN (...)` ties the inner row to the outer
row. A correlated `Exists()` or `Subquery()` joined on anything else, such as `team_id`,
does not. The config branch then tests the outer flag's `filters` while the inner query
ranges over the team's other flags, and returns a wrong set of flags with no error.
Postgres rejects the query only when the outer scope holds no `posthog_featureflag`.
"""
# Get stale flags using the best available signal:
# 1. If last_called_at exists: flag hasn't been called in 30+ days
# 2. If last_called_at is NULL: flag is 100% rolled out and 30+ days old
if stale_threshold is None:
stale_threshold = stale_flag_threshold()
usage_based_stale = Q(last_called_at__lt=stale_threshold, active=True)
# nosemgrep: python.django.security.audit.query-set-extra.avoid-query-set-extra (static SQL, no user input)
config_based_queryset = queryset.filter(
last_called_at__isnull=True,
active=True,
created_at__lt=stale_threshold,
).extra(
where=[
f"""
(
(
{_HAS_UNTARGETED_FULL_ROLLOUT_GROUP}
AND (posthog_featureflag.filters->>'multivariate' IS NULL
OR posthog_featureflag.filters->'multivariate' = '{{}}'::jsonb
OR jsonb_array_length({_VARIANTS_ARRAY}) = 0)
)
OR
(
EXISTS (
SELECT 1 FROM jsonb_array_elements({_VARIANTS_ARRAY}) AS variant
WHERE variant->>'rollout_percentage' = '100'
)
AND {_HAS_UNTARGETED_FULL_ROLLOUT_GROUP}
)
OR
(
EXISTS (
SELECT 1 FROM jsonb_array_elements({_GROUPS_ARRAY}) AS elem
WHERE elem->>'rollout_percentage' = '100'
AND {_ELEM_HAS_NO_TARGETING}
AND elem->'variant' IS NOT NULL
AND elem->>'variant' IS NOT NULL
)
AND (posthog_featureflag.filters->>'multivariate' IS NOT NULL AND jsonb_array_length({_VARIANTS_ARRAY}) > 0)
)
OR (posthog_featureflag.filters IS NULL OR posthog_featureflag.filters = '{{}}'::jsonb)
)
"""
]
)
return queryset.filter(usage_based_stale) | config_based_queryset
def filter_effectively_full_rollout_flags(queryset: QuerySet) -> QuerySet:
"""
Narrow a FeatureFlag queryset to the flags whose configuration can only serve one result.
Rollout completeness is not staleness. `filter_stale_flags` keeps that job and nothing
user-visible reads this.
The predicate reads configuration only. Which of these flags is a cleanup candidate is the
caller's policy, so flag age, call recency and `active` all stay with the caller.
This is a prefilter, not a verdict. The SQL matches a release condition at an explicit 100%
with no properties, which every branch of `FeatureFlagStatusChecker.is_flag_fully_rolled_out`
needs, boolean and multivariate alike. A multivariate flag also needs every reachable path to
serve the same variant, which this does not test, so the caller must confirm each row with
`is_flag_fully_rolled_out` before it treats the flag as fully rolled out.
A group that omits the `properties` key, or stores it as JSON null, counts as having no
targeting. See `_ELEM_HAS_NO_TARGETING`.
A legacy row storing `groups` as something other than an array reads as an empty array and
drops out, rather than aborting the batch. See `_GROUPS_ARRAY`.
Flags with no release conditions at all (`filters` NULL, `{}`, or `{"groups": []}`) stay out,
although the checker calls them fully rolled out. `{"groups": []}` is the model default, so
matching it would report every flag in a project that nobody has configured.
See `filter_stale_flags` for the `.extra(where=...)` composition trap, which applies here too.
`.filter()` chained onto the result ANDs cleanly and keeps the raw text at the top level.
"""
# nosemgrep: python.django.security.audit.query-set-extra.avoid-query-set-extra (static SQL, no user input)
return queryset.extra(where=[_HAS_UNTARGETED_FULL_ROLLOUT_GROUP])
# Describes the `active` param for every published schema that accepts it: the list endpoint's
# OpenAPI parameter and the bulk-delete filter serializer. It states in prose what
# `filter_stale_flags` matches, so it has to change with that SQL.
STALE_ACTIVE_PARAM_DESCRIPTION = (
"'true' and 'false' filter on serving state, the flag's `active` column. 'STALE' "
"returns enabled flags only, so a disabled flag is never STALE. An enabled flag "
"matches when its last recorded `$feature_flag_called` event is more than "
f"{STALE_FLAG_THRESHOLD_DAYS} days old. With no recorded event, it matches when it is "
f"at least {STALE_FLAG_THRESHOLD_DAYS} days old and either stores `filters` as `{{}}` "
"or serves one result to everyone through a release condition at 100% with no "
"property filters. A flag with no recorded event and an empty `groups` list does not "
"match, even when its `status` reads STALE. The reverse also happens: a multivariate flag "
"matches when a variant is at 100% under a release condition at 100% with no property "
"filters, or when that condition names a variant. Its `status` can still read ACTIVE, "
"because an earlier variant in the list or an earlier targeted condition can serve a "
"different result. In a flag of either type that mixes person and group aggregation, the "
"filter also counts a group-aggregated condition at 100% with no property filters, which "
"`status` does not. An SDK that sends no "
"`$feature_flag_called` event leaves no record, so a STALE flag can still be in use."
)
def filter_flags_by_active_param(queryset: QuerySet, value: str | bool) -> QuerySet:
"""
Filter a FeatureFlag queryset by the `active` param (STALE / true / false).
Source of truth for both the feature_flags viewset (`_apply_filters`) and Max's
listing path. Handles string values (from URL query params) and native booleans
(from JSON bodies). The STALE branch delegates to `filter_stale_flags`.
"""
if value == "STALE":
return filter_stale_flags(queryset)
# Handle both string "true"/"false" (any casing) and boolean True/False
is_active = str(value).lower() == "true"
return queryset.filter(active=is_active)
def _sole_reachable_variant(variants: list[dict]) -> str | None:
"""The only variant the distribution can serve, or None when a user can land on more than one.
Variants take cumulative slices of the hash space in declaration order, so the first variant
with a non-zero rollout takes the low hashes. Only that variant exists when it takes the whole
space. A list such as `[40, 100]` is overallocated: the 100 does not make the flag constant,
because the 40 still owns the low hashes.
"""
for variant in variants:
percentage = variant.get("rollout_percentage") or 0
if percentage <= 0:
continue
return variant.get("key") if percentage >= 100 else None
return None
# FeatureFlagStatusChecker is used to determine the status of a feature flag for a given user.
# Eventually, this may be used to automatically archive old flags that are no longer in use.
#
# Status can be one of the following:
# - ACTIVE: The feature flag is actively evaluated and in use.
# - STALE: The feature flag is likely safe to remove. Detection uses the best available signal:
# 1. If last_called_at exists: flag hasn't been called in 30+ days (usage-based)
# 2. If last_called_at is NULL: flag is 100% rolled out and 30+ days old (config-based)
# - ARCHIVED: The feature flag has been archived (done for good, kept for historical data).
# - DELETED: The feature flag has been soft deleted.
# - UNKNOWN: The feature flag is not found in the database.
#
# The set-based counterpart is `filter_stale_flags`. Both are meant to classify the same flags as
# stale, with the exceptions recorded in that function's docstring.
class FeatureFlagStatusChecker:
def __init__(
self,
feature_flag_id: int | None = None,
feature_flag: FeatureFlag | None = None,
):
self.feature_flag_id = feature_flag_id
self.feature_flag = feature_flag
# Set when `get_status` reaches STALE through the configuration route, where the reason it
# returns already states the rollout. Callers that narrate the rollout separately read this
# rather than re-deriving the route from the flag.
self.reason_states_rollout = False
def get_status(self) -> tuple[FeatureFlagStatus, FeatureFlagStatusReason]:
if not self.feature_flag_id and not self.feature_flag:
return FeatureFlagStatus.UNKNOWN, "Must provide feature flag or feature flag id"
try:
flag = (
FeatureFlag.objects_including_soft_deleted.get(pk=self.feature_flag_id)
if self.feature_flag_id
else self.feature_flag
)
except FeatureFlag.DoesNotExist:
return FeatureFlagStatus.UNKNOWN, "Flag could not be found"
if not flag:
return FeatureFlagStatus.UNKNOWN, "Flag could not be loaded"
if flag.deleted:
return FeatureFlagStatus.DELETED, "Flag has been deleted"
if flag.archived:
return FeatureFlagStatus.ARCHIVED, "Flag has been archived"
# Disabled flags are not evaluated for staleness
if not flag.active:
return FeatureFlagStatus.ACTIVE, "Flag is disabled (not evaluated for staleness)"
# Use the best available signal to determine if flag is stale:
# 1. If we have usage data (last_called_at), use that - it's the most accurate
# 2. If no usage data, fall back to configuration-based detection
if flag.last_called_at is not None:
# We have usage data - use it as the primary signal
is_stale, stale_reason = self.is_flag_stale_by_usage(flag)
if is_stale:
return FeatureFlagStatus.STALE, stale_reason
# Flag has recent usage
days_since_called = (datetime.now(UTC) - flag.last_called_at).days
if days_since_called == 0:
return FeatureFlagStatus.ACTIVE, "Flag was called today"
return (
FeatureFlagStatus.ACTIVE,
f"Flag was last called {days_since_called} day{'s' if days_since_called != 1 else ''} ago",
)
else:
# No usage data - fall back to configuration-based detection
# Only for flags that are old enough (30+ days) to have had a chance to be called
is_flag_older_than_stale_threshold = flag.created_at < stale_flag_threshold()
if is_flag_older_than_stale_threshold:
is_fully_rolled_out, rolled_out_reason = self.is_flag_fully_rolled_out(flag)
if is_fully_rolled_out:
self.reason_states_rollout = True
return FeatureFlagStatus.STALE, rolled_out_reason
return FeatureFlagStatus.ACTIVE, "Flag has no usage data yet"
def is_flag_stale_by_usage(self, flag: FeatureFlag) -> tuple[bool, FeatureFlagStatusReason]:
"""
Check if flag is stale based on usage data (last_called_at).
A flag is stale if it hasn't been called in 30+ days.
"""
assert flag.last_called_at is not None, "last_called_at must not be None"
stale_threshold = stale_flag_threshold()
if flag.last_called_at < stale_threshold:
days_since_called = (datetime.now(UTC) - flag.last_called_at).days
return True, f"Flag has not been called in {days_since_called} days"
return False, ""
def get_rollout_summary(self, flag: FeatureFlag) -> "FeatureFlagRolloutSummary":
"""
Summarize the flag's rollout configuration so callers can determine rollout
completeness (e.g. "fully rolled out / GA") without re-parsing ``filters``.
This is independent of ``get_status``: ``status`` reflects recent evaluation
(was the flag called), while this reflects configuration. A flag can be
``active`` while only partially rolled out, or fully rolled out but ``stale``.
"""
filters = flag.filters or {}
groups = filters.get("groups") or []
multivariate = filters.get("multivariate")
has_targeting_conditions = False
max_rollout_percentage: int | float | None = None
for group in groups:
if group.get("properties"):
has_targeting_conditions = True
# A missing rollout_percentage evaluates to 100% at runtime, so it counts as 100 here.
# This is deliberately looser than effectively_full_rollout / is_group_fully_rolled_out,
# which require an explicit 100.
percentage = condition_rollout_percentage(group)
max_rollout_percentage = (
percentage if max_rollout_percentage is None else max(max_rollout_percentage, percentage)
)
is_fully_rolled_out, _ = self.is_flag_fully_rolled_out(flag)
return FeatureFlagRolloutSummary(
effectively_full_rollout=is_fully_rolled_out,
has_targeting_conditions=has_targeting_conditions,
max_rollout_percentage=max_rollout_percentage,
is_multivariate=bool(multivariate and multivariate.get("variants")),
)
def rollout_state_and_variant(
self, flag: FeatureFlag, summary: FeatureFlagRolloutSummary
) -> tuple[str, str | None]:
"""Map a rollout summary to a `ROLLOUT_*` state and, when a multivariate flag is
fully rolled out to one variant, that variant's key."""
if summary.effectively_full_rollout:
variant = None
if summary.is_multivariate:
# summary already established full rollout; this only fetches the winning variant key.
# Both calls read the same in-memory flag, so they cannot disagree.
variant = self.sole_served_variant(flag)
return ROLLOUT_FULLY_ROLLED_OUT, variant
# Effectively at 0%: every release condition is at 0 (max across groups is 0).
if summary.max_rollout_percentage == 0:
return ROLLOUT_NOT_ROLLED_OUT, None
return ROLLOUT_PARTIAL, None
def is_flag_fully_rolled_out(self, flag: FeatureFlag) -> tuple[bool, FeatureFlagStatusReason]:
# The model accessors raise on a document in another config format. The checker cannot
# read such a flag, so it never calls it fully rolled out. A raw read would answer as a
# flag with no conditions and call it rolled out instead.
try:
# An empty/missing variant list is treated as boolean, matching the STALE SQL filter
# (which routes `jsonb_array_length(variants) = 0` into the boolean branch). The
# accessors cannot read `filters` of None, which the boolean branch handles itself.
has_variants = flag.filters is not None and bool(flag.variants)
if has_variants:
served_variant = self.sole_served_variant(flag)
if served_variant is not None:
return True, f'This flag will always use the variant "{served_variant}"'
elif self.is_boolean_flag_fully_rolled_out(flag):
return True, 'This boolean flag will always evaluate to "true"'
except ConfigFormatError:
return False, ""
return False, ""
def sole_served_variant(self, flag: FeatureFlag) -> str | None:
"""The one variant that every reachable path serves, or None when the paths disagree.
The matcher reads the release conditions in declaration order and stops at the first one
that matches, so a condition declared before the blanket one decides the result for the
users it matches. A condition carrying a `variant` override serves that variant, and any
other condition serves whatever the variant distribution gives. The flag is fully rolled
out to one variant only when every one of those paths lands on the same variant. The walk
ends at the first condition that decides for everyone, see `first_deciding_condition`.
A boolean flag carries no variants and returns None, so a caller must not read None as
"the flag is not constant". `is_flag_fully_rolled_out` sends boolean flags to
`is_boolean_flag_fully_rolled_out` instead.
"""
decider = self.first_deciding_condition(flag)
if decider is None:
return None
variants = flag.variants
groups = flag.conditions
distributed = _sole_reachable_variant(variants)
variant_keys = {variant.get("key") for variant in variants}
results = set()
for group in groups[: decider + 1]:
if condition_rollout_percentage(group) <= 0:
continue
# The matcher ignores an override naming a variant the flag does not configure, and the
# distribution decides instead.
override = pinned_variant(group, variant_keys)
results.add(distributed if override is None else override)
# `None` is in the set when a path falls through to a distribution that is not itself constant.
if len(results) != 1:
return None
(served,) = results
return served
def is_group_fully_rolled_out(self, group: dict) -> bool:
rollout_percentage = group.get("rollout_percentage")
# A `properties` key stored as JSON null means no targeting, the same as an absent key.
# The matcher's field is `Option<Vec<PropertyFilter>>` and the filters serializer
# normalizes null to `[]`, so only legacy rows still hold the null.
properties = group.get("properties") or []
return rollout_percentage == 100 and len(properties) == 0
def first_deciding_condition(self, flag: FeatureFlag) -> int | None:
"""Index of the first untargeted 100% condition that settles the result for every request.
The matcher skips a group-aggregated condition when the request carries no key for that
group. A flag whose conditions all aggregate on one target addresses only the requests
that carry it, so its condition decides for that whole audience. A flag that mixes person
and group aggregation addresses requests without the key too, and only a person-level
condition reaches those.
"""
groups = flag.conditions
flag_level_index = flag.aggregation_group_type_index
mixed = len({condition_aggregation(group, flag_level_index) for group in groups}) > 1
return next(
(
index
for index, group in enumerate(groups)
if self.is_group_fully_rolled_out(group)
and (not mixed or condition_aggregation(group, flag_level_index) is None)
),
None,
)
def is_boolean_flag_fully_rolled_out(self, flag: FeatureFlag) -> bool:
# Treat missing filters, `{}`, and `{"groups": []}` as "no release conditions"
# and therefore fully rolled out. Not a supported state, but legacy data hits
# all three shapes (especially `{"groups": []}` post-backfill). The accessors cannot
# read the first, so it is tested before them.
if flag.filters is None or not flag.conditions:
logger.debug(f"Boolean flag {flag.id} has no release conditions, so it is rolled out to 100%")
return True
if self.first_deciding_condition(flag) is not None:
logger.debug(f"Boolean flag {flag.id} has a release conditions rolled out to 100%")
return True
return False