Flag evaluation reasons

Overview

This topic explains how to use the flag evaluation reason feature to get more information about the flag variations LaunchDarkly serves to users.

To learn more about how LaunchDarkly determines why a user receives a given flag variation, read Evaluation reasons.

Understanding the flag evaluation reason feature

Details about each SDK's configuration are available in the SDK-specific sections below.

• Client-side SDKs
• Server-side SDKs

Client-side SDKs

This feature is available in the following client-side SDKs:

• Android
• Flutter
• iOS
• JavaScript
• Node.js (client-side)
• React Native
• Roku
• Xamarin

Android

The variationDetail methods, such as boolVariationDetail, work the same as variation. They also provide additional "reason" information about how a flag value was calculated, such as if the user matched a specific rule. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1EvaluationDetail<Boolean> detail =
2  client.boolVariationDetail("flag-key", false);
3  // or stringVariationDetail for a string-valued flag, etc.
4
5boolean value = detail.getValue();
6Integer index = detail.getVariationIndex();
7EvaluationReason reason = detail.getReason();
COPY

To learn more, read EvaluationDetail and getVariationIndex.

Flutter

The variationDetail methods, such as boolVariationDetail, work the same as variation. They also provide additional "reason" information about how a flag value was calculated, such as if the user matched a specific rule. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1LDEvaluationDetail<bool> detail =
2  await LDClient.boolVariationDetail("flag-key", false);
3  // or stringVariationDetail for a string-valued flag, etc.
4
5bool value = detail.value;
6int index = detail.variationIndex;
7LDEvaluationReason reason = detail.reason;
COPY

To learn more, read LDEvaluationDetail and boolVariationDetail.

iOS

The variationDetail methods, such as boolVariationDetail, work the same as variation. They also provide additional "reason" information about how a flag value was calculated, such as if the user matched a specific rule. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1let LDEvaluationDetail<Bool> detail =
2  client.variationDetail("flag-key", false);
3
4Bool value = detail.value;
5Int? index = detail.variationIndex;
6Dictionary<String, Any>? reason = detail.reason;
COPY

To learn more, read LDEvaluationDetail and variationDetail.

JavaScript

The variationDetail method lets you evaluate a feature flag with the same parameters you would for variation. With variationDetail, you receive more information about how the value was calculated.

The variation detail returns in an object containing both the result value and a "reason" object which tells you more information about the flag evaluation. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. It also indicates if the flag returned the default value due to an error. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1var detail = client.variationDetail("flag-key", false);
2
3var value = detail.value;
4var index = detail.variationIndex;
5var reason = detail.reason;
COPY

To learn more, read LDEvaluationDetail and variationDetail.

Node.js (client-side)

The variationDetail method lets you evaluate a feature flag with the same parameters you would for variation. With variationDetail, you receive more information about how the value was calculated.

The variation detail returns in an object that contains both the result value and a "reason" object which tells you more information about the flag evaluation. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. It also indicates if the flag returned the default value due to an error. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1var detail = client.variationDetail("flag-key", false);
2
3var value = detail.value;
4var index = detail.variationIndex;
5var reason = detail.reason;
COPY

To learn more, read LDEvaluationDetail and variationDetail.

React Native

The variationDetail methods work the same as variation, but also provide additional reason information about how a flag value was calculated. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1const detail =
2  client.boolVariationDetail("flag-key", false);
3
4const value = detail.value;
5const index = detail.variationIndex;
6const reason = detail.reason;
COPY

To learn more, read LDEvaluationDetail and boolVariationDetail.

Roku

For each variation type there is also an associated version that returns the reason a particular value was returned.

Here is an example:

1details = launchDarkly.intVariationDetail("MY_FLAG_KEY", 123)
COPY

These variation methods return an object containing the keys value, reason, and variationIndex. The value field is the result of the evaluation. The reason field is an object that explains why the result happened, for example details about a rule match. The reason object will always contain a kind field. Lastly the variationIndex field contains the ID of the particular value returned. This field may be null.

Xamarin

The VariationDetail methods, such as BoolVariationDetail, work the same as Variation, but also provide additional "reason" information about how a flag value was calculated. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1EvaluationDetail<bool> detail =
2  client.BoolVariationDetail("flag-key", false);
3  // or StringVariationDetail for a string-valued flag, etc.
4
5bool value = detail.Value;
6int? index = detail.VariationIndex;
7EvaluationReason reason = detail.Reason;
COPY

To learn more, read EvaluationDetail and BoolVariationDetail.

Server-side SDKs

Unlike client-side SDKs, you do not need to enable an evaluation reason configuration option in server-side SDKs for this feature to work.

This feature is available in the following server-side SDKs:

• .NET
• Apex
• C/C++ (server-side)
• Erlang
• Go
• Haskell
• Java
• Lua
• Node.js (server-side)
• PHP
• Python
• Ruby

.NET

The VariationDetail methods, such as BoolVariationDetail, work the same as the Variation methods, but also provide additional "reason" information about how a flag value was calculated. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1EvaluationDetail<bool> detail =
2  client.BoolVariationDetail("flag-key", myUser, false);
3  // or StringVariationDetail for a string-valued flag, etc.
4
5bool value = detail.Value;
6int? index = detail.VariationIndex;
7EvaluationReason reason = detail.Reason;
COPY

To learn more, read EvaluationDetail, BoolVariationDetail.

Apex

By passing an LDClient.EvaluationDetail object to a variation call you can programmatically inspect the reason for a particular evaluation.

Here is an example:

1LDClient.EvaluationDetail details = new LDClient.EvaluationDetail();
2
3Boolean value = client.boolVariation(user, 'your.feature.key', false, details);
4
5/* inspect details here */
6if (details.getReason().getKind() == EvaluationReason.Kind.OFF) {
7    /* ... */
8}
COPY

