diff --git a/dd-openfeature/README.md b/dd-openfeature/README.md
index e5cc8751b8d..cf23df8f97a 100644
--- a/dd-openfeature/README.md
+++ b/dd-openfeature/README.md
@@ -54,6 +54,8 @@ Settings are read from the Datadog Java agent configuration when attached, then
| `DD_FEATURE_FLAGS_EXPOSURES_DATADOG_LOGGING_ENABLED` | `true` | Sends exposures to Datadog. See [Stop sending exposures to Datadog](#stop-sending-exposures-to-datadog). |
| `DD_FEATURE_FLAGS_EXPERIMENTATION_OPT_OUT_MODE` | `disabled` | Controls per-subject experimentation opt-out: `disabled`, `immediate`, or `future_experiments_only`. See [Per-subject experimentation opt-out](#per-subject-experimentation-opt-out). |
| `DD_FEATURE_FLAGS_EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED` | `false` | Lets the `dd_evaluation_telemetry_opt_out` context attribute opt subjects out of evaluation telemetry. See [Per-subject evaluation telemetry opt-out](#per-subject-evaluation-telemetry-opt-out). |
+| `DD_FEATURE_FLAGS_EVALUATION_METADATA_TABLE_SIZE` | `1024` | Slots of the table that lets evaluations resolving the same split in the same millisecond share their flag metadata, rounded up to a power of two (at most 65536). `0` builds the metadata of every evaluation. |
+| `DD_FEATURE_FLAGS_EVALUATION_METADATA_TIME_BUCKET_MS` | `10` | Width, in milliseconds, of the time bucket in which evaluations of the same split share their flag metadata (at most 10000). The `first_evaluation` and `last_evaluation` times of flag evaluation events can then be up to the width minus one millisecond early; `1` keeps them exact. `0` leaves the time out of the shared metadata, and the evaluation events use the time their hook runs. |
| `DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED` | `false` | Adds flag evaluations to the local root span. Requires `dd-java-agent`. |
| `DD_API_KEY`, `DD_SITE`, `DD_ENV`, `DD_SERVICE`, `DD_VERSION` | | Credentials and event context. |
| `DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED` | | Deprecated: `true` selects `remote_config`, `false` disables Feature Flags. An explicit source wins. |
diff --git a/dd-openfeature/src/jmh/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTableBenchmark.java b/dd-openfeature/src/jmh/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTableBenchmark.java
new file mode 100644
index 00000000000..6c80256b186
--- /dev/null
+++ b/dd-openfeature/src/jmh/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTableBenchmark.java
@@ -0,0 +1,271 @@
+package com.datadog.openfeature.internal.evaluation;
+
+import static com.datadog.openfeature.internal.evaluation.MetadataKeys.EVAL_TIMESTAMP_MS;
+import static java.util.concurrent.TimeUnit.NANOSECONDS;
+import static java.util.concurrent.TimeUnit.SECONDS;
+
+import com.datadog.openfeature.ExperimentationOptOutMode;
+import com.datadog.openfeature.internal.ufc.ServerConfiguration;
+import com.datadog.openfeature.internal.ufc.UniversalFlagConfigParser;
+import de.thetaphi.forbiddenapis.SuppressForbidden;
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.ImmutableContext;
+import dev.openfeature.sdk.ProviderEvaluation;
+import dev.openfeature.sdk.Value;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Locale;
+import java.util.SplittableRandom;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.LongAdder;
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Fork;
+import org.openjdk.jmh.annotations.Level;
+import org.openjdk.jmh.annotations.Measurement;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Param;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.TearDown;
+import org.openjdk.jmh.annotations.Warmup;
+import org.openjdk.jmh.infra.Blackhole;
+
+/**
+ * Requests that each evaluate {@code flagsPerRequest} flags drawn from 1,000 enabled flags of the
+ * 10,000-flag scale configuration ({@code evaluation-suites/scale}), for a subject and cohort that
+ * change on every request, on threads sharing one evaluator. It sweeps the evaluation metadata
+ * table size and time bucket width. {@code tableSize=0} builds the metadata of every evaluation, as
+ * without the table; {@code timeBucketMs=0} leaves the timestamp out of the metadata.
+ *
+ *
{@code popularity=uniform} draws each flag of a request uniformly; {@code skewed} draws it
+ * from a Zipf distribution with exponent 1, so a few flags take most evaluations. An operation is
+ * one request, sampled for its mean and percentiles. Each measurement iteration prints the table's
+ * hit rate, the share of successful evaluations that reused metadata, and how early the reported
+ * {@code __dd_eval_timestamp_ms} was: the clock just before the evaluation minus the reported time,
+ * sampled on every 8th request. Without a timestamp in the metadata, the flag evaluation hook reads
+ * its own clock after the evaluation, so the reported time is never early.
+ *
+ *
Run with the thread count as an option: {@code java -jar dd-openfeature/build/libs/*-jmh.jar
+ * EvaluationMetadataTableBenchmark -t 12 -prof gc}. {@code tableSize=0} ignores the bucket width.
+ */
+@State(Scope.Benchmark)
+@Warmup(iterations = 2, time = 1, timeUnit = SECONDS)
+@Measurement(iterations = 3, time = 1, timeUnit = SECONDS)
+@BenchmarkMode(Mode.SampleTime)
+@OutputTimeUnit(NANOSECONDS)
+@Fork(value = 1)
+public class EvaluationMetadataTableBenchmark {
+ private static final String CONFIG_PATH =
+ "dd-openfeature/src/test/fixtures/ffe-system-test-data/evaluation-suites/scale/ufc-config.json";
+ private static final int POPULATION = 1000;
+ private static final int CONTEXTS = 1024;
+ private static final int DRAWS = 1 << 16;
+ private static final int ERROR_SAMPLE_MASK = 7;
+ private static final int MAX_ERROR_MS = 10_000;
+
+ /** The number of flags each request evaluates. */
+ @Param({"10", "50"})
+ public int flagsPerRequest;
+
+ /** The requested table size, 0 for no table. */
+ @Param({"0", "256", "1024", "4096"})
+ public int tableSize;
+
+ /** The time bucket width in milliseconds, 0 to leave the timestamp out of the metadata. */
+ @Param({"1", "10", "100", "1000", "0"})
+ public int timeBucketMs;
+
+ /** How the flags of a request are drawn: {@code uniform} or {@code skewed} (Zipf). */
+ @Param({"uniform", "skewed"})
+ public String popularity;
+
+ private ServerConfiguration config;
+ private FlagEvaluator evaluator;
+ private String[] flags;
+ private double[] cumulative;
+ private EvaluationContext[] contexts;
+ private final AtomicInteger threadSeeds = new AtomicInteger();
+ private final List threads = Collections.synchronizedList(new ArrayList<>());
+ private final LongAdder misses = new LongAdder();
+ private final LongAdder lookups = new LongAdder();
+
+ /** One benchmark thread: its flag draws, its positions, and its timestamp error histogram. */
+ @State(Scope.Thread)
+ public static class Requests {
+ private int[] draws;
+ private int nextDraw;
+ private int nextContext;
+ private int requests;
+ private long[] earlyMs;
+
+ @Setup(Level.Trial)
+ public void setUp(final EvaluationMetadataTableBenchmark benchmark) {
+ final int seed = benchmark.threadSeeds.incrementAndGet();
+ draws = benchmark.draws(new SplittableRandom(seed));
+ nextContext = (seed * 97) & (CONTEXTS - 1);
+ earlyMs = new long[MAX_ERROR_MS + 1];
+ benchmark.threads.add(this);
+ }
+
+ @Setup(Level.Iteration)
+ public void reset() {
+ Arrays.fill(earlyMs, 0);
+ }
+
+ int nextDraw() {
+ final int draw = draws[nextDraw];
+ nextDraw = (nextDraw + 1) & (DRAWS - 1);
+ return draw;
+ }
+
+ EvaluationContext nextContext(final EvaluationContext[] contexts) {
+ final EvaluationContext context = contexts[nextContext];
+ nextContext = (nextContext + 1) & (CONTEXTS - 1);
+ return context;
+ }
+ }
+
+ @Setup(Level.Trial)
+ public void setUp() throws IOException {
+ config = UniversalFlagConfigParser.parse(Files.readAllBytes(configFile()));
+ evaluator =
+ new FlagEvaluator(
+ false,
+ (flag, subject, allocation, variant, serialId) -> false,
+ ExperimentationOptOutMode.DISABLED,
+ true,
+ EvaluationMetadataTable.create(tableSize, misses),
+ timeBucketMs);
+ // Every 10th bulk flag is disabled: skip them, so each evaluation resolves a split.
+ flags = new String[POPULATION];
+ for (int i = 0, flag = 0; i < POPULATION; flag++) {
+ if (flag % 10 != 9) {
+ flags[i++] = String.format(Locale.ROOT, "scale-bulk-%05d", flag);
+ }
+ }
+ cumulative = new double[POPULATION];
+ double sum = 0;
+ for (int i = 0; i < POPULATION; i++) {
+ sum += "skewed".equals(popularity) ? 1.0 / (i + 1) : 1.0;
+ cumulative[i] = sum;
+ }
+ for (int i = 0; i < POPULATION; i++) {
+ cumulative[i] /= sum;
+ }
+ contexts = new EvaluationContext[CONTEXTS];
+ for (int i = 0; i < CONTEXTS; i++) {
+ contexts[i] =
+ new ImmutableContext(
+ "subject-" + i,
+ Collections.singletonMap(
+ "cohort", new Value(String.format(Locale.ROOT, "cohort-%02d", i % 100))));
+ }
+ for (final String flag : flags) {
+ final ProviderEvaluation result =
+ evaluator.evaluate(config, Boolean.class, flag, false, contexts[0]);
+ if (result.getErrorCode() != null || result.getVariant() == null) {
+ throw new IllegalStateException(flag + " did not resolve a split: " + result.getReason());
+ }
+ }
+ }
+
+ int[] draws(final SplittableRandom random) {
+ final int[] draws = new int[DRAWS];
+ for (int i = 0; i < DRAWS; i++) {
+ final int index = Arrays.binarySearch(cumulative, random.nextDouble());
+ draws[i] = Math.min(index < 0 ? -index - 1 : index, POPULATION - 1);
+ }
+ return draws;
+ }
+
+ @Setup(Level.Iteration)
+ public void startIteration() {
+ misses.reset();
+ lookups.reset();
+ }
+
+ @TearDown(Level.Iteration)
+ @SuppressForbidden
+ public void reportIteration() {
+ final long total = lookups.sum();
+ final long missed = tableSize == 0 ? total : misses.sum();
+ final long[] early = new long[MAX_ERROR_MS + 1];
+ synchronized (threads) {
+ for (final Requests thread : threads) {
+ for (int i = 0; i <= MAX_ERROR_MS; i++) {
+ early[i] += thread.earlyMs[i];
+ }
+ }
+ }
+ long samples = 0;
+ int max = 0;
+ for (int i = 0; i <= MAX_ERROR_MS; i++) {
+ samples += early[i];
+ if (early[i] != 0) {
+ max = i;
+ }
+ }
+ int p99 = 0;
+ for (long seen = early[0]; seen < samples * 0.99 && p99 < MAX_ERROR_MS; ) {
+ seen += early[++p99];
+ }
+ System.out.printf(
+ Locale.ROOT,
+ "%n@@ table=%d bucket=%d flags=%d popularity=%s lookups=%d misses=%d hitRate=%.4f"
+ + " earlyP99Ms=%d earlyMaxMs=%d samples=%d%n",
+ EvaluationMetadataTable.size(tableSize),
+ timeBucketMs,
+ flagsPerRequest,
+ popularity,
+ total,
+ missed,
+ total == 0 ? 0 : (double) (total - missed) / total,
+ p99,
+ max,
+ samples);
+ }
+
+ @Benchmark
+ public void request(final Requests requests, final Blackhole blackhole) {
+ final EvaluationContext context = requests.nextContext(contexts);
+ final boolean sample = (requests.requests++ & ERROR_SAMPLE_MASK) == 0;
+ for (int i = 0; i < flagsPerRequest; i++) {
+ final String flag = flags[requests.nextDraw()];
+ if (sample) {
+ final long before = System.currentTimeMillis();
+ final ProviderEvaluation result =
+ evaluator.evaluate(config, Boolean.class, flag, false, context);
+ final Long reported = result.getFlagMetadata().getLong(EVAL_TIMESTAMP_MS);
+ // Without the timestamp, the hook reads its clock after the evaluation: never early.
+ final long early = reported == null ? 0 : before - reported;
+ requests.earlyMs[(int) Math.max(0, Math.min(early, MAX_ERROR_MS))]++;
+ blackhole.consume(result);
+ } else {
+ blackhole.consume(evaluator.evaluate(config, Boolean.class, flag, false, context));
+ }
+ }
+ lookups.add(flagsPerRequest);
+ }
+
+ private static Path configFile() {
+ Path directory = Paths.get("").toAbsolutePath();
+ while (directory != null) {
+ final Path candidate = directory.resolve(CONFIG_PATH);
+ if (Files.exists(candidate)) {
+ return candidate;
+ }
+ directory = directory.getParent();
+ }
+ throw new IllegalStateException(
+ "Unable to find the FFE scale suite: initialize the ffe-system-test-data submodule");
+ }
+}
diff --git a/dd-openfeature/src/main/java/com/datadog/openfeature/DDEvaluator.java b/dd-openfeature/src/main/java/com/datadog/openfeature/DDEvaluator.java
index 8e0111e71a5..0da5e7773d9 100644
--- a/dd-openfeature/src/main/java/com/datadog/openfeature/DDEvaluator.java
+++ b/dd-openfeature/src/main/java/com/datadog/openfeature/DDEvaluator.java
@@ -136,7 +136,12 @@ class DDEvaluator implements Evaluator, Consumer {
// hook.
this.core =
new FlagEvaluator(
- spanEnrichmentEnabled, this::isExposed, experimentationOptOutMode, exposuresEnabled);
+ spanEnrichmentEnabled,
+ this::isExposed,
+ experimentationOptOutMode,
+ exposuresEnabled,
+ settings.evaluationMetadataTableSize(),
+ settings.evaluationMetadataTimeBucketMs());
}
@Override
diff --git a/dd-openfeature/src/main/java/com/datadog/openfeature/internal/config/Settings.java b/dd-openfeature/src/main/java/com/datadog/openfeature/internal/config/Settings.java
index d36df1462ee..2e4d4449d75 100644
--- a/dd-openfeature/src/main/java/com/datadog/openfeature/internal/config/Settings.java
+++ b/dd-openfeature/src/main/java/com/datadog/openfeature/internal/config/Settings.java
@@ -39,6 +39,10 @@ public final class Settings {
static final String EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED =
"feature.flags.evaluation.telemetry.per.subject.opt.out.enabled";
static final String EXPERIMENTATION_OPT_OUT_MODE = "feature.flags.experimentation.opt.out.mode";
+ static final String EVALUATION_METADATA_TABLE_SIZE =
+ "feature.flags.evaluation.metadata.table.size";
+ static final String EVALUATION_METADATA_TIME_BUCKET_MS =
+ "feature.flags.evaluation.metadata.time.bucket.ms";
static final String TRACE_DEBUG = "trace.debug";
static final String API_KEY = "api-key";
static final String SITE = "site";
@@ -49,6 +53,8 @@ public final class Settings {
static final String DEFAULT_SITE = "datadoghq.com";
static final int DEFAULT_POLL_INTERVAL_SECONDS = 30;
static final int DEFAULT_REQUEST_TIMEOUT_SECONDS = 5;
+ static final int DEFAULT_EVALUATION_METADATA_TABLE_SIZE = 1024;
+ static final int DEFAULT_EVALUATION_METADATA_TIME_BUCKET_MS = 10;
private final AgentBridge bridge;
private final UnaryOperator systemProperties;
@@ -182,6 +188,31 @@ public String experimentationOptOutMode() {
return mode == null ? "disabled" : mode;
}
+ /**
+ * The number of slots of the table sharing the flag metadata of evaluations that resolve the same
+ * split in the same millisecond. The evaluator rounds it up to a power of two.
+ *
+ * @return the number of slots, or 0 to build the metadata of each evaluation (1024 by default).
+ */
+ public int evaluationMetadataTableSize() {
+ return getNonNegativeInt(
+ EVALUATION_METADATA_TABLE_SIZE, DEFAULT_EVALUATION_METADATA_TABLE_SIZE);
+ }
+
+ /**
+ * The width of the time bucket in which evaluations of a split share their flag metadata,
+ * including its evaluation timestamp. Evaluations that reuse the metadata report the time of the
+ * evaluation that built it, up to the width minus one millisecond early. The evaluator caps it at
+ * 10,000 milliseconds, the flush interval of the flag evaluation events.
+ *
+ * @return the width in milliseconds (10 by default; 1 keeps the timestamps exact), or 0 to leave
+ * the timestamp out of the metadata, so the hooks read their own clock.
+ */
+ public int evaluationMetadataTimeBucketMs() {
+ return getNonNegativeInt(
+ EVALUATION_METADATA_TIME_BUCKET_MS, DEFAULT_EVALUATION_METADATA_TIME_BUCKET_MS);
+ }
+
/**
* Tells whether {@code DD_TRACE_DEBUG} is on. It gates the diagnostics that log raw evaluation
* contexts and values, on top of the application's logging configuration.
@@ -292,6 +323,16 @@ private Boolean getBoolean(final String key) {
/** Reads the first value that parses, in source priority order, like the agent. */
private int getPositiveInt(final String key, final int defaultValue) {
+ return getInt(key, defaultValue, 1, "positive");
+ }
+
+ /** Reads the first value that parses, in source priority order, like the agent. */
+ private int getNonNegativeInt(final String key, final int defaultValue) {
+ return getInt(key, defaultValue, 0, "zero or positive");
+ }
+
+ private int getInt(
+ final String key, final int defaultValue, final int minimum, final String expected) {
for (int source = 0; source < SOURCE_COUNT; source++) {
final String value = value(key, source);
if (nonBlank(value) == null) {
@@ -299,10 +340,10 @@ private int getPositiveInt(final String key, final int defaultValue) {
}
try {
final int parsed = Integer.parseInt(value);
- if (parsed > 0) {
+ if (parsed >= minimum) {
return parsed;
}
- LOGGER.warn("Invalid value for {}: {}. The value must be positive", key, value);
+ LOGGER.warn("Invalid value for {}: {}. The value must be {}", key, value, expected);
return defaultValue;
} catch (final NumberFormatException e) {
LOGGER.warn("Invalid value for {}: {}", key, value);
diff --git a/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTable.java b/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTable.java
new file mode 100644
index 00000000000..e88475123cc
--- /dev/null
+++ b/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTable.java
@@ -0,0 +1,206 @@
+package com.datadog.openfeature.internal.evaluation;
+
+import com.datadog.openfeature.internal.ufc.Allocation;
+import com.datadog.openfeature.internal.ufc.Flag;
+import com.datadog.openfeature.internal.ufc.Split;
+import dev.openfeature.sdk.ImmutableMetadata;
+import java.util.concurrent.atomic.LongAdder;
+import javax.annotation.Nullable;
+
+/**
+ * Shares the flag metadata of successful evaluations that resolve the same split in the same time
+ * bucket. With a bounded bucket, this is a burst coalescer, not a cache: an entry is only reusable
+ * within the bucket it was built in, because the metadata carries the evaluation timestamp of the
+ * evaluation that built it. A later bucket builds and publishes a new entry. A bucket of {@code W}
+ * milliseconds reports the evaluations that reuse an entry up to {@code W - 1} milliseconds early:
+ * the default of 10 milliseconds, at most 9 milliseconds early in the 10 second flush interval of
+ * the flag evaluation events, shares most of what wider buckets share. A bucket of one millisecond,
+ * the resolution of the timestamp, keeps the timestamp exact. The {@link #UNBOUNDED} bucket leaves
+ * the timestamp out of the metadata, so the hooks read their own clock and the entry of a split is
+ * reusable until the slot is replaced.
+ *
+ * The table is a fixed, direct-mapped array of slots. Each slot holds the metadata built last
+ * for one key: the {@link Split}, {@link Allocation} and {@link Flag} references, the configuration
+ * consent to observe full evaluation data, the exposure state, and the time bucket. Everything else
+ * in the metadata is fixed by the split, its allocation and its flag. The key compares references,
+ * so a reloaded configuration, whose objects are new, never matches an entry of the previous one,
+ * and no metadata field can be left out of the key.
+ *
+ *
The table takes no lock. An entry has only final fields and is published with a single
+ * reference store, so a reader sees either a whole entry or none. Two evaluations that miss the
+ * same slot at once both build metadata and the last store wins: a lost race only costs a rebuild.
+ */
+final class EvaluationMetadataTable {
+ /** The default number of slots. */
+ static final int DEFAULT_SIZE = 1024;
+
+ /** The largest number of slots. */
+ static final int MAX_SIZE = 1 << 16;
+
+ /** The default time bucket width. */
+ static final int DEFAULT_TIME_BUCKET_MS = 10;
+
+ /**
+ * The widest time bucket: the flush interval of the flag evaluation events, which aggregate the
+ * first and last evaluation times of each interval.
+ */
+ static final int MAX_TIME_BUCKET_MS = 10_000;
+
+ /** The time bucket width that leaves the evaluation timestamp out of the metadata. */
+ static final int UNBOUNDED = 0;
+
+ /** The evaluation logs no exposure, so the metadata carries no exposure state. */
+ static final int NO_EXPOSURE = 0;
+
+ /** The evaluation logs an exposure that was not recorded yet. */
+ static final int NEW_EXPOSURE = 1;
+
+ /** The evaluation logs an exposure that was already recorded. */
+ static final int RECORDED_EXPOSURE = 2;
+
+ private final Entry[] slots;
+ private final int mask;
+ @Nullable private final LongAdder misses;
+
+ private EvaluationMetadataTable(final int size, @Nullable final LongAdder misses) {
+ this.slots = new Entry[size];
+ this.mask = size - 1;
+ this.misses = misses;
+ }
+
+ /**
+ * Creates a table.
+ *
+ * @param requestedSize the requested number of slots: rounded up to a power of two and capped at
+ * {@link #MAX_SIZE}, or 0 to share no metadata.
+ * @return the table, or {@code null} if the requested size is 0 or negative.
+ */
+ @Nullable
+ static EvaluationMetadataTable create(final int requestedSize) {
+ return create(requestedSize, null);
+ }
+
+ /**
+ * Creates a table that counts its misses, for the benchmarks.
+ *
+ * @param requestedSize the requested number of slots, as for {@link #create(int)}.
+ * @param misses the counter incremented on each lookup that finds no entry, or {@code null}.
+ * @return the table, or {@code null} if the requested size is 0 or negative.
+ */
+ @Nullable
+ static EvaluationMetadataTable create(final int requestedSize, @Nullable final LongAdder misses) {
+ final int size = size(requestedSize);
+ return size == 0 ? null : new EvaluationMetadataTable(size, misses);
+ }
+
+ /**
+ * @param requestedSize the requested number of slots.
+ * @return the number of slots of a table of this requested size, 0 when it shares no metadata.
+ */
+ static int size(final int requestedSize) {
+ if (requestedSize <= 0) {
+ return 0;
+ }
+ if (requestedSize >= MAX_SIZE) {
+ return MAX_SIZE;
+ }
+ return requestedSize == 1 ? 1 : Integer.highestOneBit(requestedSize - 1) << 1;
+ }
+
+ /**
+ * @param requestedMs the requested time bucket width, in milliseconds.
+ * @return the width used: {@link #UNBOUNDED} for 0, at least 1 and at most {@link
+ * #MAX_TIME_BUCKET_MS} otherwise.
+ */
+ static int timeBucketMs(final int requestedMs) {
+ if (requestedMs == UNBOUNDED) {
+ return UNBOUNDED;
+ }
+ return Math.max(1, Math.min(requestedMs, MAX_TIME_BUCKET_MS));
+ }
+
+ /** The number of slots. */
+ int size() {
+ return slots.length;
+ }
+
+ /**
+ * Finds the metadata built for this key.
+ *
+ * @return the metadata, or {@code null} if the slot holds another key.
+ */
+ @Nullable
+ ImmutableMetadata get(
+ final Flag flag,
+ final Allocation allocation,
+ final Split split,
+ final boolean observeFullEvaluationData,
+ final int exposure,
+ final long timeBucket) {
+ final Entry entry = slots[index(split, exposure)];
+ if (entry != null
+ && entry.split == split
+ && entry.timeBucket == timeBucket
+ && entry.exposure == exposure
+ && entry.observeFullEvaluationData == observeFullEvaluationData
+ && entry.allocation == allocation
+ && entry.flag == flag) {
+ return entry.metadata;
+ }
+ if (misses != null) {
+ misses.increment();
+ }
+ return null;
+ }
+
+ /** Publishes the metadata built for this key, replacing the slot's entry. */
+ void put(
+ final Flag flag,
+ final Allocation allocation,
+ final Split split,
+ final boolean observeFullEvaluationData,
+ final int exposure,
+ final long timeBucket,
+ final ImmutableMetadata metadata) {
+ slots[index(split, exposure)] =
+ new Entry(
+ flag, allocation, split, observeFullEvaluationData, exposure, timeBucket, metadata);
+ }
+
+ private int index(final Split split, final int exposure) {
+ // The exposure states of a split take neighboring slots, so a subject that was already exposed
+ // does not evict the entry of one that was not. The time bucket is left out: the next one
+ // replaces the entry of the previous one instead of evicting another split.
+ int hash = (System.identityHashCode(split) << 2 | exposure) * 0x9E3779B9;
+ hash ^= hash >>> 16;
+ return hash & mask;
+ }
+
+ /** One immutable slot entry. Its final fields make it safe to publish without a barrier. */
+ private static final class Entry {
+ final Flag flag;
+ final Allocation allocation;
+ final Split split;
+ final boolean observeFullEvaluationData;
+ final int exposure;
+ final long timeBucket;
+ final ImmutableMetadata metadata;
+
+ Entry(
+ final Flag flag,
+ final Allocation allocation,
+ final Split split,
+ final boolean observeFullEvaluationData,
+ final int exposure,
+ final long timeBucket,
+ final ImmutableMetadata metadata) {
+ this.flag = flag;
+ this.allocation = allocation;
+ this.split = split;
+ this.observeFullEvaluationData = observeFullEvaluationData;
+ this.exposure = exposure;
+ this.timeBucket = timeBucket;
+ this.metadata = metadata;
+ }
+ }
+}
diff --git a/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/FlagEvaluator.java b/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/FlagEvaluator.java
index 79d0b97c25e..b4c1b488367 100644
--- a/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/FlagEvaluator.java
+++ b/dd-openfeature/src/main/java/com/datadog/openfeature/internal/evaluation/FlagEvaluator.java
@@ -44,6 +44,7 @@
import java.util.concurrent.ConcurrentHashMap;
import java.util.regex.Pattern;
import java.util.regex.PatternSyntaxException;
+import javax.annotation.Nullable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@@ -63,6 +64,8 @@ public final class FlagEvaluator {
private final ExposureLookup exposureLookup;
private final ExperimentationOptOutMode experimentationOptOutMode;
private final boolean exposuresEnabled;
+ @Nullable private final EvaluationMetadataTable metadataTable;
+ private final int metadataTimeBucketMs;
/**
* Creates an evaluator.
@@ -81,6 +84,28 @@ public FlagEvaluator(
this(spanEnrichmentEnabled, exposureLookup, experimentationOptOutMode, true);
}
+ /**
+ * Creates an evaluator with the default evaluation metadata table.
+ *
+ * @param spanEnrichmentEnabled whether span enrichment is enabled.
+ * @param exposureLookup the lookup telling whether an exposure was already recorded.
+ * @param experimentationOptOutMode the resolved experimentation opt-out mode.
+ * @param exposuresEnabled whether evaluations of allocations logging exposures are exposures.
+ */
+ public FlagEvaluator(
+ final boolean spanEnrichmentEnabled,
+ final ExposureLookup exposureLookup,
+ final ExperimentationOptOutMode experimentationOptOutMode,
+ final boolean exposuresEnabled) {
+ this(
+ spanEnrichmentEnabled,
+ exposureLookup,
+ experimentationOptOutMode,
+ exposuresEnabled,
+ EvaluationMetadataTable.DEFAULT_SIZE,
+ EvaluationMetadataTable.DEFAULT_TIME_BUCKET_MS);
+ }
+
/**
* Creates an evaluator.
*
@@ -90,16 +115,43 @@ public FlagEvaluator(
* @param exposuresEnabled whether evaluations of allocations logging exposures are exposures.
* When false, every evaluation is reported as not logging exposures, so no exposure is
* recorded, deduplicated, sent, or reported to exposure hooks, and assignment is unchanged.
+ * @param metadataTableSize the number of slots of the table sharing the metadata of evaluations
+ * that resolve the same split in the same time bucket, rounded up to a power of two, or 0 to
+ * build the metadata of each evaluation.
+ * @param metadataTimeBucketMs the width, in milliseconds, of the time bucket in which evaluations
+ * of a split share their metadata and its {@code __dd_eval_timestamp_ms}, at most {@link
+ * EvaluationMetadataTable#MAX_TIME_BUCKET_MS}; or 0 to leave the timestamp out of the
+ * metadata, so the hooks read their own clock.
*/
public FlagEvaluator(
final boolean spanEnrichmentEnabled,
final ExposureLookup exposureLookup,
final ExperimentationOptOutMode experimentationOptOutMode,
- final boolean exposuresEnabled) {
+ final boolean exposuresEnabled,
+ final int metadataTableSize,
+ final int metadataTimeBucketMs) {
+ this(
+ spanEnrichmentEnabled,
+ exposureLookup,
+ experimentationOptOutMode,
+ exposuresEnabled,
+ EvaluationMetadataTable.create(metadataTableSize),
+ metadataTimeBucketMs);
+ }
+
+ FlagEvaluator(
+ final boolean spanEnrichmentEnabled,
+ final ExposureLookup exposureLookup,
+ final ExperimentationOptOutMode experimentationOptOutMode,
+ final boolean exposuresEnabled,
+ @Nullable final EvaluationMetadataTable metadataTable,
+ final int metadataTimeBucketMs) {
this.spanEnrichmentEnabled = spanEnrichmentEnabled;
this.exposureLookup = exposureLookup;
this.experimentationOptOutMode = experimentationOptOutMode;
this.exposuresEnabled = exposuresEnabled;
+ this.metadataTable = metadataTable;
+ this.metadataTimeBucketMs = EvaluationMetadataTable.timeBucketMs(metadataTimeBucketMs);
}
public ProviderEvaluation evaluate(
@@ -541,22 +593,79 @@ private ProviderEvaluation resolveVariant(
observeFullEvaluationData);
}
- // Stamp eval-time at the resolution point so first/last_evaluation reflect evaluation time,
- // not hook-fire time. Passed to the hook via provider metadata "__dd_eval_timestamp_ms".
+ // The exposure state depends on the subject, so it is part of the metadata table key. A
+ // provider with exposures disabled treats every allocation as not logging exposures. The
+ // allocation and split were already selected, so this changes reporting, not assignment.
+ final boolean doLog = this.exposuresEnabled && Boolean.TRUE.equals(allocation.doLog);
+ final int exposure;
+ if (!doLog) {
+ exposure = EvaluationMetadataTable.NO_EXPOSURE;
+ } else if (this.exposureLookup.isExposed(
+ flag.key, context.getTargetingKey(), allocation.key, variant.key, split.serialId)) {
+ exposure = EvaluationMetadataTable.RECORDED_EXPOSURE;
+ } else {
+ exposure = EvaluationMetadataTable.NEW_EXPOSURE;
+ }
+ // Everything else in the metadata is fixed by the split, so evaluations of the split in the
+ // same time bucket share it.
+ final int bucketMs = this.metadataTimeBucketMs;
+ final long timeBucket =
+ bucketMs == EvaluationMetadataTable.UNBOUNDED
+ ? 0
+ : bucketMs == 1 ? evalTimestampMs : evalTimestampMs / bucketMs;
+ final EvaluationMetadataTable table = this.metadataTable;
+ ImmutableMetadata metadata =
+ table == null
+ ? null
+ : table.get(flag, allocation, split, observeFullEvaluationData, exposure, timeBucket);
+ if (metadata == null) {
+ metadata =
+ buildMetadata(
+ flag,
+ allocation,
+ split,
+ observeFullEvaluationData,
+ doLog,
+ exposure,
+ bucketMs == EvaluationMetadataTable.UNBOUNDED ? null : evalTimestampMs);
+ if (table != null) {
+ table.put(
+ flag, allocation, split, observeFullEvaluationData, exposure, timeBucket, metadata);
+ }
+ }
+ return ProviderEvaluation.builder()
+ .value(mappedValue)
+ .reason(resolveReason(allocation, split))
+ .variant(variant.key)
+ .flagMetadata(metadata)
+ .build();
+ }
+
+ private ImmutableMetadata buildMetadata(
+ final Flag flag,
+ final Allocation allocation,
+ final Split split,
+ final boolean observeFullEvaluationData,
+ final boolean doLog,
+ final int exposure,
+ @Nullable final Long evalTimestampMs) {
final ImmutableMetadata.ImmutableMetadataBuilder metadataBuilder =
ImmutableMetadata.builder()
.addString("flagKey", flag.key)
.addString("variationType", flag.variationType.name())
.addString(ALLOCATION_KEY, allocation.key)
- .addLong(EVAL_TIMESTAMP_MS, evalTimestampMs)
.addBoolean(OBSERVE_FULL_EVALUATION_DATA, observeFullEvaluationData);
+ // Stamp eval-time at the resolution point so first/last_evaluation reflect evaluation time,
+ // not hook-fire time. Passed to the hook via provider metadata "__dd_eval_timestamp_ms".
+ // Without
+ // it, the hook stamps its own time.
+ if (evalTimestampMs != null) {
+ metadataBuilder.addLong(EVAL_TIMESTAMP_MS, evalTimestampMs);
+ }
// Surface the UFC split's serial id and the allocation's doLog flag for APM span enrichment and
// for the exposure hook, which sends the exposure after the evaluation succeeds. An evaluation
// that neither logs exposures nor enriches spans carries neither key.
// __dd_split_serial_id is omitted when the split carries no serial id.
- // A provider with exposures disabled treats every allocation as not logging exposures. The
- // allocation and split were already selected, so this changes reporting, not assignment.
- final boolean doLog = this.exposuresEnabled && Boolean.TRUE.equals(allocation.doLog);
if (spanEnrichmentEnabled || doLog) {
if (split.serialId != null) {
metadataBuilder.addInteger(SPLIT_SERIAL_ID, split.serialId);
@@ -566,16 +675,9 @@ private ProviderEvaluation resolveVariant(
addSplitFeatures(metadataBuilder, split);
if (doLog) {
metadataBuilder.addBoolean(
- EXPOSURE_CACHE_HIT,
- this.exposureLookup.isExposed(
- flag.key, context.getTargetingKey(), allocation.key, variant.key, split.serialId));
+ EXPOSURE_CACHE_HIT, exposure == EvaluationMetadataTable.RECORDED_EXPOSURE);
}
- return ProviderEvaluation.builder()
- .value(mappedValue)
- .reason(resolveReason(allocation, split))
- .variant(variant.key)
- .flagMetadata(metadataBuilder.build())
- .build();
+ return metadataBuilder.build();
}
private static String resolveReason(final Allocation allocation, final Split split) {
diff --git a/dd-openfeature/src/test/java/com/datadog/openfeature/internal/config/SettingsTest.java b/dd-openfeature/src/test/java/com/datadog/openfeature/internal/config/SettingsTest.java
index 6fc2d6c6d0f..6e4bb603725 100644
--- a/dd-openfeature/src/test/java/com/datadog/openfeature/internal/config/SettingsTest.java
+++ b/dd-openfeature/src/test/java/com/datadog/openfeature/internal/config/SettingsTest.java
@@ -90,6 +90,8 @@ void appliesDefaults() {
assertTrue(settings.isEvaluationCountsEnabled());
assertTrue(settings.isExposuresDatadogLoggingEnabled());
assertEquals("disabled", settings.experimentationOptOutMode());
+ assertEquals(1024, settings.evaluationMetadataTableSize());
+ assertEquals(10, settings.evaluationMetadataTimeBucketMs());
}
@TableTest({
@@ -180,6 +182,36 @@ void fallsBackToDefaultPollIntervalOnInvalidValues(final String value, final int
.agentlessPollIntervalSeconds());
}
+ @TableTest({
+ "scenario | value | size",
+ "disabled | 0 | 0 ",
+ "custom | 300 | 300 ",
+ "negative | -1 | 1024",
+ "invalid | ten | 1024",
+ "blank | ' ' | 1024"
+ })
+ void readsTheEvaluationMetadataTableSize(final String value, final int size) {
+ assertEquals(
+ size,
+ TestSettings.of("feature.flags.evaluation.metadata.table.size", value)
+ .evaluationMetadataTableSize());
+ }
+
+ @TableTest({
+ "scenario | value | width",
+ "unbounded | 0 | 0 ",
+ "custom | 100 | 100 ",
+ "exact | 1 | 1 ",
+ "negative | -1 | 10 ",
+ "invalid | ten | 10 "
+ })
+ void readsTheEvaluationMetadataTimeBucket(final String value, final int width) {
+ assertEquals(
+ width,
+ TestSettings.of("feature.flags.evaluation.metadata.time.bucket.ms", value)
+ .evaluationMetadataTimeBucketMs());
+ }
+
@Test
void fallsBackToLowerPrioritySourcesOnBlankOrInvalidValues() {
final Map properties = new HashMap<>();
diff --git a/dd-openfeature/src/test/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTableTest.java b/dd-openfeature/src/test/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTableTest.java
new file mode 100644
index 00000000000..1104690efec
--- /dev/null
+++ b/dd-openfeature/src/test/java/com/datadog/openfeature/internal/evaluation/EvaluationMetadataTableTest.java
@@ -0,0 +1,403 @@
+package com.datadog.openfeature.internal.evaluation;
+
+import static com.datadog.openfeature.internal.evaluation.EvaluationMetadataTable.NEW_EXPOSURE;
+import static com.datadog.openfeature.internal.evaluation.EvaluationMetadataTable.RECORDED_EXPOSURE;
+import static com.datadog.openfeature.internal.evaluation.MetadataKeys.ALLOCATION_KEY;
+import static com.datadog.openfeature.internal.evaluation.MetadataKeys.DO_LOG;
+import static com.datadog.openfeature.internal.evaluation.MetadataKeys.EVAL_TIMESTAMP_MS;
+import static com.datadog.openfeature.internal.evaluation.MetadataKeys.EXPOSURE_CACHE_HIT;
+import static com.datadog.openfeature.internal.evaluation.MetadataKeys.OBSERVE_FULL_EVALUATION_DATA;
+import static java.util.Arrays.asList;
+import static java.util.Collections.emptyList;
+import static java.util.Collections.emptyMap;
+import static java.util.Collections.singletonList;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotSame;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.datadog.openfeature.ExperimentationOptOutMode;
+import com.datadog.openfeature.internal.ufc.Allocation;
+import com.datadog.openfeature.internal.ufc.Flag;
+import com.datadog.openfeature.internal.ufc.ServerConfiguration;
+import com.datadog.openfeature.internal.ufc.Split;
+import com.datadog.openfeature.internal.ufc.ValueType;
+import com.datadog.openfeature.internal.ufc.Variant;
+import dev.openfeature.sdk.ImmutableMetadata;
+import dev.openfeature.sdk.MutableContext;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.ThreadLocalRandom;
+import java.util.concurrent.TimeUnit;
+import org.junit.jupiter.api.Test;
+import org.tabletest.junit.TableTest;
+
+class EvaluationMetadataTableTest {
+ private static final ImmutableMetadata METADATA = ImmutableMetadata.builder().build();
+
+ @TableTest({
+ "scenario | requested | size ",
+ "disabled | 0 | 0 ",
+ "negative | -1 | 0 ",
+ "one | 1 | 1 ",
+ "rounded up | 3 | 4 ",
+ "power of two | 1024 | 1024 ",
+ "next power | 1025 | 2048 ",
+ "capped | 100000 | 65536"
+ })
+ void roundsTheSizeUpToAPowerOfTwo(final int requested, final int size) {
+ assertEquals(size, EvaluationMetadataTable.size(requested));
+ final EvaluationMetadataTable table = EvaluationMetadataTable.create(requested);
+ if (size == 0) {
+ assertNull(table);
+ } else {
+ assertEquals(size, table.size());
+ }
+ }
+
+ @Test
+ void findsTheMetadataOfTheSameKeyInTheSameMillisecondOnly() {
+ final EvaluationMetadataTable table = EvaluationMetadataTable.create(16);
+ final Split split = split();
+ final Allocation allocation = allocation("allocation", split, true);
+ final Flag flag = flag("flag", allocation);
+ table.put(flag, allocation, split, true, NEW_EXPOSURE, 100L, METADATA);
+
+ assertSame(METADATA, table.get(flag, allocation, split, true, NEW_EXPOSURE, 100L));
+ assertNull(table.get(flag, allocation, split, true, NEW_EXPOSURE, 101L));
+ assertNull(table.get(flag, allocation, split, false, NEW_EXPOSURE, 100L));
+ assertNull(table.get(flag, allocation, split, true, RECORDED_EXPOSURE, 100L));
+ assertNull(table.get(flag, allocation, split(), true, NEW_EXPOSURE, 100L));
+ final Allocation other = allocation("allocation", split, true);
+ assertNull(table.get(flag, other, split, true, NEW_EXPOSURE, 100L));
+ assertNull(table.get(flag("flag", allocation), allocation, split, true, NEW_EXPOSURE, 100L));
+ }
+
+ @Test
+ void evaluationsInTheSameMillisecondShareTheMetadata() {
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+ int shared = 0;
+ for (int i = 0; i < 1000 && shared < 10; i++) {
+ final ImmutableMetadata first = evaluate(evaluator, config, "flag", "user");
+ final ImmutableMetadata second = evaluate(evaluator, config, "flag", "user");
+ if (first.getLong(EVAL_TIMESTAMP_MS).equals(second.getLong(EVAL_TIMESTAMP_MS))) {
+ assertSame(first, second);
+ shared++;
+ } else {
+ assertNotSame(first, second);
+ }
+ }
+ assertEquals(10, shared);
+ }
+
+ @Test
+ void aLaterMillisecondBuildsNewMetadata() {
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+ final ImmutableMetadata first = evaluate(evaluator, config, "flag", "user");
+ final long firstMs = first.getLong(EVAL_TIMESTAMP_MS);
+ ImmutableMetadata later;
+ do {
+ later = evaluate(evaluator, config, "flag", "user");
+ } while (later.getLong(EVAL_TIMESTAMP_MS) == firstMs);
+
+ assertNotSame(first, later);
+ assertTrue(later.getLong(EVAL_TIMESTAMP_MS) > firstMs);
+ final Map expected = new HashMap<>(first.asUnmodifiableMap());
+ expected.put(EVAL_TIMESTAMP_MS, later.getLong(EVAL_TIMESTAMP_MS));
+ assertEquals(expected, later.asUnmodifiableMap());
+ }
+
+ @Test
+ void keysOnTheConsentOfTheConfiguration() {
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE);
+ final Flag flag = flag("flag", allocation("a", split(), true));
+ final ServerConfiguration consenting = config(true, flag);
+ final ServerConfiguration withheld = config(false, flag);
+
+ for (int i = 0; i < 100; i++) {
+ assertEquals(
+ true,
+ evaluate(evaluator, consenting, "flag", "user").getBoolean(OBSERVE_FULL_EVALUATION_DATA));
+ assertEquals(
+ false,
+ evaluate(evaluator, withheld, "flag", "user").getBoolean(OBSERVE_FULL_EVALUATION_DATA));
+ }
+ }
+
+ @Test
+ void keysOnTheExposureState() {
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+
+ for (int i = 0; i < 100; i++) {
+ assertEquals(
+ true, evaluate(evaluator, config, "flag", "exposed").getBoolean(EXPOSURE_CACHE_HIT));
+ assertEquals(
+ false, evaluate(evaluator, config, "flag", "user").getBoolean(EXPOSURE_CACHE_HIT));
+ }
+ }
+
+ @Test
+ void sharesAcrossExposureStatesWhenExposuresAreDisabled() {
+ final FlagEvaluator evaluator =
+ new FlagEvaluator(
+ false,
+ exposedUser(),
+ ExperimentationOptOutMode.DISABLED,
+ false,
+ EvaluationMetadataTable.DEFAULT_SIZE,
+ EvaluationMetadataTable.UNBOUNDED);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+
+ final ImmutableMetadata exposed = evaluate(evaluator, config, "flag", "exposed");
+ assertNull(exposed.getBoolean(DO_LOG));
+ assertNull(exposed.getBoolean(EXPOSURE_CACHE_HIT));
+ assertSame(exposed, evaluate(evaluator, config, "flag", "user"));
+ }
+
+ @Test
+ void keysOnTheAllocationAndItsDoLog() {
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE);
+ // Directly built configurations can share a split between allocations.
+ final Split split = split();
+ final ServerConfiguration logging = config(true, flag("flag", allocation("a", split, true)));
+ final ServerConfiguration silent = config(true, flag("flag", allocation("b", split, false)));
+
+ for (int i = 0; i < 100; i++) {
+ final ImmutableMetadata logged = evaluate(evaluator, logging, "flag", "user");
+ final ImmutableMetadata unlogged = evaluate(evaluator, silent, "flag", "user");
+ assertEquals("a", logged.getString(ALLOCATION_KEY));
+ assertEquals(true, logged.getBoolean(DO_LOG));
+ assertEquals("b", unlogged.getString(ALLOCATION_KEY));
+ assertNull(unlogged.getBoolean(DO_LOG));
+ assertNull(unlogged.getBoolean(EXPOSURE_CACHE_HIT));
+ }
+ }
+
+ @Test
+ void aReloadedConfigurationBuildsNewMetadata() {
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE);
+ final ServerConfiguration before = config(true, flag("flag", allocation("a", split(), true)));
+ final ServerConfiguration after = config(true, flag("flag", allocation("b", split(), true)));
+
+ for (int i = 0; i < 100; i++) {
+ final ImmutableMetadata old = evaluate(evaluator, before, "flag", "user");
+ final ImmutableMetadata reloaded = evaluate(evaluator, after, "flag", "user");
+ assertNotSame(old, reloaded);
+ assertEquals("a", old.getString(ALLOCATION_KEY));
+ assertEquals("b", reloaded.getString(ALLOCATION_KEY));
+ }
+ }
+
+ @Test
+ void aZeroSizeBuildsTheMetadataOfEachEvaluation() {
+ final FlagEvaluator evaluator = evaluator(0);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+ for (int i = 0; i < 100; i++) {
+ final ImmutableMetadata first = evaluate(evaluator, config, "flag", "user");
+ final ImmutableMetadata second = evaluate(evaluator, config, "flag", "user");
+ assertNotSame(first, second);
+ if (first.getLong(EVAL_TIMESTAMP_MS).equals(second.getLong(EVAL_TIMESTAMP_MS))) {
+ assertEquals(first.asUnmodifiableMap(), second.asUnmodifiableMap());
+ }
+ }
+ }
+
+ @TableTest({
+ "scenario | requested | width",
+ "unbounded | 0 | 0 ",
+ "negative | -5 | 1 ",
+ "millisecond | 1 | 1 ",
+ "wider | 100 | 100 ",
+ "capped | 60000 | 10000"
+ })
+ void capsTheTimeBucketWidth(final int requested, final int width) {
+ assertEquals(width, EvaluationMetadataTable.timeBucketMs(requested));
+ }
+
+ @Test
+ void evaluationsInTheSameBucketShareTheMetadataOfTheFirstOne() {
+ final int width = 10;
+ final FlagEvaluator evaluator = evaluator(EvaluationMetadataTable.DEFAULT_SIZE, width);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+ // Start at the beginning of a bucket, so its later milliseconds follow.
+ while (System.currentTimeMillis() % width != 0) {
+ Thread.onSpinWait();
+ }
+ final ImmutableMetadata first = evaluate(evaluator, config, "flag", "user");
+ final long firstMs = first.getLong(EVAL_TIMESTAMP_MS);
+ int laterMilliseconds = 0;
+ long before;
+ ImmutableMetadata later;
+ while (true) {
+ before = System.currentTimeMillis();
+ later = evaluate(evaluator, config, "flag", "user");
+ if (later.getLong(EVAL_TIMESTAMP_MS) / width != firstMs / width) {
+ break;
+ }
+ // A later millisecond of the bucket still reports the time of the first evaluation.
+ assertSame(first, later);
+ if (before > firstMs) {
+ laterMilliseconds++;
+ }
+ }
+
+ assertTrue(laterMilliseconds > 0);
+ assertNotSame(first, later);
+ assertTrue(later.getLong(EVAL_TIMESTAMP_MS) >= before);
+ }
+
+ @Test
+ void anUnboundedBucketLeavesTheTimestampOutAndKeepsTheMetadata() {
+ final FlagEvaluator evaluator =
+ evaluator(EvaluationMetadataTable.DEFAULT_SIZE, EvaluationMetadataTable.UNBOUNDED);
+ final Flag flag = flag("flag", allocation("a", split(), true));
+ final ImmutableMetadata first = evaluate(evaluator, config(true, flag), "flag", "user");
+ final long start = System.currentTimeMillis();
+
+ assertNull(first.getLong(EVAL_TIMESTAMP_MS));
+ assertEquals("a", first.getString(ALLOCATION_KEY));
+ while (System.currentTimeMillis() < start + 3) {
+ assertSame(first, evaluate(evaluator, config(true, flag), "flag", "user"));
+ }
+ assertNotSame(first, evaluate(evaluator, config(false, flag), "flag", "user"));
+ }
+
+ @Test
+ void anUnboundedBucketWithoutTableBuildsTimestamplessMetadata() {
+ final FlagEvaluator evaluator = evaluator(0, EvaluationMetadataTable.UNBOUNDED);
+ final ServerConfiguration config = config(true, flag("flag", allocation("a", split(), true)));
+ final ImmutableMetadata first = evaluate(evaluator, config, "flag", "user");
+ final ImmutableMetadata second = evaluate(evaluator, config, "flag", "user");
+
+ assertNotSame(first, second);
+ assertNull(first.getLong(EVAL_TIMESTAMP_MS));
+ assertEquals(first.asUnmodifiableMap(), second.asUnmodifiableMap());
+ }
+
+ @TableTest({
+ "scenario | timeBucketMs",
+ "millisecond | 1 ",
+ "wider bucket | 10 ",
+ "unbounded | 0 "
+ })
+ void neverReturnsTheMetadataOfAnotherKeyUnderContention(final int timeBucketMs) throws Exception {
+ // A single slot makes every key collide.
+ final FlagEvaluator evaluator =
+ new FlagEvaluator(
+ false,
+ exposedUser(),
+ ExperimentationOptOutMode.DISABLED,
+ true,
+ EvaluationMetadataTable.create(1),
+ timeBucketMs);
+ final List flags = new ArrayList<>();
+ for (int i = 0; i < 4; i++) {
+ flags.add(flag("flag-" + i, allocation("allocation-" + i, split(), i % 2 == 0)));
+ }
+ final ServerConfiguration consenting = config(true, flags.toArray(new Flag[0]));
+ final ServerConfiguration withheld = config(false, flags.toArray(new Flag[0]));
+ final int threads = 8;
+ final CountDownLatch start = new CountDownLatch(1);
+ final ExecutorService executor = Executors.newFixedThreadPool(threads);
+ try {
+ final List> results = new ArrayList<>();
+ for (int t = 0; t < threads; t++) {
+ results.add(
+ executor.submit(() -> {
+ start.await();
+ final ThreadLocalRandom random = ThreadLocalRandom.current();
+ for (int i = 0; i < 50_000; i++) {
+ final int flag = random.nextInt(flags.size());
+ final boolean consent = random.nextBoolean();
+ final String subject = random.nextBoolean() ? "exposed" : "user";
+ final long before = System.currentTimeMillis();
+ final ImmutableMetadata metadata =
+ evaluate(evaluator, consent ? consenting : withheld, "flag-" + flag, subject);
+ final long after = System.currentTimeMillis();
+ assertEquals("flag-" + flag, metadata.getString("flagKey"));
+ assertEquals("allocation-" + flag, metadata.getString(ALLOCATION_KEY));
+ assertEquals(consent, metadata.getBoolean(OBSERVE_FULL_EVALUATION_DATA));
+ assertEquals(
+ flag % 2 == 0 ? "exposed".equals(subject) : null,
+ metadata.getBoolean(EXPOSURE_CACHE_HIT));
+ if (timeBucketMs == EvaluationMetadataTable.UNBOUNDED) {
+ assertNull(metadata.getLong(EVAL_TIMESTAMP_MS));
+ } else {
+ // A reused entry reports the time of the evaluation that built it, in the same
+ // bucket.
+ final long ms = metadata.getLong(EVAL_TIMESTAMP_MS);
+ final long earliest = before - before % timeBucketMs;
+ assertTrue(
+ earliest <= ms && ms <= after, ms + " not in " + earliest + ".." + after);
+ }
+ }
+ return null;
+ }));
+ }
+ start.countDown();
+ for (final Future> result : results) {
+ result.get(60, TimeUnit.SECONDS);
+ }
+ } finally {
+ executor.shutdownNow();
+ }
+ }
+
+ /** An evaluator with a one millisecond bucket, which keeps the timestamps exact. */
+ private static FlagEvaluator evaluator(final int tableSize) {
+ return evaluator(tableSize, 1);
+ }
+
+ private static FlagEvaluator evaluator(final int tableSize, final int timeBucketMs) {
+ return new FlagEvaluator(
+ false, exposedUser(), ExperimentationOptOutMode.DISABLED, true, tableSize, timeBucketMs);
+ }
+
+ private static FlagEvaluator.ExposureLookup exposedUser() {
+ return (flag, subject, allocation, variant, serialId) -> "exposed".equals(subject);
+ }
+
+ private static ImmutableMetadata evaluate(
+ final FlagEvaluator evaluator,
+ final ServerConfiguration config,
+ final String flag,
+ final String subject) {
+ final ImmutableMetadata metadata =
+ evaluator
+ .evaluate(config, Integer.class, flag, 0, new MutableContext(subject))
+ .getFlagMetadata();
+ return metadata;
+ }
+
+ private static Split split() {
+ return new Split(emptyList(), "on", emptyMap(), 7);
+ }
+
+ private static Allocation allocation(final String key, final Split split, final boolean doLog) {
+ return new Allocation(key, null, null, null, singletonList(split), doLog);
+ }
+
+ private static Flag flag(final String key, final Allocation allocation) {
+ final Map variations = new HashMap<>();
+ variations.put("on", new Variant("on", 1));
+ return new Flag(key, true, ValueType.INTEGER, variations, singletonList(allocation));
+ }
+
+ private static ServerConfiguration config(final boolean consent, final Flag... flags) {
+ final Map byKey = new HashMap<>();
+ for (final Flag flag : asList(flags)) {
+ byKey.put(flag.key, flag);
+ }
+ return new ServerConfiguration("", "", consent, null, byKey);
+ }
+}
diff --git a/dd-trace-api/src/main/java/datadog/trace/api/config/FeatureFlaggingConfig.java b/dd-trace-api/src/main/java/datadog/trace/api/config/FeatureFlaggingConfig.java
index a14f4adbf5c..1e38da77652 100644
--- a/dd-trace-api/src/main/java/datadog/trace/api/config/FeatureFlaggingConfig.java
+++ b/dd-trace-api/src/main/java/datadog/trace/api/config/FeatureFlaggingConfig.java
@@ -36,5 +36,24 @@ public final class FeatureFlaggingConfig {
public static final String FEATURE_FLAGS_EXPERIMENTATION_OPT_OUT_MODE =
"feature.flags.experimentation.opt.out.mode";
+ /**
+ * The number of slots of the table sharing the flag metadata of evaluations that resolve the same
+ * split in the same millisecond, rounded up to a power of two. {@code 0} builds the metadata of
+ * each evaluation. Default: {@code 1024}. Maps to {@code
+ * DD_FEATURE_FLAGS_EVALUATION_METADATA_TABLE_SIZE}.
+ */
+ public static final String FEATURE_FLAGS_EVALUATION_METADATA_TABLE_SIZE =
+ "feature.flags.evaluation.metadata.table.size";
+
+ /**
+ * The width, in milliseconds, of the time bucket in which evaluations of a split share their flag
+ * metadata, including its evaluation timestamp, so evaluations report up to the width minus one
+ * millisecond early. At most {@code 10000}. {@code 0} leaves the timestamp out of the metadata,
+ * so the hooks read their own clock, and {@code 1} keeps the timestamps exact. Default: {@code
+ * 10}. Maps to {@code DD_FEATURE_FLAGS_EVALUATION_METADATA_TIME_BUCKET_MS}.
+ */
+ public static final String FEATURE_FLAGS_EVALUATION_METADATA_TIME_BUCKET_MS =
+ "feature.flags.evaluation.metadata.time.bucket.ms";
+
private FeatureFlaggingConfig() {}
}
diff --git a/metadata/supported-configurations.json b/metadata/supported-configurations.json
index 0a42dda0ec2..7f349ae6942 100644
--- a/metadata/supported-configurations.json
+++ b/metadata/supported-configurations.json
@@ -1612,6 +1612,22 @@
"aliases": []
}
],
+ "DD_FEATURE_FLAGS_EVALUATION_METADATA_TABLE_SIZE": [
+ {
+ "version": "A",
+ "type": "int",
+ "default": "1024",
+ "aliases": []
+ }
+ ],
+ "DD_FEATURE_FLAGS_EVALUATION_METADATA_TIME_BUCKET_MS": [
+ {
+ "version": "A",
+ "type": "int",
+ "default": "10",
+ "aliases": []
+ }
+ ],
"DD_FEATURE_FLAGS_EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED": [
{
"version": "A",