feat: context management by typotter · Pull Request #2886 · DataDog/dd-sdk-android

typotter · 2025-09-18T04:59:36Z

Feature Flags Evaluat Context Implementation

What does this PR do?

Implements synchronous evaluation context management for feature flag evaluation, inclusion in precompute-assignments request, for exposure logging via in-memory storage and enrichment from the SDK core.

This establishes the foundation for feature flag targeting by allowing developers to set evaluation context that gets automatically enhanced with device, app, and user data from the Datadog SDK core.

Context, Targeting Data, Attributes; these are all words that mean the set of properties the flag evaluation system can use to determine the effective value of a flag for a particular user or subject (or context). The targetingKey is the pillar of the evaluation context, impacting both targeting rules and the selection of traffic for Experiments (such as an A/B test). An inconsistent targetingKey for a user leads to inconsistent bucketing.

Motivation

The feature flags implementation needs context management to:

Enable proper flag targeting based on user/device attributes
Pull context data from existing Datadog SDK infrastructure
Provide a developer-friendly API following Kotlin best practices
Include context information in network requests for precomputed flag evaluation
Prepare the foundation for future atomic configuration management

How to navigate this PR

How to Navigate This PR

🎯 Start Here - Core API Changes

FlagsProvider.kt - See the new setContext(targetingKey, attributes) API
FlagsConfiguration.kt - New useDatadogContextForEvaluations option
EvaluationContext.kt - New Kotlin DSL for context creation

🏗️ Architecture Overview

FlagsContextManager.kt - Central context management with SDK core integration
DefaultFlagsRepository.kt - Context storage and network coordination
DefaultFlagsNetworkManager.kt - Context inclusion in network requests

🧪 Understanding Through Tests

EvaluationContextTest.kt - See the new DSL syntax examples
FlagsContextIntegrationTest.kt - End-to-end context flow
FlagsContextManagerTest.kt - SDK core integration examples

💡 Understanding the Flow

Start at: DatadogFlagsProvider.setContext() (line 37)
Follow to: DefaultFlagsRepository.updateContext() (line 53)
See enhancement: FlagsContextManager.enhanceWithCoreContext() (line 100+)
Network inclusion: DefaultFlagsNetworkManager.buildRequestBody() (line 178+)

Usage Examples

Basic Context Setting

val provider = FlagsClient.get()

provider.setContext("user123", mapOf(
        "region" to "us-east",
        "tier" to "gold",
        "beta" to true
    ))

val enabled = provider.resolveBooleanValue("new-feature", false)

SDK Core Integration

// Automatically enhanced with:
// - device.type, device.brand, device.model, device.architecture
// - app.version, app.build, env, service, version
// - user.id, user.name, user.email, user.* (additional properties)

jonathanmos · 2025-09-18T12:20:53Z

