FFL-1721 Emit flagevaluation EVP Track

CHANGELOG.md

@@ -1,12 +1,12 @@
 # Unreleased
 
-- [IMPROVEMENT] Skip malformed Logs attributes individually instead of dropping the entire 
-  event, and log clear error messages. See [#2665][]
+- [FEATURE] Add evaluation logging to `DatadogFlags` module. See [#2646][]
+- [IMPROVEMENT] Skip malformed Logs attributes individually instead of dropping the entire event, and log clear error messages. See [#2665][]
 
 # 3.6.1 / 02-02-2026
 
 - [FIX] Prevent crashes related to swapping the `__cxa_throw` function. See [#2661][]
-        
+
 # 3.6.0 / 28-01-2026
 
 - [FEATURE] Add `DatadogProfiling` module to profile app launches. See [#2654][]
@@ -1038,6 +1038,7 @@ Release `2.0` introduces breaking changes. Follow the [Migration Guide](MIGRATIO
 [#2633]: https://github.com/DataDog/dd-sdk-ios/pull/2633
 [#2647]: https://github.com/DataDog/dd-sdk-ios/pull/2647
 [#2640]: https://github.com/DataDog/dd-sdk-ios/pull/2640
+[#2646]: https://github.com/DataDog/dd-sdk-ios/pull/2646
 [#2639]: https://github.com/DataDog/dd-sdk-ios/pull/2639
 [#2654]: https://github.com/DataDog/dd-sdk-ios/pull/2654
 [#2665]: https://github.com/DataDog/dd-sdk-ios/pull/2665

Datadog/IntegrationUnitTests/Flags/FlagsEvaluationIntegrationTests.swift

@@ -0,0 +1,63 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import XCTest
+import TestUtilities
+import DatadogInternal
+
+@_spi(Internal)
+@testable import DatadogFlags
+
+/// Covers integration scenarios for flag evaluation logging.
+final class FlagsEvaluationIntegrationTests: XCTestCase {
+    private enum Fixtures {
+        static let flagsData = FlagsData(
+            flags: [
+                "test-flag": .init(
+                    allocationKey: "allocation-123",
+                    variationKey: "variation-123",
+                    variation: .boolean(true),
+                    reason: "TARGETING_MATCH",
+                    doLog: true
+                )
+            ],
+            context: .init(
+                targetingKey: "user-123",
+                attributes: [:]
+            ),
+            date: .mockAny()
+        )
+    }
+
+    // MARK: - EVALLOG.4: Shutdown Flush
+
+    /// EVALLOG.4: Evaluations are flushed when SDK shuts down via flushAndTearDown()
+    func testWhenSDKShutsDown_itFlushesPendingEvaluations() throws {
+        // Given
+        let core = DatadogCoreProxy(context: .mockWith(trackingConsent: .granted))
+        Flags.enable(with: .init(trackEvaluations: true), in: core)
+
+        let featureScope = core.scope(for: FlagsFeature.self)
+        featureScope.flagsDataStore.setFlagsData(Fixtures.flagsData, forClientNamed: FlagsClient.defaultName)
+        featureScope.dataStore.flush()
+
+        let client = FlagsClient.create(in: core)
+
+        // When
+        _ = client.getBooleanValue(key: "test-flag", defaultValue: false)
+
+        // Then
+        try core.flushAndTearDown()
+
+        let events = core.waitAndReturnEvents(
+            ofFeature: FlagsEvaluationFeature.name,
+            ofType: FlagEvaluationEvent.self
+        )
+
+        XCTAssertEqual(events.count, 1, "Should have flushed pending evaluations on shutdown")
+        XCTAssertEqual(events.first?.flag.key, "test-flag")
+    }
+}

DatadogFlags/Sources/Client/EvaluationAggregator.swift

@@ -0,0 +1,186 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import Foundation
+import DatadogInternal
+
+internal final class EvaluationAggregator {
+    private let flushInterval: TimeInterval
+    private let maxAggregations: Int
+    private let dateProvider: any DateProvider
+    private let featureScope: FeatureScope
+    @ReadWriteLock
+    private var aggregations: [AggregationKey: AggregatedEvaluation] = [:]
+    private var flushTimer: Timer?
+
+    init(
+        dateProvider: any DateProvider,
+        featureScope: FeatureScope,
+        flushInterval: TimeInterval,
+        maxAggregations: Int = 1_000
+    ) {
+        self.dateProvider = dateProvider
+        self.featureScope = featureScope
+        self.flushInterval = flushInterval
+        self.maxAggregations = maxAggregations
+
+        startFlushTimer()
+    }
+
+    deinit {
+        flushTimer?.invalidate()
+        // Note: We don't flush here due to exclusivity conflict with DatadogCore.stop()
+    }
+
+    func recordEvaluation(
+        for flagKey: String,
+        assignment: FlagAssignment,
+        evaluationContext: FlagsEvaluationContext,
+        flagError: String?
+    ) {
+        let errorMessage = flagError
+        let now = dateProvider.now.timeIntervalSince1970.dd.toInt64Milliseconds
+
+        let key = AggregationKey(
+            flagKey: flagKey,
+            variantKey: assignment.variationKey,
+            allocationKey: assignment.allocationKey,
+            targetingKey: evaluationContext.targetingKey,
+            errorMessage: errorMessage,
+            context: evaluationContext.attributes
+        )
+
+        var shouldFlush = false
+
+        _aggregations.mutate { aggregations in
+            if var existing = aggregations[key] {
+                existing.evaluationCount += 1
+                existing.lastEvaluation = now
+                aggregations[key] = existing
+            } else {
+                let runtimeDefaultUsed = assignment.reason == "DEFAULT" || errorMessage != nil
+
+                let aggregated = AggregatedEvaluation(
+                    flagKey: flagKey,
+                    variantKey: assignment.variationKey,
+                    allocationKey: assignment.allocationKey,
+                    targetingKey: evaluationContext.targetingKey,
+                    targetingRuleKey: nil,
+                    errorMessage: errorMessage,
+                    context: evaluationContext.attributes,
+                    firstEvaluation: now,
+                    lastEvaluation: now,
+                    evaluationCount: 1,
+                    runtimeDefaultUsed: runtimeDefaultUsed ? true : nil
+                )
+
+                aggregations[key] = aggregated
+            }
+
+            shouldFlush = aggregations.count >= self.maxAggregations
+        }
+
+        if shouldFlush {
+            sendEvaluations()
+        }
+    }
+
+    func sendEvaluations() {
+        var evaluationsToSend: [AggregatedEvaluation] = []
+
+        _aggregations.mutate { aggregations in
+            evaluationsToSend = Array(aggregations.values)
+            aggregations.removeAll()
+        }
+
+        guard !evaluationsToSend.isEmpty else {
+            return
+        }
+
+        featureScope.eventWriteContext { _, writer in
+            for aggregated in evaluationsToSend {
+                let event = aggregated.toFlagEvaluationEvent()
+                writer.write(value: event)
+            }
+        }
+    }
+
+    private func startFlushTimer() {
+        flushTimer = Timer.scheduledTimer(
+            withTimeInterval: flushInterval,
+            repeats: true
+        ) { [weak self] _ in
+            self?.sendEvaluations()
+        }
+    }
+}
+
+private struct AggregationKey: Hashable {
+    let flagKey: String
+    let variantKey: String
+    let allocationKey: String
+    let targetingKey: String
+    let errorMessage: String?
+    let contextHash: Int
+
+    init(
+        flagKey: String,
+        variantKey: String,
+        allocationKey: String,
+        targetingKey: String,
+        errorMessage: String?,
+        context: [String: AnyValue]
+    ) {
+        self.flagKey = flagKey
+        self.variantKey = variantKey
+        self.allocationKey = allocationKey
+        self.targetingKey = targetingKey
+        self.errorMessage = errorMessage
+        var hasher = Hasher()
+        for key in context.keys.sorted() {
+            hasher.combine(key)
+            hasher.combine(context[key])
+        }
+        self.contextHash = hasher.finalize()
+    }
+}
+
+private struct AggregatedEvaluation {
+    let flagKey: String
+    let variantKey: String
+    let allocationKey: String
+    let targetingKey: String
+    let targetingRuleKey: String?
+    let errorMessage: String?
+    let context: [String: AnyValue]
+
+    let firstEvaluation: Int64
+    var lastEvaluation: Int64
+    var evaluationCount: Int
+    let runtimeDefaultUsed: Bool?
+
+    func toFlagEvaluationEvent() -> FlagEvaluationEvent {
+        let eventContext: FlagEvaluationEvent.EvaluationEventContext? = context.isEmpty ? nil : .init(
+            evaluation: context,
+            dd: nil
+        )
+
+        return FlagEvaluationEvent(
+            timestamp: firstEvaluation,
+            flag: .init(key: flagKey),
+            firstEvaluation: firstEvaluation,
+            lastEvaluation: lastEvaluation,
+            evaluationCount: evaluationCount,
+            variant: runtimeDefaultUsed == true ? nil : .init(key: variantKey),
+            allocation: runtimeDefaultUsed == true ? nil : .init(key: allocationKey),
+            targetingRule: targetingRuleKey.map { .init(key: $0) },
+            targetingKey: targetingKey,
+            runtimeDefaultUsed: runtimeDefaultUsed,
+            error: errorMessage.map { .init(message: $0) },
+            context: eventContext
+        )
+    }
+}

DatadogFlags/Sources/Client/EvaluationLogger.swift

@@ -0,0 +1,50 @@
+/*
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import Foundation
+import DatadogInternal
+
+internal protocol EvaluationLogging {
+    func logEvaluation(
+        for flagKey: String,
+        assignment: FlagAssignment,
+        evaluationContext: FlagsEvaluationContext,
+        flagError: String?
+    )
+}
+
+internal final class EvaluationLogger: EvaluationLogging {
+    private let aggregator: EvaluationAggregator
+
+    init(aggregator: EvaluationAggregator) {
+        self.aggregator = aggregator
+    }
+
+    func logEvaluation(
+        for flagKey: String,
+        assignment: FlagAssignment,
+        evaluationContext: FlagsEvaluationContext,
+        flagError: String?
+    ) {
+        aggregator.recordEvaluation(
+            for: flagKey,
+            assignment: assignment,
+            evaluationContext: evaluationContext,
+            flagError: flagError
+        )
+    }
+}
+
+internal final class NOPEvaluationLogger: EvaluationLogging {
+    func logEvaluation(
+        for flagKey: String,
+        assignment: FlagAssignment,
+        evaluationContext: FlagsEvaluationContext,
+        flagError: String?
+    ) {
+        // No-op
+    }
+}