Class: LaunchDarkly::EvaluationReason
- Inherits:
-
Object
- Object
- LaunchDarkly::EvaluationReason
- Defined in:
- lib/ldclient-rb/evaluation_detail.rb
Overview
Describes the reason that a flag evaluation produced a particular value. This is returned by
methods such as LDClient#variation_detail as the reason property of an EvaluationDetail.
The kind property is always defined, but other properties will have non-nil values only for
certain values of kind. All properties are immutable.
There is a standard JSON representation of evaluation reasons when they appear in analytics events.
Use as_json or to_json to convert to this representation.
Use factory methods such as EvaluationReason.off to obtain instances of this class.
Constant Summary collapse
- OFF =
Value for #kind indicating that the flag was off and therefore returned its configured off value.
:OFF- FALLTHROUGH =
Value for #kind indicating that the flag was on but the context did not match any targets or rules.
:FALLTHROUGH- TARGET_MATCH =
Value for #kind indicating that the context key was specifically targeted for this flag.
:TARGET_MATCH- RULE_MATCH =
Value for #kind indicating that the context matched one of the flag's rules.
:RULE_MATCH- PREREQUISITE_FAILED =
Value for #kind indicating that the flag was considered off because it had at least one prerequisite flag that either was off or did not return the desired variation.
:PREREQUISITE_FAILED- ERROR =
Value for #kind indicating that the flag could not be evaluated, e.g. because it does not exist or due to an unexpected error. In this case the result value will be the application default value that the caller passed to the client. Check #error_kind for more details on the problem.
:ERROR- ERROR_CLIENT_NOT_READY =
Value for #error_kind indicating that the caller tried to evaluate a flag before the client had successfully initialized.
:CLIENT_NOT_READY- ERROR_FLAG_NOT_FOUND =
Value for #error_kind indicating that the caller provided a flag key that did not match any known flag.
:FLAG_NOT_FOUND- ERROR_MALFORMED_FLAG =
Value for #error_kind indicating that there was an internal inconsistency in the flag data, e.g. a rule specified a nonexistent variation. An error message will always be logged in this case.
:MALFORMED_FLAG- ERROR_WRONG_TYPE =
Value for #error_kind indicating that there was an inconsistency between the expected type of the flag, and the actual type of the variation evaluated.
:WRONG_TYPE- ERROR_USER_NOT_SPECIFIED =
Value for #error_kind indicating that the caller passed
nilfor the context parameter, or the context was invalid. :USER_NOT_SPECIFIED- ERROR_EXCEPTION =
Value for #error_kind indicating that an unexpected exception stopped flag evaluation. An error message will always be logged in this case.
:EXCEPTION- @@fallthrough_with_experiment =
new(:FALLTHROUGH, nil, nil, nil, nil, true)
- @@fallthrough =
new(:FALLTHROUGH, nil, nil, nil, nil)
- @@off =
new(:OFF, nil, nil, nil, nil)
- @@target_match =
new(:TARGET_MATCH, nil, nil, nil, nil)
- @@error_instances =
{ ERROR_CLIENT_NOT_READY => make_error(ERROR_CLIENT_NOT_READY), ERROR_FLAG_NOT_FOUND => make_error(ERROR_FLAG_NOT_FOUND), ERROR_MALFORMED_FLAG => make_error(ERROR_MALFORMED_FLAG), ERROR_USER_NOT_SPECIFIED => make_error(ERROR_USER_NOT_SPECIFIED), ERROR_EXCEPTION => make_error(ERROR_EXCEPTION), }
Instance Attribute Summary collapse
-
#big_segments_status ⇒ Symbol
readonly
Describes the validity of Big Segment information, if and only if the flag evaluation required querying at least one Big Segment.
-
#error_kind ⇒ Symbol
readonly
A value indicating the general category of error.
-
#in_experiment ⇒ Boolean|nil
readonly
A boolean or nil value representing if the rule or fallthrough has an experiment rollout.
-
#kind ⇒ Symbol
readonly
Indicates the general category of the reason.
-
#override_affected ⇒ Boolean
readonly
True if an override affected this evaluation, directly or transitively.
-
#prerequisite_key ⇒ String
readonly
The key of the prerequisite flag that did not return the desired variation.
-
#rule_id ⇒ String
readonly
A unique string identifier for the matched rule, which will not change if other rules are added or deleted.
-
#rule_index ⇒ Integer|nil
readonly
The index of the rule that was matched (0 for the first rule in the feature flag).
Class Method Summary collapse
-
.error(error_kind) ⇒ EvaluationReason
Returns an instance whose #kind is #ERROR.
-
.fallthrough(in_experiment = false) ⇒ EvaluationReason
Returns an instance whose #kind is #FALLTHROUGH.
-
.off ⇒ EvaluationReason
Returns an instance whose #kind is #OFF.
-
.prerequisite_failed(prerequisite_key) ⇒ EvaluationReason
Returns an instance whose #kind is #PREREQUISITE_FAILED.
-
.rule_match(rule_index, rule_id, in_experiment = false) ⇒ EvaluationReason
Returns an instance whose #kind is #RULE_MATCH.
-
.target_match ⇒ EvaluationReason
Returns an instance whose #kind is #TARGET_MATCH.
Instance Method Summary collapse
- #==(other) ⇒ Object
-
#[](key) ⇒ Object
Allows this object to be treated as a hash corresponding to its JSON representation.
-
#as_json ⇒ Hash
Returns a hash that can be used as a JSON representation of the reason, in the format used in LaunchDarkly analytics events.
-
#initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment = nil, big_segments_status = nil, override_affected = false) ⇒ EvaluationReason
constructor
Constructor that sets all properties.
-
#inspect ⇒ String
Returns a concise string representation of the reason.
-
#to_json(*a) ⇒ String
Same as #as_json, but converts the JSON structure into a string.
-
#to_s ⇒ String
Equivalent to #inspect.
- #with_big_segments_status(big_segments_status) ⇒ Object
-
#with_override_affected(override_affected) ⇒ EvaluationReason
Returns a reason that is the same as this one apart from the #override_affected indicator.
Constructor Details
#initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment = nil, big_segments_status = nil, override_affected = false) ⇒ EvaluationReason
Constructor that sets all properties. Applications should not normally use this constructor, but should use class methods like #off to avoid creating unnecessary instances.
361 362 363 364 365 366 367 368 369 370 371 372 373 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 361 def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment=nil, big_segments_status = nil, override_affected = false) @kind = kind.to_sym @rule_index = rule_index @rule_id = rule_id @rule_id.freeze unless rule_id.nil? @prerequisite_key = prerequisite_key @prerequisite_key.freeze unless prerequisite_key.nil? @error_kind = error_kind @in_experiment = in_experiment @big_segments_status = big_segments_status @override_affected = !!override_affected end |
Instance Attribute Details
#big_segments_status ⇒ Symbol (readonly)
Describes the validity of Big Segment information, if and only if the flag evaluation required
querying at least one Big Segment. Otherwise it returns nil. Possible values are defined by
BigSegmentsStatus.
Big Segments are a specific kind of context segments. For more information, read the LaunchDarkly documentation: https://docs.launchdarkly.com/home/users/big-segments
151 152 153 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 151 def big_segments_status @big_segments_status end |
#error_kind ⇒ Symbol (readonly)
A value indicating the general category of error. This should be one of the class constants such
as #ERROR_FLAG_NOT_FOUND. If #kind is not #ERROR, it will be nil.
142 143 144 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 142 def error_kind @error_kind end |
#in_experiment ⇒ Boolean|nil (readonly)
A boolean or nil value representing if the rule or fallthrough has an experiment rollout.
132 133 134 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 132 def in_experiment @in_experiment end |
#kind ⇒ Symbol (readonly)
Indicates the general category of the reason. Will always be one of the class constants such as #OFF.
118 119 120 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 118 def kind @kind end |
#override_affected ⇒ Boolean (readonly)
True if an override affected this evaluation, directly or transitively. It is true when the
evaluated flag came from the SDK's override store. It is also true when a prerequisite flag at
any depth, or a segment read during the evaluation, came from the override store. In the JSON
representation, the overrideAffected property appears only when this is true.
Flag overrides are currently experimental and subject to change.
160 161 162 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 160 def override_affected @override_affected end |
#prerequisite_key ⇒ String (readonly)
The key of the prerequisite flag that did not return the desired variation. If #kind is not
#PREREQUISITE_FAILED, this will be nil.
137 138 139 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 137 def prerequisite_key @prerequisite_key end |
#rule_id ⇒ String (readonly)
A unique string identifier for the matched rule, which will not change if other rules are added
or deleted. If #kind is not #RULE_MATCH, this will be nil.
128 129 130 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 128 def rule_id @rule_id end |
#rule_index ⇒ Integer|nil (readonly)
The index of the rule that was matched (0 for the first rule in the feature flag). If
#kind is not #RULE_MATCH, this will be nil.
123 124 125 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 123 def rule_index @rule_index end |
Class Method Details
.error(error_kind) ⇒ EvaluationReason
Returns an instance whose #kind is #ERROR.
218 219 220 221 222 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 218 def self.error(error_kind) raise ArgumentError.new("error_kind must be a symbol") unless error_kind.is_a? Symbol e = @@error_instances[error_kind] e.nil? ? make_error(error_kind) : e end |
.fallthrough(in_experiment = false) ⇒ EvaluationReason
Returns an instance whose #kind is #FALLTHROUGH.
170 171 172 173 174 175 176 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 170 def self.fallthrough(in_experiment=false) if in_experiment @@fallthrough_with_experiment else @@fallthrough end end |
.off ⇒ EvaluationReason
Returns an instance whose #kind is #OFF.
164 165 166 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 164 def self.off @@off end |
.prerequisite_failed(prerequisite_key) ⇒ EvaluationReason
Returns an instance whose #kind is #PREREQUISITE_FAILED.
208 209 210 211 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 208 def self.prerequisite_failed(prerequisite_key) raise ArgumentError.new("prerequisite_key must be a string") unless prerequisite_key.is_a? String new(:PREREQUISITE_FAILED, nil, nil, prerequisite_key, nil) end |
.rule_match(rule_index, rule_id, in_experiment = false) ⇒ EvaluationReason
Returns an instance whose #kind is #RULE_MATCH.
191 192 193 194 195 196 197 198 199 200 201 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 191 def self.rule_match(rule_index, rule_id, in_experiment=false) raise ArgumentError.new("rule_index must be a number") unless rule_index.is_a? Numeric raise ArgumentError.new("rule_id must be a string") if !rule_id.nil? && !(rule_id.is_a? String) # in test data, ID could be nil if in_experiment er = new(:RULE_MATCH, rule_index, rule_id, nil, nil, true) else er = new(:RULE_MATCH, rule_index, rule_id, nil, nil) end er end |
.target_match ⇒ EvaluationReason
Returns an instance whose #kind is #TARGET_MATCH.
180 181 182 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 180 def self.target_match @@target_match end |
Instance Method Details
#==(other) ⇒ Object
224 225 226 227 228 229 230 231 232 233 234 235 236 237 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 224 def ==(other) if other.is_a? EvaluationReason @kind == other.kind && @rule_index == other.rule_index && @rule_id == other.rule_id && @prerequisite_key == other.prerequisite_key && @error_kind == other.error_kind && @big_segments_status == other.big_segments_status && @override_affected == other.override_affected elsif other.is_a? Hash @kind.to_s == other[:kind] && @rule_index == other[:ruleIndex] && @rule_id == other[:ruleId] && @prerequisite_key == other[:prerequisiteKey] && (other[:errorKind] == @error_kind.nil? ? nil : @error_kind.to_s) && (other[:bigSegmentsStatus] == @big_segments_status.nil? ? nil : @big_segments_status.to_s) && !!other[:overrideAffected] == @override_affected end end |
#[](key) ⇒ Object
Allows this object to be treated as a hash corresponding to its JSON representation. For
instance, if reason.kind is #RULE_MATCH, then reason[:kind] will be "RULE_MATCH" and
reason[:ruleIndex] will be equal to reason.rule_index.
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 314 def [](key) case key when :kind @kind.to_s when :ruleIndex @rule_index when :ruleId @rule_id when :prerequisiteKey @prerequisite_key when :errorKind @error_kind.nil? ? nil : @error_kind.to_s when :bigSegmentsStatus @big_segments_status.nil? ? nil : @big_segments_status.to_s when :overrideAffected @override_affected else nil end end |
#as_json ⇒ Hash
Returns a hash that can be used as a JSON representation of the reason, in the format used in LaunchDarkly analytics events.
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 271 def as_json(*) # parameter is unused, but may be passed if we're using the json gem # Note that this implementation is somewhat inefficient; it allocates a new hash every time. # However, in normal usage the SDK only serializes reasons if 1. full event tracking is # enabled for a flag and the application called variation_detail, or 2. experimentation is # enabled for an evaluation. We can't reuse these hashes because an application could call # as_json and then modify the result. ret = case @kind when :RULE_MATCH if @in_experiment { kind: @kind, ruleIndex: @rule_index, ruleId: @rule_id, inExperiment: @in_experiment } else { kind: @kind, ruleIndex: @rule_index, ruleId: @rule_id } end when :PREREQUISITE_FAILED { kind: @kind, prerequisiteKey: @prerequisite_key } when :ERROR { kind: @kind, errorKind: @error_kind } when :FALLTHROUGH if @in_experiment { kind: @kind, inExperiment: @in_experiment } else { kind: @kind } end else { kind: @kind } end unless @big_segments_status.nil? ret[:bigSegmentsStatus] = @big_segments_status end # The property is written only when true, so the wire format of an ordinary evaluation is unchanged. ret[:overrideAffected] = true if @override_affected ret end |
#inspect ⇒ String
Returns a concise string representation of the reason. Examples: "FALLTHROUGH",
"ERROR(FLAG_NOT_FOUND)". The exact syntax is not guaranteed to remain the same; this is meant
for debugging.
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 249 def inspect case @kind when :RULE_MATCH if @in_experiment "RULE_MATCH(#{@rule_index},#{@rule_id},#{@in_experiment})" else "RULE_MATCH(#{@rule_index},#{@rule_id})" end when :PREREQUISITE_FAILED "PREREQUISITE_FAILED(#{@prerequisite_key})" when :ERROR "ERROR(#{@error_kind})" when :FALLTHROUGH @in_experiment ? "FALLTHROUGH(#{@in_experiment})" : @kind.to_s else @kind.to_s end end |
#to_json(*a) ⇒ String
Same as #as_json, but converts the JSON structure into a string.
307 308 309 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 307 def to_json(*a) as_json.to_json(*a) end |
#to_s ⇒ String
Equivalent to #inspect.
241 242 243 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 241 def to_s inspect end |
#with_big_segments_status(big_segments_status) ⇒ Object
335 336 337 338 339 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 335 def with_big_segments_status(big_segments_status) return self if @big_segments_status == big_segments_status EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment, big_segments_status, @override_affected) end |
#with_override_affected(override_affected) ⇒ EvaluationReason
Returns a reason that is the same as this one apart from the #override_affected indicator. Returns this instance when the indicator already has the given value.
Flag overrides are currently experimental and subject to change.
350 351 352 353 354 355 |
# File 'lib/ldclient-rb/evaluation_detail.rb', line 350 def with_override_affected(override_affected) override_affected = !!override_affected return self if @override_affected == override_affected EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment, @big_segments_status, override_affected) end |