Repository navigation
feat(flags): support known-absent property keys in local evaluation - #1280
marandaneto wants to merge 7 commits into
Conversation
SDK performance: posthog-python3 changes worth reviewing: 3 observed regressions. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.
View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
PR overviewNo security issues were found in this pull request. Reviews
|
💡 Motivation and Context
Closes the Python part of PostHog/posthog#88947.
Local flag evaluation can't tell a missing property apart from one the caller didn't pass. If a key is left out of
person_properties, the condition that reads it is inconclusive and the SDK asks/flags. Callers had no way to say "this person definitely doesn't haveplan". So a flag withplan is_not_setcould never resolve locally. The local result and the/flagsresult could also disagree.The flags service now accepts known-absent keys (PostHog/posthog#138239). This PR adds the same input to the SDK, following the cross-SDK spec in PostHog/sdk-specs#233.
New input
Two optional keyword arguments:
person_property_keys_known_absent: a collection of person property keys.group_property_keys_known_absent: a mapping from group type to a collection of group property keys.They are accepted by
evaluate_flags,get_feature_flag,get_feature_flag_result,feature_enabled,get_feature_flag_payload,get_all_flags,get_all_flags_and_payloads,get_feature_variants,get_feature_payloads,get_feature_flags_and_payloads,get_flags_decision, and the module-level wrappers. They also work incapture(send_feature_flags={...})and inAsyncClient.evaluate_flags. Existing signatures don't change.Local evaluation
distinct_idand$group_key.is_not_set,is_not,not_icontains,not_starts_with,not_ends_withandnot_regexmatch. Every other supported operator does not match. That includesis_set,exact,gt, allsemver_*operators and the date operators. The result is final, with no/flagsrequest./flagseven when the key is listed.test_cohort_leaf_unsupported_operator_falls_back_before_known_absencecovers a cohort leafplan not_between [1, 2]with and withoutnegation.__posthog_person_metadata__are ignored.negation. Flag dependencies are evaluated with the same listed keys.$feature_enrollment/<flag key>means the person is not enrolled. Evaluation then continues to holdouts and release conditions instead of returning early or falling back. Python is the only SDK with local enrollment handling./flagsrequest bodyWhen the SDK calls
/flagsand the caller listed keys, the body includesperson_property_keys_known_absent: [...]andgroup_property_keys_known_absent: {"<group type>": [...]}. This happens for local fallback, forced remote calls, and remote-only calls. A field is left out when it wasn't provided or is empty.Limits
Each list holds at most 1000 keys. Duplicates count. For groups the limit applies per group type. A longer list raises
ValueErrorfrom the flag getters. Nothing is evaluated and no request is sent. The SDK never truncates the list. Wrong types raiseTypeError, for example a plain string or a non-string group type. Withcapture(send_feature_flags={...}), the error is handled like othercaptureerrors.capturelogs it and returnsNone, and no event is sent. Withdebug=Trueit raises.Compliance adapter
The adapter now declares
feature_flags_known_absent_v1./get_feature_flagpasses both new params to the SDK unchanged. It also acceptsallow_remote_fallback: true, which calls the default getter on the client with local definitions. That mode returns HTTP 400 when combined withforce_remote: trueoronly_evaluate_locally: true.Not included
icontains_multi,not_icontains_multi,betweenandnot_betweenoperators. The SDK doesn't support them yet, so a listed key with these operators still falls back to/flags. Tracked in Support icontains_multi and between operators in SDK local flag evaluation posthog#138581.Links
💚 How did you test it?
New tests in
posthog/test/test_feature_flags_known_absent.py:distinct_id, and$group_key./flags.negation, and a flag dependency./flagsbody including the fields on fallback and on every remote entry point, includingcapture(send_feature_flags=...)and asyncevaluate_flags. The fields are left out when not provided or empty.capturepath with default and debug settings, and wrong types./flagsbody.sdk_compliance_adapter/test_adapter.pycovers the new adapter params andallow_remote_fallback.Commands run locally with
uv run --no-syncon macOS:ruff format --check .passed.ruff check .passed.mypy --no-site-packages --config-file mypy.ini . | mypy-baseline filterpassed.make public_api_checkpassed. The snapshot is updated in this PR.python -W error -c "import posthog"passed.pytest sdk_compliance_adapter/test_adapter.pypassed.pytest --timeout=30gave 8397 passed and 3 failed. The 3 failures are fork tests inposthog/test/test_metrics_autocapture.py. They also fail on unchangedmainon macOS.After the spec revision I added the cohort-leaf test. It passed with no production change. I re-ran
ruff format --check .,ruff check ., mypy with the baseline filter,make public_api_checkandpython -W error -c "import posthog", and all passed.pytest --timeout=30gave 8399 passed and the same 3 fork test failures inposthog/test/test_metrics_autocapture.py.CI now runs SDK test harness 1.34.0. The
feature_flags_known_absentsuite ran and passed 12/12 in each compliance job (gzip, deflate and zstd).📝 Checklist
If releasing new changes
sampo addto generate a changeset file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Written with Pi (Claude) and reviewed with the autoreview skill (GPT model, branch mode). Review found three real problems, which are fixed in separate commits. Validation consumed one-shot iterators before the
/flagscall. Unbounded iterables were read fully before the limit check. Non-string group types andNonegroup lists were accepted. A fourth review run was clean.capturekeeps its existing error handling for invalid known-absent keys instead of raising. This matches how it already treats an invalidsend_feature_flagsvalue.