Flag evaluation reasons: Server-side SDKs

This topic explains how to use the flag evaluation reason feature to get more information about the flag variations LaunchDarkly serves to contexts or users. This page covers server-side sdks.

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 (server-side)
• Apex
• C++ (server-side)
• Erlang
• Go
• Haskell
• Java
• Lua
• Node.js (server-side)
• PHP
• Python
• Ruby
• Rust

.NET (server-side)

Expand .NET (server-side) code sample

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 context 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:

.NET SDK v7.0 (C#)

      EvaluationDetail<bool> detail =
          client.BoolVariationDetail("example-flag-key", myContext, false);
          // or StringVariationDetail for a string-valued flag, etc.

      bool value = detail.Value;
      int? index = detail.VariationIndex;
      EvaluationReason reason = detail.Reason;

To learn more, read EvaluationDetail, BoolVariationDetail.

Here is an example of how to access the details of a reason object:

C#

      void PrintReason(EvaluationReason reason)
      {
        switch (reason.Kind)
        {
          case EvaluationReasonKind.OFF:
            Console.WriteLine("it's off");
            break;
          case EvaluationReasonKind.FALLTHROUGH:
            Console.WriteLine("fell through");
            break;
          case EvaluationReasonKind.TARGET_MATCH:
            Console.WriteLine("targeted");
            break;
          case EvaluationReasonKind.RULE_MATCH:
            var rm = reason as EvaluationReason.RuleMatch;
            Console.WriteLine("matched rule " + rm.RuleIndex + "/" + rm.RuleID);
            break;
          case EvaluationReasonKind.PREREQUISITE_FAILED:
            var pf = reason as EvaluationReason.PrerequisiteFailed;
            Console.WriteLine("prereq failed: " + pf.PrerequisiteKey);
            break;
          case EvaluationReasonKind.ERROR:
            var e = reason as EvaluationReason.Error;
            Console.WriteLine("error: " + e.ErrorKind);
            break;
        }
        // or, if all you want is a simple descriptive string:
        System.out.println(reason.ToString());
      }

To learn more, read EvaluationReason.

Apex

Expand Apex code sample

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

Here is an example:

Apex

      LDClient.EvaluationDetail details = new LDClient.EvaluationDetail();

      Boolean value = client.boolVariation(user, 'your.feature.key', false, details);

      /* inspect details here */
      if (details.getReason().getKind() == EvaluationReason.Kind.OFF) {
          /* ... */
      }

C++ (server-side)

Expand C++ (server-side) code sample

You can request and then programmatically inspect the reason for a particular feature flag evaluation.

The detail.Reason() response is described in Evaluation reasons.

Here is an example:

C++ SDK v3.0 (native)

      auto detail = client.BoolVariationDetail(context, "example-flag-key", false);
      if (detail.Value()) {
        std::cout << "Value was true!" << std::endl;
      } else {
        // it was false, let's find out why
        if (auto reason = detail.Reason(); reason.has_value()) {
          // reason might not be present, so we have to check
          std::cout << "Value was false because of " << reason.value() << std::endl;
        } else {
          std::cout << "No reason provided to explain why flag was false!" << std::endl;
        }
      }

To learn more, read EvaluationDetail.

Erlang

Expand Erlang code sample

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

Here is an example:

SDK v2.0+"

      Flag = ldclient:variation_detail(<<"example-flag-key">>, #{key => <<"example-context-key">>}, false)

Go

Expand Go code sample

The VariationDetail methods, such as BoolVariationDetail, work the same way as Variation, but also provide additional “reason” information about how a flag value was calculated. For example, you can find out if the context was individually targeted by 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:

Go SDK v7.13.4+, using LDScopedClient

      value, detail, err := scopedClient.BoolVariationDetail("example-flag-key", false)
      // or StringVariationDetail for a string-valued flag, etc.
      // LDScopedClient is in beta and may change without notice.

      index := detail.VariationIndex
      reason := detail.Reason

To learn more, read EvaluationDetail and BoolVariationDetail.

Here is an example of how to access the details of a reason object:

Go SDK v6+

      import (
          "github.com/launchdarkly/go-sdk-common/v3/ldreason"
      )

      func PrintReason(reason ldreason.EvaluationReason) {
        switch reason.GetKind() {
        case ldreason.EvalReasonOff:
          fmt.Println("it's off")
        case ldreason.EvalReasonFallthrough:
          fmt.Println("fell through")
        case ldreason.EvalReasonTargetMatch:
          fmt.Println("targeted")
        case ldreason.EvalReasonRuleMatch:
          fmt.Printf("matched rule %d/%s\n", r.GetRuleIndex(), r.GetRuleID())
        case ldreason.EvalReasonPrerequisiteFailed:
          fmt.Printf("prereq failed: %s\n", r.GetPrerequisiteKey())
        case ldreason.EvalReasonError:
          fmt.Printf("error: %s\n", r.GetErrorKind())
        }
        // or, if all you want is a simple descriptive string:
        fmt.Println(reason)
      }

To learn more, read EvaluationReason.

If you are using OpenTelemetry, then instead of using the VariationDetail method for each type, you must use the VariationDetailCtx method for each type. For example, use BoolVariationDetailCtx rather than BoolVariationDetail. The methods are the same except that the VariationDetailCtx methods also require a Go context parameter. This Go context is used in the hook implementation that provides OpenTelemetry support. To learn more, read OpenTelemetry.

Haskell

Expand Haskell code sample

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:

Haskell SDK v4.0

      details :: IO (EvaluationDetail Bool)
      details = boolVariationDetail client "example-flag-key" context False

To learn more, read EvaluationDetail and boolVariationDetail.

Java

Expand Java code sample

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 context 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:

Java SDK v6.0

      import com.launchdarkly.sdk.*;

      EvaluationDetail<Boolean> detail =
        client.boolVariationDetail("example-flag-key", context, false);
        // or stringVariationDetail for a string-valued flag, and so on.

      boolean value = detail.getValue();
      int index = detail.getVariationIndex();       // will be < 0 if evaluation failed
      EvaluationReason reason = detail.getReason();

To learn more, read EvaluationDetail and boolVariationDetail.

Here is an example of how to access the details of a reason object:

Java

      void printReason(EvaluationReason reason) {
        switch (reason.getKind()) {
          case OFF:
            System.out.println("it's off");
            break;
          case FALLTHROUGH:
            System.out.println("fell through");
            break;
          case TARGET_MATCH:
            System.out.println("targeted");
            break;
          case RULE_MATCH:
            EvaluationReason.RuleMatch rm = (EvaluationReason.RuleMatch)reason;
            System.out.println("matched rule " + rm.getRuleIndex()
              + "/" + rm.getRuleId());
            break;
          case PREREQUISITE_FAILED:
            EvaluationReason.PrerequisiteFailed pf =
              (EvaluationReason.PrerequisiteFailed)reason;
            System.out.println("prereq failed: " + pf.getPrerequisiteKey());
            break;
          case ERROR:
            EvaluationReason.Error e = (EvaluationReason.Error)reason;
            System.out.println("error: " + e.getErrorKind());
        }
        // or, if all you want is a simple descriptive string:
        System.out.println(reason.toString());
      }

To learn more, read EvaluationReason.

Lua

Expand Lua code sample

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

Lua SDK v2

      local details = client:boolVariationDetail(client, context, "example-flag-key", false);

      -- inspect details here
      if details.reason == "FLAG_NOT_FOUND" then
      end

To learn more, read boolVariationDetail.

Node.js (server-side)

Expand Node.js (server-side) code sample

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 context 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:

Node.js SDK v7.x and later (JavaScript)

      var detail = client.variationDetail('example-flag-key', context, false);

      var value = detail.value;
      var index = detail.variationIndex;
      var reason = detail.reason;

To learn more, read LDEvaluationDetail and variationDetail.

Here is an example of how to access the details of a reason object:

JavaScript

      function printReason(reason) {
        switch(reason.kind) {
          case "OFF":
            console.log("it's off");
            break;
          case "FALLTHROUGH":
            console.log("fell through");
            break;
          case "TARGET_MATCH":
            console.log("targeted");
            break;
          case "RULE_MATCH":
            console.log("matched rule " + reason.ruleIndex + ", "  + reason.ruleId);
            break;
          case "PREREQUISITE_FAILED":
            console.log("prereq failed: " + reason.prerequisiteKey);
            break;
          case "ERROR":
            console.log("error: " + reason.errorKind);
            break;
        }
      }

To learn more, read LDEvaluationReason.

PHP

Expand PHP code sample

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 example, if the context 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:

PHP SDK v5.0

      $detail = $client->variationDetail("example-flag-key", $myContext, false);

      $value = $detail->getValue();
      $index = $detail->getVariationIndex();
      $reason = $detail->getReason();

To learn more, read EvaluationDetail and variationDetail.

Here is an example of how to access the details of a reason object:

PHP SDK v5.0 and earlier

      function printReason($reason) {
        switch ($reason->getKind()) {
          case EvaluationReason::OFF:
            echo("it's off");
            break;
          case EvaluationReason::FALLTHROUGH:
            echo("fell through");
            break;
          case EvaluationReason::TARGET_MATCH:
            echo("targeted");
            break;
          case EvaluationReason::RULE_MATCH:
            echo("matched rule " . $reason->getRuleIndex() .
              "/" . $reason->getRuleId());
            break;
          case EvaluationReason::PREREQUISITE_FAILED:
            echo("prereq failed: " . $reason->getPrerequisiteKey());
            break;
          case EvaluationReason::ERROR:
            echo("error: " . $reason->getErrorKind());
            break;
        }
        // or, if all you want is a simple descriptive string:
        echo $reason;
      }

To learn more, read EvaluationReason.

Python

Expand Python code sample

The variation_detail method lets you evaluate a feature flag with the same parameters as you would for variation. You can use this 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 context 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:

Python SDK v8.0

      detail = client.variation_detail("example-flag-key", my_context, False)
      value = detail.value
      index = detail.variation_index
      reason = detail.reason

To learn more, read EvaluationDetail and variation_detail.

Here is an example of how to access the details of a reason object:

Python

      def print_reason(reason):
        kind = reason["kind"]
        if kind == "OFF":
          print "it's off"
        elif kind == "FALLTHROUGH":
          print "fell through"
        elif kind == "TARGET_MATCH":
          print "targeted"
        elif kind == "RULE_MATCH":
          print "matched rule %d/%s" % (reason["ruleIndex"], reason["ruleId"])
        elif kind == "PREREQUISITE_FAILED":
          print "prereq failed: %s" % reason["prerequisiteKey"]
        elif kind == "ERROR":
          print "error: %s" % reason["errorKind"]

To learn more, read EvaluationDetail.reason.

Ruby

Expand Ruby code sample

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 context 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:

Ruby SDK v7.0

      detail = client.variation_detail("example-flag-key", my_context, false)
      value = detail.value
      index = detail.variation_index
      reason = detail.reason

To learn more, read EvaluationDetail and variation_detail.

Here is an example of how to access the details of a reason object:

Ruby

      def print_reason(reason)
        case reason[:kind]
        when "OFF"
          puts "it's off"
        when "FALLTHROUGH"
          puts "fell through"
        when "TARGET_MATCH"
          puts "targeted"
        when "RULE_MATCH"
          puts "matched rule #{reason[:ruleIndex]}/#{reason[:ruleId]}"
        when "PREREQUISITE_FAILED"
          puts "prereq failed: #{reason[:prerequisiteKey]}"
        when "ERROR"
          puts "error: #{reason[:errorKind]}"
        end
      end

To learn more, read EvaluationDetail.reason.

Rust

Expand Rust code sample

The variation_detail methods (for example, bool_variation_detail) let you evaluate a feature flag, using the same parameters as you would for variation, and receive more information about how the flag value was calculated. For example, you can find out if the context 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:

Rust SDK v1

      let detail = client.bool_variation_detail(&context, "example-flag-key", false);

      let value = detail.value;
      let index = detail.variation_index;
      let reason = detail.reason;

To learn more, read variation_detail and bool_variation_detail.

Here is an example of how to access the details of a reason object:

Rust SDK v1

      fn print_reason(reason: Reason) {
          match reason {
              Reason::Off => println!("it's off"),
              Reason::Fallthrough { .. } => println!("fell through"),
              Reason::TargetMatch => println!("targeted"),
              Reason::RuleMatch {
                  rule_index,
                  rule_id,
                  ..
              } => println!("matched rule {}/{}", rule_index, rule_id),
              Reason::PrerequisiteFailed { prerequisite_key } => {
                  println!("prereq failed: {}", prerequisite_key)
              }
              Reason::Error { error } => println!("error: {:?}", error),
          };
      }

To learn more, read Reason.