from __future__ import annotations import json import typing from dataclasses import replace import structlog from common.core.utils import is_saas from django.conf import settings from django.db import IntegrityError, transaction from django.db.models import Q from django.utils import timezone from flag_engine.segments.constants import ALL_RULE, ANY_RULE, PERCENTAGE_SPLIT from rest_framework.exceptions import ValidationError from rest_framework.settings import api_settings from app_analytics.mappers import map_user_agent_to_sdk_language_and_version from audit.constants import EXPERIMENT_ROLLOUT_APPLIED_MESSAGE from audit.models import AuditLog from audit.related_object_type import RelatedObjectType from cohorts.models import Cohort from core.dataclasses import AuthorData from environments.tasks import rebuild_environment_document from experimentation.constants import ( CONTROL_VARIANT_KEY, EXPOSURE_HOURLY_BUCKET_MAX_WINDOW, MAX_AUDIENCE_SEGMENTS, RESULTS_MIN_CONVERSIONS_PER_VARIANT, RESULTS_MIN_IDENTITIES_PER_VARIANT, SRM_MIN_TOTAL_IDENTITIES, WAREHOUSES_FLAG, ) from experimentation.dataclasses import ( AudienceSpec, ConversionsTimeseries, ConversionsTimeseriesPoint, ExposureBucket, ExposuresSummary, ExposuresTimeseries, ExposuresTimeseriesPoint, MetricResult, MetricSpec, ResultsAggregates, ResultsSummary, RolloutSpec, WarehouseEventNames, WarehouseEventStats, ) from experimentation.mappers import map_sdk_event_to_sdk_experimentation_event from experimentation.metrics import ( flagsmith_experimentation_sdk_events_total, flagsmith_experimentation_warehouse_connection_verifications_total, ) from experimentation.models import ( VALID_STATUS_TRANSITIONS, AudienceMatch, Experiment, ExperimentStatus, MetricAggregation, MetricDirection, SDKExperimentationEvent, WarehouseConnection, WarehouseConnectionStatus, WarehouseDeliveryStatus, WarehouseType, ) from experimentation.sdk_events import SDKExperimentationEventSerializer from experimentation.stats import ( Inference, VariantStats, compare_to_control, srm_p_value, ) from experimentation.warehouses import flagsmith from experimentation.warehouses.exceptions import UnsupportedWarehouseOperation from experimentation.warehouses.postgres import is_flagsmith_database_config from experimentation.warehouses.registry import get_warehouse from features.feature_segments.services import get_next_segment_override_priority from features.feature_states.models import API_VALUE_TYPES from features.future.services import delete_segment_override, update_flag from features.future.types import SegmentOverrideRequest from features.models import Feature, FeatureState from features.value_types import BOOLEAN, STRING from features.versioning.versioning_service import get_environment_flags_list from integrations.flagsmith.client import get_openfeature_client from organisations.subscriptions.constants import PLAN_RANK, SubscriptionPlanFamily from segments.models import Condition, Segment, SegmentManagedBy, SegmentRule from segments.services import write_segment_rules # TODO: Delete alias as per https://github.com/Flagsmith/flagsmith/issues/7818 from segments.types import SegmentRule as SegmentRuleType if typing.TYPE_CHECKING: from collections.abc import Sequence from datetime import datetime from flag_engine.segments.types import ConditionOperator, RuleType from environments.models import Environment from experimentation.models import Metric from experimentation.types import ( ExposureGranularity, RejectedSDKEvent, SDKEventBatchResult, ) from features.feature_states.models import FeatureValueType from features.models import FeatureStateValue from organisations.models import Organisation from users.models import FFAdminUser logger = structlog.get_logger("warehouse") experimentation_logger = structlog.get_logger("experimentation") class _ExposureReadKwargs(typing.TypedDict): environment_key: str feature_name: str window_start: datetime window_end: datetime granularity: ExposureGranularity def get_warehouses_flag_config(organisation: Organisation) -> dict[str, object]: raw = get_openfeature_client().get_string_value( WAREHOUSES_FLAG, default_value="{}", evaluation_context=organisation.openfeature_evaluation_context, ) try: parsed = json.loads(raw) except (json.JSONDecodeError, TypeError): return {} return parsed if isinstance(parsed, dict) else {} def is_warehouse_type_available( organisation: Organisation, warehouse_type: str ) -> bool: if not is_saas(): return True minimum_plans = get_warehouses_flag_config(organisation).get("minimum_plans") if not isinstance(minimum_plans, dict): return True # Unknown or empty plan IDs resolve to FREE, i.e. available on every plan. minimum = SubscriptionPlanFamily.get_by_plan_id( str(minimum_plans.get(warehouse_type) or "") ) current = organisation.subscription.subscription_plan_family return PLAN_RANK[current] >= PLAN_RANK[minimum] def ensure_flagsmith_warehouse_connection( environment: Environment, ) -> WarehouseConnection | None: if not (settings.EXPERIMENTATION_ENABLED and is_saas()): return None organisation = environment.project.organisation if not get_warehouses_flag_config(organisation).get("auto_connect_flagsmith"): return None if not is_warehouse_type_available(organisation, WarehouseType.FLAGSMITH): return None if WarehouseConnection.objects.filter( environment=environment, deleted_at__isnull=True, ).exists(): return None try: connection: WarehouseConnection = WarehouseConnection.objects.create( environment=environment, warehouse_type=WarehouseType.FLAGSMITH, name="Flagsmith", ) return connection except IntegrityError: return None def store_sdk_experimentation_events( environment: Environment, submitted_events: list[object], *, sdk_user_agent: str | None, ) -> SDKEventBatchResult: collected_at = timezone.now() sdk_language, sdk_version = map_user_agent_to_sdk_language_and_version( sdk_user_agent ) valid_events: list[SDKExperimentationEvent] = [] rejected_events: list[RejectedSDKEvent] = [] rejected_fields: set[str] = set() for index, event in enumerate(submitted_events): serializer = SDKExperimentationEventSerializer(data=event) if serializer.is_valid(): valid_events.append( map_sdk_event_to_sdk_experimentation_event( serializer.validated_data, environment_key=environment.api_key, collected_at=collected_at, sdk_language=sdk_language, sdk_version=sdk_version, ) ) continue field, (message, *_) = next(iter(serializer.errors.items())) rejected_fields.add(field) error = ( message if field == api_settings.NON_FIELD_ERRORS_KEY else f"{field}: {message}" ) rejected_events.append({"index": index, "error": error}) SDKExperimentationEvent.objects.bulk_create(valid_events) flagsmith_experimentation_sdk_events_total.labels(result="accepted").inc( len(valid_events) ) flagsmith_experimentation_sdk_events_total.labels(result="rejected").inc( len(rejected_events) ) if rejected_events: experimentation_logger.warning( "sdk_events.rejected", environment__id=environment.id, submitted_events__count=len(submitted_events), rejected_events__count=len(rejected_events), rejected_events__fields=sorted(rejected_fields), ) return {"accepted": len(valid_events), "rejected": rejected_events} def get_warehouse_event_names( connection: "WarehouseConnection", environment_key: str, ) -> WarehouseEventNames | None: return get_warehouse(connection.warehouse_type).get_event_names( connection, environment_key ) def compute_exposures_summary( experiment: Experiment, *, window_start: datetime, window_end: datetime, ) -> ExposuresSummary: """Read an experiment's exposures from its environment's warehouse, or the managed one when the environment has no connection.""" granularity = _select_exposure_granularity(window_start, window_end) read_kwargs: _ExposureReadKwargs = { "environment_key": experiment.environment.api_key, "feature_name": experiment.feature.name, "window_start": window_start, "window_end": window_end, "granularity": granularity, } connection = experiment.environment.warehouse_connections.first() if connection is None: buckets = flagsmith.get_exposure_buckets(**read_kwargs) else: buckets = get_warehouse(connection.warehouse_type).get_exposure_buckets( connection, **read_kwargs ) return build_exposures_summary(buckets, granularity=granularity) def build_exposures_summary( buckets: Sequence[ExposureBucket], *, granularity: ExposureGranularity, ) -> ExposuresSummary: return ExposuresSummary( excluded_identities=sum( b.first_exposed_identities for b in buckets if b.quarantined ), timeseries=_exposures_timeseries(buckets, granularity=granularity), ) def _exposures_timeseries( buckets: Sequence[ExposureBucket], *, granularity: ExposureGranularity, ) -> ExposuresTimeseries: return ExposuresTimeseries( granularity=granularity, points=[ ExposuresTimeseriesPoint(bucket=bucket, new_identities=counts) for bucket, counts in _counts_by_bucket( (b.bucket, b.variant, b.first_exposed_identities) for b in buckets if not b.quarantined ) ], ) def _conversions_timeseries( metric_id: int, aggregates: ResultsAggregates, ) -> ConversionsTimeseries | None: buckets = aggregates.conversion_buckets.get(metric_id) if buckets is None: return None return ConversionsTimeseries( granularity=aggregates.granularity, points=[ ConversionsTimeseriesPoint(bucket=bucket, converted_identities=counts) for bucket, counts in _counts_by_bucket( (b.bucket, b.variant, b.converted_identities) for b in buckets ) ], ) def _counts_by_bucket( rows: typing.Iterable[tuple[datetime, str, int]], ) -> list[tuple[str, dict[str, int]]]: """Group rows into one per-variant dict per bucket, in bucket order. The bucket becomes an ISO string because the summary lands in a JSONField as is, and datetimes wouldn't serialise.""" counts_by_bucket: dict[datetime, dict[str, int]] = {} for bucket, variant, count in rows: counts_by_bucket.setdefault(bucket, {})[variant] = count return [ (bucket.isoformat(), counts_by_bucket[bucket]) for bucket in sorted(counts_by_bucket) ] def _select_exposure_granularity( window_start: datetime, window_end: datetime, ) -> ExposureGranularity: if window_end - window_start <= EXPOSURE_HOURLY_BUCKET_MAX_WINDOW: return "hour" return "day" def build_results_summary( aggregates: ResultsAggregates, *, expected_shares: dict[str, float], ) -> ResultsSummary: exposure_counts = aggregates.exposure_counts total = sum(exposure_counts.values()) if expected_shares and total >= SRM_MIN_TOTAL_IDENTITIES: srm = srm_p_value( [exposure_counts.get(variant, 0) for variant in expected_shares], list(expected_shares.values()), ) else: srm = None return ResultsSummary( srm_p_value=srm, metrics=[ MetricResult( metric_id=spec.metric_id, variants=aggregates.metric_stats.get(spec.metric_id, {}), inference=_metric_inference( spec, aggregates.metric_stats.get(spec.metric_id, {}) ), conversions_timeseries=_conversions_timeseries( spec.metric_id, aggregates ), ) for spec in aggregates.specs ], exposures_timeseries=_exposures_timeseries( aggregates.exposure_buckets, granularity=aggregates.granularity ), ) def compute_results_summary( experiment: "Experiment", *, window_start: "datetime", window_end: "datetime", ) -> ResultsSummary: """Gather an experiment's metric statistics and chart rows from its environment's warehouse, or the managed one when the environment has no connection, and reduce them to the stored results payload.""" read_kwargs: _ExposureReadKwargs = { "environment_key": experiment.environment.api_key, "feature_name": experiment.feature.name, "window_start": window_start, "window_end": window_end, "granularity": _select_exposure_granularity(window_start, window_end), } specs = _experiment_metric_specs(experiment) connection = experiment.environment.warehouse_connections.first() if connection is None: aggregates = flagsmith.get_results_aggregates(specs=specs, **read_kwargs) else: aggregates = get_warehouse(connection.warehouse_type).get_results_aggregates( connection, specs=specs, **read_kwargs ) return build_results_summary( aggregates, expected_shares=_expected_variant_shares(experiment), ) def _experiment_metric_specs(experiment: "Experiment") -> list[MetricSpec]: return [ MetricSpec( metric_id=experiment_metric.metric_id, event=experiment_metric.metric.definition["event"], aggregation=experiment_metric.metric.aggregation, lower_is_better=( experiment_metric.metric.direction == MetricDirection.DOWN ), ) for experiment_metric in experiment.experiment_metrics.select_related("metric") ] def _expected_variant_shares(experiment: "Experiment") -> dict[str, float]: """The traffic split SRM tests against: each multivariate option's environment allocation, with ``control`` taking the unallocated remainder. Empty when the feature has no usable allocations, skipping the SRM check.""" # TODO: read the split from the percentage-split segment override feature # state once that's implemented, rather than the environment default. feature_state = ( FeatureState.objects.get_live_feature_states( environment=experiment.environment, additional_filters=Q(feature_segment__isnull=True, identity__isnull=True), feature_id=experiment.feature_id, ) .prefetch_related( "multivariate_feature_state_values__multivariate_feature_option" ) .first() ) if feature_state is None: return {} shares: dict[str, float] = {} allocated = 0.0 for mv_value in feature_state.multivariate_feature_state_values.all(): key = mv_value.multivariate_feature_option.key if key is None: # An unkeyed option's traffic can't be attributed to a variant; # counting it as control would inflate control's expected share and # raise a false SRM alarm, so skip the check entirely. logger.error( "srm.unkeyed_variant", experiment__id=experiment.id, environment__id=experiment.environment_id, feature__id=experiment.feature_id, ) return {} shares[key] = mv_value.percentage_allocation / 100 allocated += mv_value.percentage_allocation if not shares: return {} if allocated > 100: # A misconfigured feature whose options over-allocate; control's share # would be negative, so there's no valid split to test against. logger.error( "srm.overallocated", experiment__id=experiment.id, environment__id=experiment.environment_id, feature__id=experiment.feature_id, ) return {} shares[CONTROL_VARIANT_KEY] = (100 - allocated) / 100 return shares def _metric_inference( spec: MetricSpec, variants: dict[str, VariantStats], ) -> dict[str, Inference | None]: control = variants.get(CONTROL_VARIANT_KEY) return { variant_key: _infer_treatment(spec, control, treatment) for variant_key, treatment in variants.items() if variant_key != CONTROL_VARIANT_KEY } def _infer_treatment( spec: MetricSpec, control: VariantStats | None, treatment: VariantStats, ) -> Inference | None: # Product floor for showing a result at all; compare_to_control applies its # own independent guards (e.g. zero control mean) on top of this. if ( control is None or control.n < RESULTS_MIN_IDENTITIES_PER_VARIANT or treatment.n < RESULTS_MIN_IDENTITIES_PER_VARIANT ): return None if spec.aggregation == MetricAggregation.OCCURRENCE and ( control.sum < RESULTS_MIN_CONVERSIONS_PER_VARIANT or treatment.sum < RESULTS_MIN_CONVERSIONS_PER_VARIANT ): return None inference = compare_to_control(control, treatment) if inference is not None and spec.lower_is_better: # "Winning" means moving the metric the good way; for a lower-is-better # metric that's a fall, so the chance of winning is the chance lift < 0. inference = replace(inference, chance_to_win=1.0 - inference.chance_to_win) return inference def _resolve_audit_log_author( user: FFAdminUser, ) -> dict[str, int | None]: if getattr(user, "is_master_api_key_user", False): return {"author_id": None, "master_api_key_id": user.key.id} return {"author_id": user.pk, "master_api_key_id": None} def create_warehouse_audit_log( connection: WarehouseConnection, user: FFAdminUser, *, action: str, ) -> None: AuditLog.objects.create( environment=connection.environment, project=connection.environment.project, **_resolve_audit_log_author(user), related_object_id=connection.id, related_object_type=RelatedObjectType.WAREHOUSE_CONNECTION.name, log=( f"Warehouse connection {action} for environment " f"{connection.environment.name}" ), ) def create_metric_audit_log( metric: Metric, user: FFAdminUser, *, action: str, ) -> None: AuditLog.objects.create( environment=metric.environment, project=metric.environment.project, **_resolve_audit_log_author(user), related_object_id=metric.id, related_object_type=RelatedObjectType.METRIC.name, log=f"Metric '{metric.name}' {action}", ) def create_experiment_audit_log( experiment: Experiment, user: FFAdminUser, *, action: str, ) -> None: AuditLog.objects.create( environment=experiment.environment, project=experiment.environment.project, **_resolve_audit_log_author(user), related_object_id=experiment.id, related_object_type=RelatedObjectType.EXPERIMENT.name, log=( f"Experiment '{experiment.name}' {action} for environment " f"{experiment.environment.name}" ), ) def _resolve_audit_log_author_data(author: AuthorData) -> dict[str, int | str | None]: if author.api_key is not None: return {"author_id": None, "master_api_key_id": author.api_key.id} return { "author_id": author.user.pk if author.user else None, "master_api_key_id": None, } def create_rollout_audit_log( experiment: Experiment, author: AuthorData, *, rollout_percentage: float, audience_match: str, audience_segment_ids: list[int], ) -> None: audience = ( f"segments {audience_segment_ids} ({audience_match})" if audience_segment_ids else "all identities" ) AuditLog.objects.create( environment=experiment.environment, project=experiment.environment.project, **_resolve_audit_log_author_data(author), related_object_id=experiment.id, related_object_type=RelatedObjectType.EXPERIMENT.name, log=EXPERIMENT_ROLLOUT_APPLIED_MESSAGE % (experiment.name, rollout_percentage, audience), ) def transition_experiment_status( experiment: Experiment, target_status: str, user: FFAdminUser, ) -> Experiment: with transaction.atomic(): experiment.refresh_from_db(from_queryset=Experiment.objects.select_for_update()) valid_targets = VALID_STATUS_TRANSITIONS.get(experiment.status, set()) if target_status not in valid_targets: raise ValueError( f"Cannot transition from '{experiment.status}' to '{target_status}'." ) experiment.status = target_status if target_status == ExperimentStatus.RUNNING and not experiment.started_at: Feature.objects.select_for_update().filter( pk=experiment.feature_id ).exists() experiment.started_at = timezone.now() _remove_superseded_experiment_rollouts( experiment, AuthorData.from_user(user) ) elif target_status == ExperimentStatus.COMPLETED: experiment.ended_at = timezone.now() experiment.save() create_experiment_audit_log(experiment, user, action=target_status) return experiment def _remove_superseded_experiment_rollouts( experiment: Experiment, author: AuthorData ) -> None: """Stop completed or deleted experiments' rollouts shadowing this one's.""" superseded_experiment_ids = dict( Experiment.objects.all_with_deleted() .filter( Q(status=ExperimentStatus.COMPLETED) | Q(deleted_at__isnull=False), feature_id=experiment.feature_id, environment_id=experiment.environment_id, rollout_segment__is_system_segment=True, ) .exclude(id=experiment.id) .values_list("rollout_segment_id", "id") ) if not superseded_experiment_ids: return live_segment_ids = { feature_segment.segment_id for override in get_environment_flags_list( environment=experiment.environment, additional_filters=Q( feature_id=experiment.feature_id, feature_segment__segment_id__in=superseded_experiment_ids, identity__isnull=True, ), ) if (feature_segment := override.feature_segment) } for segment_id in sorted(live_segment_ids): delete_segment_override( environment=experiment.environment, feature=experiment.feature, segment_id=segment_id, author=author, overwrite_system_segment_overrides=True, ) def _log_superseded() -> None: for segment_id in sorted(live_segment_ids): experimentation_logger.info( "rollout.superseded", experiment__id=experiment.id, superseded_experiment__id=superseded_experiment_ids[segment_id], environment__id=experiment.environment_id, feature__id=experiment.feature_id, ) transaction.on_commit(_log_superseded) def _copy_segment_rule(rule: SegmentRule) -> SegmentRuleType: return { "type": typing.cast("RuleType", rule.type), "conditions": [ { "property": condition.property, "operator": typing.cast("ConditionOperator", condition.operator), "value": condition.value, "description": condition.description, } for condition in rule.conditions.all() ], "rules": [_copy_segment_rule(sub_rule) for sub_rule in rule.rules.all()], } def _copy_segment_rules(segment: Segment) -> list[SegmentRuleType]: # Read from the ORM rows: the only representation cohort segments have. return [_copy_segment_rule(rule) for rule in segment.rules.all()] def _compile_audience_rules( match: str, copied_rules: list[list[SegmentRuleType]], ) -> list[SegmentRuleType]: if not copied_rules: return [] return [ { "type": ALL_RULE if match == AudienceMatch.ALL else ANY_RULE, "conditions": [], # A segment's own top-level rules are AND-quantified, so a # multi-rule segment needs its own ALL wrapper. A single rule is # inlined, keeping the tree within the document builder's # prefetch depth and the org exporter's two-level selection. "rules": [ ( rules[0] if len(rules) == 1 else {"type": ALL_RULE, "conditions": [], "rules": rules} ) for rules in copied_rules ], } ] def _compile_audience( experiment: Experiment, audience: AudienceSpec, ) -> tuple[list[SegmentRuleType], list[int]]: segments = _get_audience_segments(experiment, audience.segment_ids) # Locked against ``delete_cohort``, which locks the same rows before # deciding no experiment targets them. cohorts_by_segment_id = { cohort.segment_id: cohort for cohort in Cohort.objects.select_for_update() .filter(segment__in=segments) # A stable lock order, so two rollouts targeting overlapping cohorts # cannot deadlock each other. .order_by("pk") } copied_rules: list[list[SegmentRuleType]] = [] for segment in segments: rules = _copy_segment_rules(segment) _validate_audience_segment( experiment, segment, rules, cohorts_by_segment_id.get(segment.id) ) copied_rules.append(rules) return _compile_audience_rules(audience.match, copied_rules), [ segment.id for segment in segments ] def _rollout_segment_rules( rollout_percentage: float, audience_rules: list[SegmentRuleType], ) -> list[SegmentRuleType]: return [ { "type": ALL_RULE, "conditions": [ { "property": "$.identity.key", "operator": PERCENTAGE_SPLIT, "value": str(rollout_percentage), "description": None, } ], "rules": [], }, *audience_rules, ] def _audience_segment_ids(experiment: Experiment) -> list[int]: # Through the join table, so soft-deleted segments still count. return sorted( Experiment.audience_segments.through.objects.filter( experiment=experiment ).values_list("segment_id", flat=True) ) def _frozen_audience_rules(experiment: Experiment) -> list[SegmentRuleType]: # The percentage split is always the rollout segment's first rule. segment = experiment.rollout_segment if segment is None or not (rules := segment.rules_data): return [] return rules[1:] def _audience_match_of(audience_rules: list[SegmentRuleType]) -> str: if audience_rules and audience_rules[0]["type"] == ALL_RULE: return AudienceMatch.ALL.value return AudienceMatch.ANY.value def _audience_changed(experiment: Experiment, audience: AudienceSpec) -> bool: stored_ids = _audience_segment_ids(experiment) requested_ids = sorted(audience.segment_ids) if not stored_ids and not requested_ids: return False return requested_ids != stored_ids or audience.match != _audience_match_of( _frozen_audience_rules(experiment) ) def _get_audience_segments( experiment: Experiment, segment_ids: list[int], ) -> list[Segment]: segments = list( Segment.live_objects.filter( project_id=experiment.feature.project_id, id__in=segment_ids ).order_by("id") ) if missing := set(segment_ids) - {segment.id for segment in segments}: raise ValidationError( f"Audience segments {sorted(missing)} do not belong to the project" ) return segments def _rules_contain_percentage_split(rules: list[SegmentRuleType]) -> bool: return any( any( condition["operator"] == PERCENTAGE_SPLIT for condition in rule["conditions"] ) or _rules_contain_percentage_split(rule.get("rules", [])) for rule in rules ) def _validate_audience_segment( experiment: Experiment, segment: Segment, rules: list[SegmentRuleType], cohort: Cohort | None, ) -> None: if segment.is_system_segment: raise ValidationError(f"Audience segment {segment.id} cannot be targeted") if segment.feature_id is not None: raise ValidationError(f"Audience segment {segment.id} is specific to a feature") if cohort is not None: if cohort.environment_id != experiment.environment_id: raise ValidationError( f"Audience segment {segment.id} belongs to a cohort in another " f"environment" ) if cohort.deletion_requested_at is not None: # Its memberships are draining, so the audience would decay to zero. raise ValidationError( f"Audience segment {segment.id} belongs to a cohort that is being " f"deleted" ) if not rules: # An empty tree compiles to a rule that matches everyone, which would # silently widen the audience instead of narrowing it. raise ValidationError(f"Audience segment {segment.id} has no rules") if _rules_contain_percentage_split(rules): raise ValidationError( f"Audience segment {segment.id} contains a percentage split" ) def _rollout_override_enabled(experiment: Experiment) -> bool: return experiment.rollout_segment_id is not None and bool( (override := _get_live_rollout_override(experiment)) and override.enabled ) def _validate_audience_change(experiment: Experiment, audience: AudienceSpec) -> None: """Checks that only apply when the audience is actually being replaced.""" if experiment.status != ExperimentStatus.CREATED: raise ValidationError( f"Cannot change the audience of a {experiment.status} experiment." ) if _rollout_override_enabled(experiment): # An enabled override is already enrolling identities, whatever the # experiment's status says, and they were enrolled by these rules. raise ValidationError( "Cannot change the audience while the rollout is enabled and " "serving traffic. Disable the rollout first." ) if len(audience.segment_ids) != len(set(audience.segment_ids)): raise ValidationError("Audience segments must be unique") if len(audience.segment_ids) > MAX_AUDIENCE_SEGMENTS: raise ValidationError( f"An audience must target no more than {MAX_AUDIENCE_SEGMENTS} segments" ) def _resolve_audience( experiment: Experiment, audience: AudienceSpec | None, ) -> tuple[list[SegmentRuleType], list[int]]: if audience is not None and _audience_changed(experiment, audience): _validate_audience_change(experiment, audience) return _compile_audience(experiment, audience) return _frozen_audience_rules(experiment), _audience_segment_ids(experiment) def _is_noop_rollout( experiment: Experiment, spec: RolloutSpec, rules: list[SegmentRuleType], ) -> bool: """True when the request asks for exactly what is already live. Such a request still succeeds, but writes no audit history and announces nothing: a re-submitted form is not a rollout change.""" segment = experiment.rollout_segment if segment is None or segment.rules_data != rules: return False override = _get_live_rollout_override(experiment) if override is None or override.enabled != spec.enabled: return False if _serialize_feature_state_value(override.feature_state_value) != ( spec.feature_state_value, spec.value_type, ): return False return { mv.multivariate_feature_option_id: mv.percentage_allocation for mv in override.multivariate_feature_state_values.all() } == {variant["id"]: variant["weight"] for variant in spec.variants} def _create_rollout_segment( experiment: Experiment, rules: list[SegmentRuleType], ) -> Segment: segment: Segment = Segment.objects.create( name=f"experiment-{experiment.id}-rollout", project=experiment.feature.project, is_system_segment=True, managed_by=SegmentManagedBy.EXPERIMENT, rules_data=rules, ) write_segment_rules(segment, rules) return segment def _sync_rollout_segment( experiment: Experiment, rules: list[SegmentRuleType], ) -> Segment: segment = experiment.rollout_segment if segment is not None: if segment.rules_data == rules: # Nothing to rewrite: a value- or enabled-only change must not # churn the rule rows. return segment segment.rules_data = rules segment.save(update_fields=["rules_data"]) write_segment_rules(segment, rules) return segment segment = _create_rollout_segment(experiment, rules) experiment.rollout_segment = segment experiment.save() return segment def _get_live_rollout_override(experiment: Experiment) -> FeatureState | None: flags = get_environment_flags_list( environment=experiment.environment, additional_filters=Q( feature_id=experiment.feature_id, feature_segment__segment_id=experiment.rollout_segment_id, identity__isnull=True, ), ) return flags[0] if flags else None def _write_rollout_override( experiment: Experiment, override: SegmentOverrideRequest, author: AuthorData ) -> None: """Write the rollout segment's override, after the others if it's new.""" if not _get_live_rollout_override(experiment): override = { **override, "priority": get_next_segment_override_priority( environment=experiment.environment, feature=experiment.feature ), } update_flag( environment=experiment.environment, feature=experiment.feature, changes={"segment_overrides": [override]}, replace=False, author=author, overwrite_system_segment_overrides=True, ) def _reset_default_allocations_to_control( experiment: Experiment, author: AuthorData ) -> None: """Zero every variant's allocation on the feature's environment-default feature state, leaving control (the unallocated remainder) at 100%. Run once, when the rollout segment is first created: identities outside the rollout cohort should all receive control while the experiment runs. """ update_flag( environment=experiment.environment, feature=experiment.feature, changes={ "environment_default": { "variants": [ {"id": option_id, "weight": 0} for option_id in experiment.feature.multivariate_options.values_list( "id", flat=True ) ] } }, replace=False, author=author, overwrite_system_segment_overrides=True, ) def apply_experiment_rollout(experiment: Experiment, spec: RolloutSpec) -> None: environment_id = experiment.environment_id with transaction.atomic(): experiment.refresh_from_db(from_queryset=Experiment.objects.select_for_update()) if experiment.status == ExperimentStatus.COMPLETED: raise ValidationError( f"Cannot change the rollout of a {experiment.status} experiment." ) audience_rules, audience_segment_ids = _resolve_audience( experiment, spec.audience ) rollout_rules = _rollout_segment_rules(spec.rollout_percentage, audience_rules) stored_segment_ids = _audience_segment_ids(experiment) if ( _is_noop_rollout(experiment, spec, rollout_rules) # A retarget to segments compiling to identical rules is still a # change worth recording. and audience_segment_ids == stored_segment_ids ): return if audience_segment_ids != stored_segment_ids: experiment.audience_segments.set(audience_segment_ids) is_first_rollout = experiment.rollout_segment_id is None segment = _sync_rollout_segment(experiment, rollout_rules) if is_first_rollout: _reset_default_allocations_to_control(experiment, spec.author) _write_rollout_override( experiment, { "segment": {"id": segment.id}, "enabled": spec.enabled, "value": {"type": spec.value_type, "value": spec.feature_state_value}, "variants": spec.variants, }, spec.author, ) # Segment condition changes don't trigger a rebuild on their own. transaction.on_commit( lambda: rebuild_environment_document.delay( kwargs={"environment_id": environment_id} ) ) audience_match = _audience_match_of(audience_rules) create_rollout_audit_log( experiment, spec.author, rollout_percentage=spec.rollout_percentage, audience_match=audience_match, audience_segment_ids=audience_segment_ids, ) # Announced only once durable: experiment creation nests this call in an # outer transaction that can still roll back. transaction.on_commit( lambda: experimentation_logger.info( "rollout.applied", experiment__id=experiment.id, environment__id=environment_id, feature__id=experiment.feature_id, author__id=spec.author.user.pk if spec.author.user else None, author__api_key_id=( spec.author.api_key.pk if spec.author.api_key else None ), rollout__percentage=spec.rollout_percentage, audience__match=audience_match, audience__segments_count=len(audience_segment_ids), audience__segment_ids=audience_segment_ids, ) ) def _serialize_feature_state_value( value: FeatureStateValue, ) -> tuple[str, FeatureValueType]: """Render a stored feature state value as the (string, API type) pair that the flag API expects.""" if value.value is None: return "", "string" return ( str(value.value).lower() if value.type == BOOLEAN else str(value.value), API_VALUE_TYPES.get(value.type or STRING, "string"), ) def get_experiment_rollout(experiment: Experiment) -> dict[str, typing.Any] | None: segment_id = experiment.rollout_segment_id if segment_id is None: return None feature_state = FeatureState.objects.get_live_feature_states( environment=experiment.environment, additional_filters=Q( feature_segment__segment_id=segment_id, identity__isnull=True ), feature_id=experiment.feature_id, ).first() if feature_state is None: return None condition = Condition.objects.get( rule__segment_id=segment_id, operator=PERCENTAGE_SPLIT ) str_value, value_type = _serialize_feature_state_value( feature_state.feature_state_value ) return { "enabled": feature_state.enabled, "rollout_percentage": float(condition.value or 0), "feature_state_value": {"type": value_type, "value": str_value}, "multivariate_feature_state_values": [ { "multivariate_feature_option": mv.multivariate_feature_option_id, "percentage_allocation": mv.percentage_allocation, } for mv in feature_state.multivariate_feature_state_values.all() ], "audience": _get_experiment_audience(experiment), } def _get_experiment_audience(experiment: Experiment) -> dict[str, typing.Any]: segments = ( Segment.objects.all_with_deleted() .filter(id__in=_audience_segment_ids(experiment)) .prefetch_related("cohorts") .order_by("id") ) return { "match": _audience_match_of(_frozen_audience_rules(experiment)), "segments": [ { "id": segment.id, "name": segment.name, "is_cohort": (cohort := next(iter(segment.cohorts.all()), None)) is not None, "cohort_source_type": cohort.source_type if cohort else None, "deleted": segment.deleted_at is not None, } for segment in segments ], } def enable_experiment_rollout(experiment: Experiment, author: AuthorData) -> None: rollout = get_experiment_rollout(experiment) if ( rollout is None or rollout["enabled"] or (rollout_segment_id := experiment.rollout_segment_id) is None ): return _write_rollout_override( experiment, { "segment": {"id": rollout_segment_id}, "enabled": True, "value": rollout["feature_state_value"], }, author, ) def mark_warehouse_pending_connection( connection: WarehouseConnection, ) -> WarehouseConnection: """Move a connection from created to pending_connection. No-op for any other status.""" if connection.status != WarehouseConnectionStatus.CREATED: return connection connection.status = WarehouseConnectionStatus.PENDING_CONNECTION connection.save(update_fields=["status"]) logger.info( "connection.test_event_sent", environment__id=connection.environment_id, organisation__id=connection.environment.project.organisation_id, ) return connection def verify_warehouse_connection( connection: WarehouseConnection, persist: bool = True, ) -> None: """Verify the connection through its warehouse provider and set the status to connected or errored. Raises ``UnsupportedWarehouseOperation``, before touching the connection, for types that cannot be verified. With persist=False, the status is only set on the in-memory instance, allowing unsaved connections to be tested.""" warehouse = get_warehouse(connection.warehouse_type) log = logger.bind(environment__id=connection.environment_id) try: log = log.bind(organisation__id=connection.environment.project.organisation_id) warehouse.verify(connection) except UnsupportedWarehouseOperation: raise except Exception as error: connection.status = WarehouseConnectionStatus.ERRORED connection.status_detail = warehouse.describe_error(error) if persist: connection.save(update_fields=["status", "status_detail"]) flagsmith_experimentation_warehouse_connection_verifications_total.labels( result="failure" ).inc() log.warning("connection.verification_failed", exc_info=True) return connection.status = WarehouseConnectionStatus.CONNECTED connection.status_detail = None if persist: connection.save(update_fields=["status", "status_detail"]) flagsmith_experimentation_warehouse_connection_verifications_total.labels( result="success" ).inc() log.info("connection.verification_succeeded") def refresh_warehouse_connection_status( connection: WarehouseConnection, stats: WarehouseEventStats, ) -> WarehouseConnection: """Set a pending connection to connected when the warehouse has received at least one event. No-op otherwise.""" if ( connection.status == WarehouseConnectionStatus.PENDING_CONNECTION and stats.total_events_received > 0 ): connection.status = WarehouseConnectionStatus.CONNECTED connection.save(update_fields=["status"]) logger.info( "connection.connected", environment__id=connection.environment_id, organisation__id=connection.environment.project.organisation_id, ) return connection def annotate_warehouse_delivery_statuses( connections: Sequence[WarehouseConnection], ) -> None: """For external connections that passed verification, show what the warehouse-delivery service last saw. Read-only: nothing is saved.""" for connection in connections: if ( connection.warehouse_type == WarehouseType.FLAGSMITH # Django stores these events, so a delivery status means a misdirected SDK. or is_flagsmith_database_config(connection.config) or connection.status != WarehouseConnectionStatus.CONNECTED ): continue try: delivery_status = connection.delivery_status except WarehouseDeliveryStatus.DoesNotExist: continue if delivery_status.status == WarehouseConnectionStatus.ERRORED: connection.status = WarehouseConnectionStatus.ERRORED connection.status_detail = delivery_status.detail def annotate_warehouse_event_stats( connection: WarehouseConnection, environment_key: str, ) -> None: """Attach live warehouse event stats to a connection — from the managed warehouse for flagsmith connections, from the customer's instance for others. No-op for types that cannot be read or when no warehouse is configured; leaves stats unset when the warehouse is unreachable. Read-only: never changes status.""" try: stats = get_warehouse(connection.warehouse_type).get_event_stats( connection, environment_key ) except UnsupportedWarehouseOperation: return if stats is not None: connection.event_stats = stats