Evaluation reasons

Overview

This topic explains how to use LaunchDarkly to determine why a context instance receives a given flag variation. It can be useful to have this information when you’re diagnosing problems or doing analysis of the impact of different flags.

You can access this information programmatically from your SDK or from Data Export events. To learn more about Data Export, read Data Export.

You can also view evaluation reasons on the context detail page. To learn how, read The context details page.

Accessing flag variation information programmatically

For each of the SDK methods that you call to evaluate a feature flag, there is a corresponding detail method.

This method returns three pieces of information:

• The computed flag variation, which is what you get when you evaluate the flag
• The variation index, which is a zero-based integer indicating which variation was selected. For example, if the flag’s possible variations are A, B, and C, in that order, and the computed variation is C, the variation index would be 2. This value is useful for tabulation, although in some cases, it may be absent. To learn more, read Error conditions.
• A reason object, which contains information about why that variation was selected. This data structure is described below.

Try it in your SDK: Flag evaluation reasons

Understanding the reason data

In strongly-typed languages, the reason object is composed of specific classes. In other languages, it is a hash, such as a dictionary or object.

The JSON representation is the same in every language, so we will describe the reason object here as if it were a JSON object.

The reason object’s only required property is kind. This describes the general reason that LaunchDarkly selected this variation. The possible values for kind are enums in the strongly-typed languages and strings in other languages.

These values are:

inExperiment is an optional attribute on the reason object that indicates whether the context was evaluated as part of an experiment:

• If inExperiment is true, LaunchDarkly includes the event in experimentation analysis
• If inExperiment is false, LaunchDarkly does not include this attribute in the reason object

For a list of SDKs that support experiment allocation, read Allocating experiment audiences.

Error conditions

If the kind is ERROR, it means that the SDK was unable to select any of the flag’s variations. This is an abnormal occurrence.

In this case, the returned flag value is the default value that you specified in your code, which is the last parameter of the method you called to evaluate the flag, rather than any value that you specified on your flag’s Targeting tab. In addition, the variation index will be null/nil.

When there is an error, the reason object also has an errorKind property which will be one of the following:

Understanding how Data Export events display

Calling any of the variation detail methods not only makes extra information available to your code, it also causes the SDK to include it in analytics events. You can view this information if you use the Live events page or Data Export.

To learn more, read Live events and Data Export.

The JSON representation of the reason data will be included in the feature evaluation event as an extra property called reason.

For instance, a debug event might look like this:

1
{
2
  "kind": "debug",
3
  "context": {
4
      "key": "example-context-key",
5
      "kind": "user",
6
      "name": "Sandy"
7
  },
8
  "creationDate": 1548195712000,
9
  "key": "example-flag-key",
10
  "version": 1000,
11
  "variation": 0,
12
  "value": true,
13
  "default": false,
14
  "reason": {
15
      "kind": "TARGET_MATCH",
16
      "inExperiment": true
17
  }
18
}