+        }
+
+        internal fun build(
+            site: String,


Users will get these parameters from here or from datadogContext?

jonathanmos · 2025-09-18T12:26:24Z

+        updatedAttributes[key] = value
+        setContext(currentContext.targetingKey, updatedAttributes)
+    } else {
+        throw IllegalStateException(


Do we want to throw an exception here?

ncreated · 2025-09-19T11:45:15Z

+            context.targetingAttributes.forEach { (key, value) ->
+                when (value) {
+                    is String -> attributesJson.put(key, value)
+                    is Number -> attributesJson.put(key, value)
+                    is Boolean -> attributesJson.put(key, value)
+                    is Collection<*> -> {
+                        // Handle arrays/lists by converting to JSON array
+                        val jsonArray = org.json.JSONArray(value)
+                        attributesJson.put(key, jsonArray)
+                    }
+                    is Map<*, *> -> {
+                        // Handle nested objects
+                        val jsonObject = JSONObject(value as Map<String, Any>)
+                        attributesJson.put(key, jsonObject)
+                    }
+                    else -> attributesJson.put(key, value.toString())
+                }
+            }


question/ It looks like we allow multiple data types in targeting_attributes, but the endpoint spec defines them as Map<String, String>:

targeting_attributes: type: object description: Key/value attributes for subject targeting. additionalProperties: type: string example: attr1: value1 companyId: "1"

The js-client stringifies targeting_attributes, and @sameerank did the same in the Swift client here.

To better support this in a typed language like Swift, we decided to require a [String: String] map in the EvaluationContext API. This could be relaxed later (by stringifying various types internally), but the plan is to handle that in future iterations.

Just double-checking here—this implementation doesn’t seem consistent with the spec. Is that intentional?

not intentional - got carried away a bit; have fixed!

codecov-commenter · 2025-09-21T03:55:54Z

Codecov Report

❌ Patch coverage is 41.33858% with 149 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.50%. Comparing base (ccf1684) to head (d8c2c35).
⚠️ Report is 322 commits behind head on feature/feature-flagging.

Files with missing lines	Patch %	Lines
...ernal/repository/net/DefaultFlagsNetworkManager.kt	0.00%	49 Missing ⚠️
...ureflags/internal/evaluation/EvaluationsManager.kt	23.26%	33 Missing ⚠️
...eflags/internal/repository/net/PrecomputeMapper.kt	3.12%	31 Missing ⚠️
...lags/internal/repository/DefaultFlagsRepository.kt	12.00%	22 Missing ⚠️
...reflags/internal/repository/net/EndpointsHelper.kt	79.31%	5 Missing and 1 partial ⚠️
.../datadog/android/flags/featureflags/FlagsClient.kt	68.75%	2 Missing and 3 partials ⚠️
...d/flags/featureflags/internal/NoOpFlagsProvider.kt	83.33%	1 Missing ⚠️
...droid/flags/featureflags/model/FeatureFlagsUser.kt	0.00%	1 Missing ⚠️
...ndroid/flags/featureflags/model/ProviderContext.kt	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                     Coverage Diff                      @@
##           feature/feature-flagging    #2886      +/-   ##
============================================================
- Coverage                     70.60%   70.50%   -0.09%     
============================================================
  Files                           827      828       +1     
  Lines                         30069    30123      +54     
  Branches                       5007     5012       +5     
============================================================
+ Hits                          21228    21238      +10     
- Misses                         7470     7505      +35     
- Partials                       1371     1380       +9

Files with missing lines	Coverage Δ
...src/main/kotlin/com/datadog/android/flags/Flags.kt	`86.49% <100.00%> (-0.36%)`	⬇️
...in/com/datadog/android/flags/FlagsConfiguration.kt	`100.00% <100.00%> (ø)`
...lags/featureflags/internal/DatadogFlagsProvider.kt	`89.80% <100.00%> (+9.15%)`	⬆️
.../flags/featureflags/internal/model/FlagsContext.kt	`100.00% <100.00%> (ø)`
...roid/flags/featureflags/model/EvaluationContext.kt	`100.00% <100.00%> (ø)`
...com/datadog/android/flags/internal/FlagsFeature.kt	`42.86% <100.00%> (-7.14%)`	⬇️
...d/flags/featureflags/internal/NoOpFlagsProvider.kt	`85.71% <83.33%> (ø)`
...droid/flags/featureflags/model/FeatureFlagsUser.kt	`0.00% <0.00%> (-100.00%)`	⬇️
...ndroid/flags/featureflags/model/ProviderContext.kt	`0.00% <0.00%> (-100.00%)`	⬇️
.../datadog/android/flags/featureflags/FlagsClient.kt	`74.19% <68.75%> (+4.50%)`	⬆️
... and 5 more

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

0xnm · 2025-09-23T08:09:53Z

+data class com.datadog.android.flags.featureflags.model.EvaluationContext
+  constructor(String, Map<String, Any> = emptyMap())
+  class Builder
+    constructor(String, com.datadog.android.api.InternalLogger)
+    fun addAttribute(String, String): Builder
+    fun addAttribute(String, Number): Builder
+    fun addAttribute(String, Boolean): Builder
+    fun addAttribute(String, Any): Builder
+    fun addAll(Map<String, Any>): Builder
+    fun build(): EvaluationContext
+  companion object 
+    fun builder(String, com.datadog.android.api.InternalLogger)


We shouldn't expose InternalLogger in the public API, it is not supposed to be used by the customer.

Is this class EvaluationContext should be internal and made public by mistake?

The EvaluationContext is going to be an external model, so I've split it out now, with an internal model where we can do validation/filtering.

0xnm · 2025-09-23T08:10:47Z

@@ -9,12 +9,24 @@ object com.datadog.android.flags.featureflags.FlagsClient
  fun isRegistered(com.datadog.android.api.SdkCore = Datadog.getInstance()): Boolean
  fun get(com.datadog.android.api.SdkCore = Datadog.getInstance()): FlagsProvider
 interface com.datadog.android.flags.featureflags.FlagsProvider


What is the reason to have flags.featureflags in the package name? Shouldn't it be only flags or featureflags? Using both seems redundant.

I do agree we need to settle on a single name here. I think flags is sufficient. Because we're two working on a lot of the same files right now, we'll make this rename in this feature branch in an independent pr

0xnm · 2025-09-23T08:12:16Z

    /**
     * Set the context for the provider.
-     * @param newContext The new context to use for the provider.
+     * @param targetingKey The targeting key to use for flag evaluation.


We probably need better documentation for that, it is not clear what is targetingKey by looking just on the javadoc.

Have filled out the docs on the EvaluationContext for targetingKey and have updated the signature here.

0xnm · 2025-09-23T08:13:35Z

+     * @param attributes The attributes to use for targeting.
     */
-    fun setContext(newContext: ProviderContext)
+    fun setContext(targetingKey: String, attributes: Map<String, Any>)


Usually the type of attributes (at least in RUM and Logs) is Map<String, Any?> (allowing nullable value). Is there a reason for using non-nullable value type?

We don't have targeting for null attributes at this time, but it's possible we will in the future. I've refactored the EvaluationContext to an internal and external model where the former will carry only the attributes supported by the flagging system and the external model is more freeform and doesn't use the internal logger

0xnm · 2025-09-23T08:14:10Z

            )
        }
