Class: PostHog::FeatureFlagEvaluations

Inherits:
Object
  • Object
show all
Defined in:
lib/posthog/feature_flag_evaluations.rb

Overview

A snapshot of feature flag evaluations for one distinct_id, returned by PostHog::Client#evaluate_flags. Calls to #enabled? / #get_flag fire the $feature_flag_called event (deduped through the existing per-distinct_id cache); #get_flag_payload does not. Pass the snapshot to capture(flags:) to attach $feature/<key> and $active_feature_flags without a second /flags request.

Defined Under Namespace

Classes: EvaluatedFlagRecord, Host

Constant Summary collapse

EVALUATED_LOCALLY_REASON = 
'Evaluated locally'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host: nil, distinct_id: nil, flags: {}, groups: nil, disable_geoip: nil, request_id: nil, evaluated_at: nil, flag_definitions_loaded_at: nil, errors_while_computing: false, quota_limited: false, minimal_flag_called_events: false, accessed: nil) ⇒ FeatureFlagEvaluations

Returns a new instance of FeatureFlagEvaluations.

Parameters:

  • host (Host, nil) (defaults to: nil) —

    Internal host callbacks used to record flag access events.

  • distinct_id (String, nil) (defaults to: nil) —

    The distinct id these evaluations belong to.

  • flags (Hash) (defaults to: {}) —

    Evaluated flags keyed by flag key.

  • groups (Hash, nil) (defaults to: nil) —

    Group analytics mapping from group type to group key.

  • disable_geoip (Boolean, nil) (defaults to: nil) —

    Whether GeoIP was disabled during evaluation.

  • request_id (String, nil) (defaults to: nil) —

    The request id returned by the /flags endpoint.

  • evaluated_at (String, nil) (defaults to: nil) —

    The evaluation timestamp returned by the /flags endpoint.

  • flag_definitions_loaded_at (Time, nil) (defaults to: nil) —

    When local flag definitions were loaded.

  • errors_while_computing (Boolean) (defaults to: false) —

    Whether the server reported errors while computing flags.

  • quota_limited (Boolean) (defaults to: false) —

    Whether feature flag evaluation was quota limited.

  • minimal_flag_called_events (Boolean) (defaults to: false) —

    Server-controlled gate for minimal $feature_flag_called events.

  • accessed (Array<String>, Set<String>, nil) (defaults to: nil) —

    Flag keys already accessed by this snapshot.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 50

def initialize(
  host: nil,
  distinct_id: nil,
  flags: {},
  groups: nil,
  disable_geoip: nil,
  request_id: nil,
  evaluated_at: nil,
  flag_definitions_loaded_at: nil,
  errors_while_computing: false,
  quota_limited: false,
  minimal_flag_called_events: false,
  accessed: nil
)
  @host = host
  @distinct_id = distinct_id || ''
  @flags = flags || {}
  @groups = groups
  @disable_geoip = disable_geoip
  @request_id = request_id
  @evaluated_at = evaluated_at
  @flag_definitions_loaded_at = flag_definitions_loaded_at
  @errors_while_computing = errors_while_computing
  @quota_limited = quota_limited
  @minimal_flag_called_events = minimal_flag_called_events == true
  @accessed = Set.new(accessed || [])
end

Instance Attribute Details

#distinct_id ⇒ String (readonly)

Returns The distinct id these evaluations belong to.

Returns:

  • (String) —

    The distinct id these evaluations belong to.



23
24
25
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 23

def distinct_id
  @distinct_id
end

#evaluated_at ⇒ String? (readonly)

Returns Evaluation timestamp returned by the /flags endpoint.

Returns:

  • (String, nil) —

    Evaluation timestamp returned by the /flags endpoint.



32
33
34
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 32

def evaluated_at
  @evaluated_at
end

#flag_definitions_loaded_at ⇒ Time? (readonly)

Returns When local flag definitions were loaded.

