How to view contexts that were served a feature flag

Affected: All SDKs

Overview

Understanding which contexts (such as users or other entities) have received specific variations of a feature flag is vital for feature analysis, troubleshooting, rollouts, and Experimentation. Common questions include:

• Which contexts received a specific variation of a flag?
• How can I verify if a certain user saw a feature during a rollout?
• Can I export flag evaluation data for external analysis?

By default, LaunchDarkly only retains aggregated evaluation metrics and does not provide historical flag evaluation data tied to individual contexts in the dashboard or REST API. However, several approaches can help you collect or analyze this information.

Solution

You can leverage the following methods to track, view, or export the relationship between contexts and served flag variations:

1. Use Data Export Integrations

If your plan includes the Data Export add-on, you can configure LaunchDarkly to stream detailed feature event data to external destinations, such as Amazon Kinesis, Azure Event Hubs, Google Cloud Pub/Sub, mParticle, Segment, or Snowflake.

Data captured includes:

• Flag key
• Variation served
• Timestamp
• Associated context keys (such as userKey or context key)
• Evaluation reason ("reason" object)

Example: Exported event

{
  "project": "62fxxxxxxxxxxxxxx",
  "environment": "62fxxxxxxxxxxxx",
  "event": {
    "kind": "feature",
    "id": "63843c40xxxxxxxxxxxx",
    "userKey": "{USER-KEY}",
    "creationDate": 1669610559830,
    "key": "{FLAG-KEY}",
    "value": "{VARIATION-VALUE}",
    "default": false,
    "version": 3,
    "variation": 1,
    "variationName": "{NAME-OF-VARIATION}",
    "reason": {
      "kind": "RULE_MATCH",
      "ruleIndex": 0,
      "ruleId": "d5b69278-8b6e-XXXX-XXXXXXXXXXX"
    }
  },
  "version": 1
}

2. Track Evaluation Details Programmatically Using SDK Methods

All major LaunchDarkly SDKs offer an evaluation reason method (variationDetail()), which provides:

• The served flag variation
• The variation index
• An evaluation reason object indicating why the variation was selected (ex. rule match, fallthrough, error)

Example: LDEvaluationDetail object

detail = {
 "value": True,                 # The served variation
 "variation_index": 0,          # Index (e.g., 0 for first variation)
 "reason": {
   "kind": "RULE_MATCH",        # Why this variation was served
   "ruleIndex": 0,
   "ruleId": [ruleId],
   "inExperiment": True
 }
}

You can use this information in your application to log or export custom records of flag evaluations with both the context and variation. For example, in a server-side SDK, inspecting the LDEvaluationDetail object allows you to capture and record which variation a particular context received, along with the reason.

3. Audit Evaluations Using the REST API

Note: This approach gives a snapshot of current evaluations, not historic records. For full evaluation events, we recommend using Data Export.

If you want to audit current flag variations for all your contexts, you can script calls using the LaunchDarkly REST API:

• Search for all contexts in a given project/environment:

  curl -i -X POST \
    'https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/contexts/search' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json'

  • Evaluate a flag for each context using the /flags/evaluate endpoint.

  curl -i -X POST \
    'https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/flags/evaluate' \
    -H 'Authorization: YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "key": "context-key-123abc",
      "kind": "user"
    }'

  • For each context, parse out the variation value and keep a mapping for further analysis.

Resources

• Data Export
• Evaluation reasons
• LaunchDarkly REST API