+
+        // Create orchestrator with network manager and dependencies


nit: no need to have comments like that, they don't add any value

0xnm · 2025-09-23T08:32:09Z

+        verify(mockInternalLogger, times(3)).log(
+            eq(InternalLogger.Level.WARN),
+            eq(InternalLogger.Target.USER),
+            any(),
+            eq(null),
+            eq(false),
+            eq(null)
+        )


We are checking only logging and we don't check that we have proper attributes as a result of filtering.

If underlying code will filter out valid attributes and keep invalid, this test will still pass.

You need to assert that only validAttributes are kept.

this test is moved to DatadogEvaluationContextTest

0xnm · 2025-09-23T08:32:49Z

+
+        // Then
+        // Should complete without errors and not log any warnings
+        verify(mockInternalLogger, times(0)).log(


same: we check only logging here, but not checking that attributes didn't make it.

0xnm · 2025-09-23T08:34:48Z

+    @Test
+    fun `M create context W constructor() { targeting key and attributes }`(forge: Forge) {
+        // Given
+        val fakeTargetingKey = forge.anAlphabeticalString()
+        val fakeAttributes = mapOf(
+            "plan" to forge.anAlphabeticalString(),
+            "user_id" to forge.anInt()
+        )
+
+        // When
+        val context = EvaluationContext(fakeTargetingKey, fakeAttributes)
+
+        // Then
+        assertThat(context.targetingKey).isEqualTo(fakeTargetingKey)
+        assertThat(context.attributes).isEqualTo(fakeAttributes)
+    }


is this test useful?

not particularly, I suppose

0xnm · 2025-09-23T08:35:11Z

+    @BeforeEach
+    fun `set up`(forge: Forge) {
+        ForgeConfigurator.configure(forge)
+    }


this can be replace by @ForgeConfiguration(ForgeConfigurator::class) annotation on the class

🧑‍🍳 thanks. much cleaner!

0xnm · 2025-09-23T08:36:21Z

+        verify(mockInternalLogger, times(0)).log(
+            any<InternalLogger.Level>(),
+            any<InternalLogger.Target>(),
+            any<() -> String>(),
+            any(),
+            any(),
+            any()
+        )


verifyNoInteractions(mockInternalLogger), same for similar blocks below

typotter

Thank you for the thoughtful review, @0xnm
I've a WIP drat PR #2896 to address these. It's too late in my day to quite get #2896 ready for review, but it is most of the way.

typotter · 2025-09-25T05:25:58Z

+    @BeforeEach
+    fun `set up`(forge: Forge) {
+        ForgeConfigurator.configure(forge)
+    }


🧑‍🍳 thanks. much cleaner!

typotter · 2025-09-25T05:26:23Z

+data class com.datadog.android.flags.featureflags.model.EvaluationContext
+  constructor(String, Map<String, Any> = emptyMap())
+  class Builder
+    constructor(String, com.datadog.android.api.InternalLogger)
+    fun addAttribute(String, String): Builder
+    fun addAttribute(String, Number): Builder
+    fun addAttribute(String, Boolean): Builder
+    fun addAttribute(String, Any): Builder
+    fun addAll(Map<String, Any>): Builder
+    fun build(): EvaluationContext
+  companion object 
+    fun builder(String, com.datadog.android.api.InternalLogger)


The EvaluationContext is going to be an external model, so I've split it out now, with an internal model where we can do validation/filtering.

typotter · 2025-09-25T05:31:06Z

    /**
     * Set the context for the provider.
-     * @param newContext The new context to use for the provider.
+     * @param targetingKey The targeting key to use for flag evaluation.


Have filled out the docs on the EvaluationContext for targetingKey and have updated the signature here.

typotter · 2025-09-25T06:28:35Z

+        verify(mockInternalLogger, times(0)).log(
+            any<InternalLogger.Level>(),
+            any<InternalLogger.Target>(),
+            any<() -> String>(),
+            any(),
+            any(),
+            any()
+        )


typotter · 2025-09-25T06:29:07Z

+    @Test
+    fun `M create context W constructor() { targeting key and attributes }`(forge: Forge) {
+        // Given
+        val fakeTargetingKey = forge.anAlphabeticalString()
+        val fakeAttributes = mapOf(
+            "plan" to forge.anAlphabeticalString(),
+            "user_id" to forge.anInt()
+        )
+
+        // When
+        val context = EvaluationContext(fakeTargetingKey, fakeAttributes)
+
+        // Then
+        assertThat(context.targetingKey).isEqualTo(fakeTargetingKey)
+        assertThat(context.attributes).isEqualTo(fakeAttributes)
+    }


not particularly, I suppose

typotter · 2025-09-25T07:17:10Z

+
+        // Then
+        // Should complete without errors and not log any warnings
+        verify(mockInternalLogger, times(0)).log(


typotter · 2025-09-25T07:19:10Z

@@ -9,12 +9,24 @@ object com.datadog.android.flags.featureflags.FlagsClient
  fun isRegistered(com.datadog.android.api.SdkCore = Datadog.getInstance()): Boolean
  fun get(com.datadog.android.api.SdkCore = Datadog.getInstance()): FlagsProvider
 interface com.datadog.android.flags.featureflags.FlagsProvider


I do agree we need to settle on a single name here. I think flags is sufficient. Because we're two working on a lot of the same files right now, we'll make this rename in this feature branch in an independent pr

typotter · 2025-09-25T07:19:33Z

            )
        }
+
+        // Create orchestrator with network manager and dependencies


typotter · 2025-09-25T07:32:16Z

+
+            // Pass to orchestrator to handle network request and atomic storage
+            flagsOrchestrator.updateEvaluationsForContext(evaluationContext)
+        } catch (e: IllegalArgumentException) {


I've shifted around the validation here to avoid the exception, thank you

typotter · 2025-09-25T07:33:46Z

+        // Since orchestrator runs async, we can't directly verify the EvaluationContext
+        // But we can verify that the method completes without throwing


hoisted the evaluations manager so we can mock it; makes this a lot less awkward

typotter requested a review from jonathanmos September 18, 2025 05:11

jonathanmos reviewed Sep 18, 2025

View reviewed changes

ncreated reviewed Sep 19, 2025

View reviewed changes

Feature Flags context revamp

d8c2c35

typotter force-pushed the typo/ff-context branch from 5601928 to d8c2c35 Compare September 21, 2025 03:24

jonathanmos approved these changes Sep 22, 2025

View reviewed changes

typotter marked this pull request as ready for review September 22, 2025 17:04

typotter requested review from a team as code owners September 22, 2025 17:04

typotter merged commit 853fd91 into feature/feature-flagging Sep 22, 2025
25 checks passed

typotter deleted the typo/ff-context branch September 22, 2025 17:04

0xnm reviewed Sep 23, 2025

View reviewed changes

typotter mentioned this pull request Sep 25, 2025

fix and improve tests, context management #2896

Merged

3 tasks

typotter commented Sep 25, 2025

View reviewed changes

This was referenced Nov 4, 2025

Flags Feature #2979

Closed

Flags Feature #2982

Merged

		// Since orchestrator runs async, we can't directly verify the EvaluationContext
		// But we can verify that the method completes without throwing

Uh oh!

Conversation

typotter commented Sep 18, 2025

Feature Flags Evaluat Context Implementation

What does this PR do?

Motivation

How to navigate this PR

How to Navigate This PR

🎯 Start Here - Core API Changes

🏗️ Architecture Overview

🧪 Understanding Through Tests

💡 Understanding the Flow

Usage Examples

Basic Context Setting

SDK Core Integration

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

typotter left a comment

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Sep 21, 2025 •

edited

Loading