Returns:

  • (Time, nil) —

    When local flag definitions were loaded.



35
36
37
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 35

def flag_definitions_loaded_at
  @flag_definitions_loaded_at
end

#groups ⇒ Hash? (readonly)

Returns Group analytics mapping used for evaluation.

Returns:

  • (Hash, nil) —

    Group analytics mapping used for evaluation.



26
27
28
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 26

def groups
  @groups
end

#request_id ⇒ String? (readonly)

Returns Request id returned by the /flags endpoint.

Returns:

  • (String, nil) —

    Request id returned by the /flags endpoint.



29
30
31
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 29

def request_id
  @request_id
end

Instance Method Details

#_get_event_properties ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds the $feature/<key> and $active_feature_flags properties for a captured event. Called from PostHog::Client#capture when flags: is set.

Returns:

  • (Hash) 


138
139
140
141
142
143
144
145
146
147
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 138

def _get_event_properties
  properties = {}
  active = []
  @flags.each do |key, flag|
    properties["$feature/#{key}"] = flag.enabled ? (flag.variant || true) : false
    active << key if flag.enabled
  end
  properties['$active_feature_flags'] = active.sort unless active.empty?
  properties
end

#enabled?(key) ⇒ Boolean

Returns true when the flag is enabled, false when disabled or missing.

Parameters:

  • key (String, Symbol) —

    The feature flag key.

Returns:

  • (Boolean) —

    true when the flag is enabled, false when disabled or missing.



85
86
87
88
89
90
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 85

def enabled?(key)
  key = key.to_s
  flag = @flags[key]
  _record_access(key, flag)
  flag&.enabled ? true : false
end

#get_flag(key) ⇒ String, ...

Returns Variant string for multivariate flags, true/false for boolean flags, or nil when the flag was not returned by the evaluation.

Parameters:

  • key (String, Symbol) —

    The feature flag key.

Returns:

  • (String, Boolean, nil) —

    Variant string for multivariate flags, true/false for boolean flags, or nil when the flag was not returned by the evaluation.



95
96
97
98
99
100
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 95

def get_flag(key)
  key = key.to_s
  flag = @flags[key]
  _record_access(key, flag)
  _flag_value(flag)
end

#get_flag_payload(key) ⇒ Object?

Returns The parsed payload for the flag, if any.

Parameters:

  • key (String, Symbol) —

    The feature flag key.

Returns:

  • (Object, nil) —

    The parsed payload for the flag, if any.



104
105
106
107
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 104

def get_flag_payload(key)
  flag = @flags[key.to_s]
  flag&.payload
end

#keys ⇒ Array<String>

Returns The evaluated flag keys in this snapshot.

Returns:

  • (Array<String>) —

    The evaluated flag keys in this snapshot.



79
80
81
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 79

def keys
  @flags.keys
end

#only(keys) ⇒ PostHog::FeatureFlagEvaluations

Returns A snapshot containing only the requested keys that exist.

Parameters:

  • keys (Array<String, Symbol>, String, Symbol) —

    Flag keys to keep in the returned snapshot.

Returns:



120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 120

def only(keys)
  keys = Array(keys).map(&:to_s)
  missing = keys.reject { |k| @flags.key?(k) }
  unless missing.empty?
    @host.log_warning.call(
      'FeatureFlagEvaluations#only was called with flag keys that are not in the ' \
      "evaluation set and will be dropped: #{missing.join(', ')}"
    )
  end
  filtered = @flags.slice(*keys)
  _clone_with(filtered)
end

#only_accessed ⇒ PostHog::FeatureFlagEvaluations

Order-dependent: if nothing has been accessed yet, the returned snapshot is empty. The method honors its name — pre-access flags before calling this if you want a populated result.

Returns:



114
115
116
 
# File 'lib/posthog/feature_flag_evaluations.rb', line 114

def only_accessed
  _clone_with(@flags.slice(*@accessed))
end