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",