C/C++ (server-side)

By passing an LDDetails struct to a variation call you can programmatically inspect the reason for a particular evaluation.

Here is an example:

1struct LDDetails details;
2bool value = LDBoolVariation(client, user, "your.feature.key", false, &details);
3
4/* inspect details here */
5if (details.reason == LD_FLAG_NOT_FOUND) {
6    /* ... */
7}
8
9LDDetailsClear(&details);
COPY

To learn more about the LDDetails structure, inspect ldvariations.h.

Erlang

The variation_detail function is similar to the variation function, but also returns an explanation of the evaluation that you can inspect programatically.

Here is an example:

Flag = ldclient:variation_detail(<<"my-bool-key">>, #{key => <<"aa0ceb">>}, false)

Go

The VariationDetail methods (BoolVariationDetail, etc.) work the same as Variation, but also provide additional "reason" information about how a flag value was calculated. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1value, detail, err := client.BoolVariationDetail("flag-key", myUser, false)
2// or StringVariationDetail for a string-valued flag, etc.
3
4index := detail.VariationIndex
5reason := detail.Reason
6
7// In Go SDK 5.0 and higher, detail.VariationIndex uses the type ldvalue.OptionalInt, which
8// allows an "undefined" state if evaluation failed. In earlier Go SDK versions, it is an
9// *int which is nil if evaluation failed.
COPY

To learn more, read EvaluationDetail and BoolVariationDetail.

Haskell

The variationDetail functions are similar to the variation functions, but they also return an explanation of the evaluation that is programmatically inspectable.

Here is an example:

1details :: IO (EvaluationDetail Bool)
2details = boolVariationDetail client user "YOUR_FEATURE_KEY" False
COPY

For specific information on the EvaluationDetail structure, inspect the LaunchDarkly.Server.Details module.

Java

The variationDetail methods (boolVariationDetail, etc.) work the same as variation, but also provide additional "reason" information about how a flag value was calculated. For example, you can find out if the user was individually targeted for the flag or was matched by one of the flag's rules. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1import com.launchdarkly.sdk.*;
2
3EvaluationDetail<Boolean> detail =
4  client.boolVariationDetail("flag-key", myUser, false);
5  // or stringVariationDetail for a string-valued flag, etc.
6
7boolean value = detail.getValue();
8int index = detail.getVariationIndex();       // will be < 0 if evaluation failed
9EvaluationReason reason = detail.getReason();
10
11
12// Before version 5.0, this was slightly different:
13import com.launchdarkly.client.*;
14
15EvaluationDetail<Boolean> detail =
16  client.boolVariationDetail("flag-key", myUser, false);
17
18boolean value = detail.getValue();
19Integer index = detail.getVariationIndex();
20EvaluationReason reason = detail.getReason();
COPY

To learn more, read EvaluationDetail and boolVariationDetail.

Lua

By using the *Detail family of variation calls you can programmatically inspect the reason for a particular evaluation:

1local details = client:boolVariationDetail(client, user, "your.feature.key", false);
2
3/* inspect details here */
4if details.reason == "FLAG_NOT_FOUND" then
5end
COPY

To learn more about configuration options, read the API docs.

Node.js (server-side)

The variationDetail method lets you evaluate a feature flag (using the same parameters as you would for variation) and receive more information about how the value was calculated.

The variation detail is returned in an object that contains both the result value and a "reason" object which will tell you, for instance, if the user was individually targeted for the flag or was matched by one of the flag's rules. It will also indicate if the flag returned the default value due to an error. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1var detail = client.variationDetail("flag-key", myUser, false);
2
3var value = detail.value;
4var index = detail.variationIndex;
5var reason = detail.reason;
COPY

To learn more, read LDEvaluationDetail and variationDetail.

PHP

The variationDetail method lets you evaluate a feature flag (using the same parameters as you would for variation) and receive more information about how the value was calculated.

The variation detail is returned in an object that contains both the result value and a "reason" object which will tell you, for instance, if the user was individually targeted for the flag or was matched by one of the flag's rules. It will also indicate if the flag returned the default value due to an error. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1$detail = $client->variationDetail("flag-key", $myUser, false);
2
3$value = $detail->getValue();
4$index = $detail->getVariationIndex();
5$reason = $detail->getReason();
COPY

To learn more, read EvaluationDetail and variationDetail.

Python

The variation_detail method lets you evaluate a feature flag with the same parameters as you would for variation. You can use thie method to receive more information about how the value was calculated.

The variation detail is returned in an object that contains both the result value and a "reason" object which will tell you, for instance, if the user was individually targeted for the flag or was matched by one of the flag's rules. It will also indicate if the flag returned the default value due to an error. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1detail = client.variation_detail("flag-key", my_user, False)
2value = detail.value
3index = detail.variation_index
4reason = detail.reason
COPY

To learn more, read EvaluationDetail and variation_detail.

Ruby

The variation_detail method lets you evaluate a feature flag (using the same parameters as you would for variation) and receive more information about how the value was calculated.

The variation detail is returned in an object that contains both the result value and a "reason" object which will tell you, for instance, if the user was individually targeted for the flag or was matched by one of the flag's rules. It will also indicate if the flag returned the default value due to an error. You can examine the "reason" data programmatically, or, if you capture detailed analytics events for flags, view it with Data Export.

Here is an example:

1detail = client.variation_detail("flag-key", my_user, false)
2value = detail.value
3index = detail.variation_index
4reason = detail.reason
COPY

To learn more, read EvaluationDetail and variation_detail.