Repository navigation
Conversation
Copy the $feature_flag_called and $experiment_exposure property schemas unchanged from the same test harness release as the other contract fixtures, and record their digests in SOURCE.json.
A remotely evaluated config version 2 flag whose record assigns an experiment variant now sends $experiment_exposure next to $feature_flag_called. $feature_flag_called for every config version 2 flag also reports its config version, reason code, rule ID, rule type and, for a complete split, variant key, and its dedupe key includes them so equal-valued arms and successive experiments are each reported. Both events are built in one step that every flag read goes through on both clients, from the parsed record that supplied the value. The exposure has its own dedupe cache, keyed by distinct ID, groups, flag, rule and variant, so a reported call never suppresses it. A split missing its rule type, rule ID or variant key sends no exposure and reports no rule tuple. Config version 1 flags, local evaluation and $feature_flag_response are unchanged.
Contributor
posthog-python Compliance ReportDate: 2026-10-30T20:01:15.399514+00:00 ✅ All Tests Passed!121/121 tests passed Capture_V1 Tests✅ 95/95 tests passed View Details
Capture_Ai Tests✅ 5/5 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
Feature_Flags_Local_Evaluation Tests✅ 4/4 tests passed View Details
|
![posthog[bot]](https://avatars.githubusercontent.com/in/1203049?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
PostHog Review · Standard · reviewed fdb2709: 4 Should fix.
This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
Comment on lines
+4753
to
+4754
| value_from_details=isinstance(flag_details, FeatureFlag) | ||
| and response == flag_details.get_value(), |
Contributor
There was a problem hiding this comment.
P2 · Track explicit payload overrides independently of value equality
When get_feature_flag_payload() receives an explicit match_value equal to the remote split's value, this equality marks the caller's override as server-supplied and emits $experiment_exposure. The payload lookup also consumes the exposure dedupe entry before a subsequent value read. Thread the override's presence through instead of inferring provenance from equality.
| ) | ||
| reported_flags.add(feature_flag_reported_key) | ||
|
|
||
| if attribution is None or attribution.variant_key is None or not value_from_details: |
Contributor
There was a problem hiding this comment.
P2 · Exclude failed records from exposure emission
When a v4 record has failed: true but retains complete split metadata, the parser discards its value and returns the disabled fallback. _capture_flag_events nevertheless emits $experiment_exposure for the retained variant on both clients, counting a failed evaluation as an assignment. Check the parsed failure state before emitting an exposure.
| groups=capture_groups, | ||
| disable_geoip=disable_geoip, | ||
| ) | ||
| reported_exposures.add(exposure_key) |
Contributor
There was a problem hiding this comment.
P2 · Record exposure deduplication only after capture succeeds
When the capture queue fills, capture() returns None, but _capture_flag_events still adds the assignment to reported_exposures. Every subsequent read suppresses that exposure after the queue recovers, losing experiment attribution until eviction or shutdown. Check the capture result and retain the dedupe entry only when the event is accepted.
Comment on lines
+564
to
+565
| if exposure_key in reported_exposures: | ||
| return |
Contributor
There was a problem hiding this comment.
P2 · Reserve exposure keys atomically before capturing
When threads read the same assignment with sync_mode=True, the first exposure's network request releases execution before its key is recorded. Another thread passes this check and sends another exposure with a separate UUID, defeating per-assignment deduplication. Atomically reserve the key before capture and release the reservation when capture fails.
$feature_flag_called for a config version 2 record now sends $feature_flag_rule_id and $feature_flag_rule_type only for a targeting match, a rollout miss, a paused experiment, a holdout and a complete experiment split. Any other reason code, including one the SDK does not know, and any failed record send neither, even when the record carries them. A failed experiment split therefore sends no exposure either.
The single-flag path decided whether a read's record supplied its value by comparing the reported value with the record's. Equal values do not show where a value came from: a payload lookup whose match_value equals the record's value, such as True for a number or object arm, sent the exposure and reserved its dedupe key, so the real read sent none. The path now sets value_from_details only when the remote record supplied the value: not for a caller's match_value, and not for a stale cached value used after a failure. Snapshot reads pass it explicitly, and the capture helpers default to no exposure.
$experiment_exposure no longer carries $feature_flag_config_version, $feature_flag_rule_type, $feature_flag_reason_code or $experiment_exposure_source. The exposure of a complete config version 2 experiment split identifies the assignment by flag, variant key and rule ID; the config version, rule type and reason code stay on the $feature_flag_called of the same read. The trigger, both dedupe keys and $feature_flag_response are unchanged. The vendored exposure schema still requires the removed properties, so the tests check exposures against it without them, and check that they are absent.
$feature_flag_called for a config version 2 flag carried both $feature_flag_reason_code and the human-readable $feature_flag_reason. The reason code now replaces the description on these events, full and minimal. Events of config version 1 flags, flags from servers without typed values and locally evaluated flags keep $feature_flag_reason as before.
Contract 8.0.0 trims the experiment exposure schema to the properties the SDK sends and rejects $feature_flag_reason on config version 2 calls, so the exposure validator no longer drops properties from the vendored schema. The four other vendored files are unchanged.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When a remotely evaluated config version 2 flag assigns an experiment variant, the SDK now sends a direct
$experiment_exposureevent next to$feature_flag_called.$feature_flag_calledfor every config version 2 flag now also carries the flag's config version, reason code and rule attribution, and the reason code replaces the human-readable$feature_flag_reasonon these events.This stacks on #1031 (base
feat/flags-v3-response), which parses the/flags?v=4records and keeps them on the flag. #1031 left event emission unchanged; this PR is where it changes.When
$experiment_exposureis sentA read sends
$experiment_exposurewhen it sends$feature_flag_calledand all of these hold for the flag record that supplied its value:failedmetadata.config_versionis2reason.codeisexperiment_splitmetadata.rule_typeisexperimentmetadata.rule_idandmetadata.variant_keyare presentThe reads are
get_feature_flag(),feature_enabled(),get_feature_flag_result(),get_feature_flag_payload(..., send_feature_flag_events=True)withoutmatch_value, andis_enabled()andget_flag()on anevaluate_flags()snapshot, on both the sync and async clients.Nothing else sends it: targeting matches, rollouts, rollout misses, holdouts, paused experiments, defaults, failures, config version 1 flags, locally evaluated flags, and stale cached values.
send_feature_flag_events=Falsesuppresses both events, and payload reads that send no$feature_flag_calledsend no exposure either. The exposure goes through the samecapture()as$feature_flag_called, so a capture failure never changes the value a read returns.$feature_flag_calledadditionsAdded only for config version 2 records:
$feature_flag_config_version2$feature_flag_reason_codereason.code, such asholdout. It replaces the human-readable$feature_flag_reason, which a config version 2 event no longer carries, full or minimal.$feature_flag_rule_idmetadata.rule_id, by the table below$feature_flag_rule_typemetadata.rule_type, by the table below$feature_flag_variantmetadata.variant_key, for a complete experiment split onlyWhat each outcome reports:
experiment_splittargeting_matchrollout_missexperiment_pausedholdoutno_rule_match,missing_group_key,flag_disabled,dependency_error,error, any other reason code, and any failed recordThe SDK never sends a field the table marks "no", even when the record carries it.
No event carries an experiment ID, a holdout ID or a seed.
$feature_flag_responseis unchanged.$experiment_exposureproperties$feature_flag$feature_flag_response$feature_flag_called(the legacy rendering)$feature_flag_variantmetadata.variant_key$feature_flag_rule_idmetadata.rule_idlocally_evaluatedfalse$feature_flag_id,$feature_flag_version,$feature_flag_request_id,$feature_flag_evaluated_at$feature_flag_called, when presentLike any captured event it also gets the library properties and
$groups, and it uses the same distinct ID, groups and GeoIP setting as its$feature_flag_called. It is a separate capture with its own event UUID. It carries no payload and no$feature/<key>. It does not carry the config version, rule type, reason code or an exposure source; the config version, rule type and reason code stay on the$feature_flag_calledof the same read.Dedupe
$feature_flag_calledkeeps its dedupe key (distinct ID, flag key, response, sorted groups). For a config version 2 record the key also includes the config version, reason code, rule ID, rule type and variant key. Equal-valued A/A arms, successive experiments on one flag, and a holdout followed by a split of the same rule are therefore each reported. Config version 1 keys are unchanged.$experiment_exposurehas its own cache, keyed by the distinct ID as a string, the sorted groups, the flag key, the config version, the rule ID and the variant key. The value, request ID, evaluation time and local/remote source are left out, so one assignment sends one exposure however often it is read. Because the cache is separate, a$feature_flag_calledthat was already reported never suppresses its exposure. It has the same bound and eviction as the flag-called cache, and shutdown clears it.What does not change
$feature_flag_reason, same dedupe key.$feature_flag_responsestays the legacy rendering of the value.$feature_flag_reason.Notes for reviewers
_capture_flag_eventsinposthog/client.pybuilds both events. Both clients'_capture_feature_flag_called_if_needed, which every single-flag getter and snapshot read already goes through, now call it, and the snapshot passes the record it already keeps from feat(flags): read the /flags?v=4 response #1031. A later read that reports through the snapshot's_record_access, such as the typed accessors in feat(flags): typed flag value accessors #1147 or the per-read option in feat: add a per-read send_feature_flag_events option to snapshot reads #1148, gets the exposure without changes. The decision reads the record, never the value the accessor returned, so a typed read that returns the caller default for anullorfalsevalue still reports the assignment, as docs(flags): propose typed flag values and evaluation details sdk-specs#104 asks. A typed read of the wrong type (TYPE_MISMATCH) sends neither event (feat(flags): typed flag value accessors #1147)._failed,_config_versionand so on), and feat(flags): typed flag value accessors #1147 makes them public._v4_fieldreads either spelling, so this PR and feat(flags): typed flag value accessors #1147 can merge in either order; the fallback can go once both have landed. A local merge with feat(flags): typed flag value accessors #1147 at b749299 has no conflicts and the flag test modules pass. Its typed reads send the exposure. A read of the wrong type sends neither event; the next read of the right type, or aget_flag()oris_enabled()read, then sends both.experiment_splitrecord without rule typeexperiment, a rule ID or a variant key sends no exposure. Its$feature_flag_calledkeeps the config version and reason code but leaves out the rule ID, rule type and variant together, never part of them. The SDK never guesses the identity from the value, the key or an earlier result.targeting_match,rollout_miss,experiment_paused,holdoutand a completeexperiment_split. Every other reason code, including codes this SDK does not know, and every failed record send neither, even if the record carries them. Only a complete split sends$feature_flag_variant. This is a small allowlist in_rule_attribution, and it fails closed like the malformed split. It matches the contract's$feature_flag_calledproperty schema.true. The single-flag path setsvalue_from_detailsonly when the remote record supplied the value.get_feature_flag_payload(match_value=..., send_feature_flag_events=True)reports the caller's value, so it sends no exposure, even when that value equals the record's. Its call keeps the record's attribution, so it still reads as a config version 2 event, and a later read of the record sends the exposure. A stale cached value used after a failure sends no exposure either. Snapshot reads always report their record's value.$feature_flag_reasonstays on the allowlist for config version 1 events; a config version 2 event drops it before the allowlist applies. The exposure is never minimized.$feature_flag_calledand$experiment_exposureproperty schemas, copied unchanged from harness release 1.27.0 (contract 8.0.0) and recorded inSOURCE.json. That release trims the exposure schema to the properties this SDK sends and rejects$feature_flag_reasonon config version 2 calls. The schema projection drops undeclared properties, so the tests also assert that no exposure carries$feature_flag_config_version,$feature_flag_rule_type,$feature_flag_reason_codeor$experiment_exposure_source.add-experiment-exposure) is the cross-SDK contract for this behaviour: when the exposure is sent, its properties, the$feature_flag_calledattribution and rule-field table, both dedupe keys, and minimal events. This PR follows it. The$feature_flag_calleddedupe key here also includes the reason code and rule type, which fix(llm-observability): include the ai packages #162 is adopting.Test plan
posthog/test/test_experiment_exposure.py: the reader cases on every read path and both clients, exact property sets (no exposure carries the four removed properties), rule fields by reason code (including stray rule fields on no-rule, failed and unknown-reason records), schema validation of every$feature_flag_calledcontext, separate UUIDs, dedupe (repeat reads, A/A arms, a new rule, value changes, groups, distinct ID types, a reported call not suppressing its exposure), opt-out, payload reads, local evaluation, older servers, minimal events, shutdown$feature_flag_reason: left out of config version 2 calls (targeting match, no rule match, failed, split) on every read path, on the async client and on minimal events; kept on config version 1 and older-server calls, full and minimaluv run --frozen --all-extras pytest -q -p no:cacheprovider posthog/testruff format --check .,ruff check ., mypy with the baseline filter, public API snapshot unchanged🤖 Generated with Claude Code