Skip to content
Merged
26 changes: 26 additions & 0 deletions dd-openfeature/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,32 @@ Settings are read from the Datadog Java agent configuration when attached, then
| Span enrichment | No | Yes |
| `ExposureHook` accessors `getFlagKey()`, `getVariant()`, `getAllocationKey()`, `getTargetingKey()` | The next release after 1.68.1 | The next release after 1.68.1 |

## Flag selection

To load only part of the flag configuration, give the provider a flag selection. It then loads the flags that have any of the tags, or whose key matches any of the key patterns:

```java
import com.datadog.openfeature.FlagSelection;
import com.datadog.openfeature.Provider;
import dev.openfeature.sdk.OpenFeatureAPI;
import java.util.List;

OpenFeatureAPI.getInstance().setProviderAndWait(new Provider(new Provider.Options()
.flagSelection(new FlagSelection()
.tags(List.of("checkout"))
.keyPatterns(List.of("checkout.*")))));
```

* Tags match exactly and case-sensitively. A key pattern matches the whole key, case-sensitively: `*` matches any run of characters, and every other character is literal.
* Evaluating a flag outside the selection returns the default value with `FLAG_NOT_FOUND`. A selection that matches no flag loads an empty configuration.
* Leading and trailing Unicode white space is trimmed from every value, and empty and duplicate values are dropped. A null list is treated as absent.
* Each list accepts at most 31 values, and each tag and key pattern is at most 200 UTF-8 bytes. A selection over a limit, one holding a null or non-`String` value or an unpaired UTF-16 surrogate, or one that would make the request URL longer than 8192 bytes, is not sent. The provider logs an error, for example `flagSelection was not sent (too_many_values: each list accepts at most 31 values). Loading the full flag configuration.`, and loads all the flags.
* The server can also ignore a selection. It then returns all the flags, and the provider logs `flagSelection was ignored by the server (<reason>). Loaded the full flag configuration.` once per reason. A custom configuration endpoint must forward the `selected_flag_tags` and `selected_flag_key_patterns` query parameters, and the `DD-Flag-Selection-Ignored` response header.
* The selection is set in code only, and the provider captures it at construction.
* The providers of a class loader share one flag configuration. The first provider initialized decides the selection, including a provider without one, which loads all the flags. A later provider with a different selection uses the first selection, until the last provider shuts down; the first such provider logs a warning, once per class loader.
* The `remote_config` source does not support a selection: the provider logs a warning and loads all the flags.
* With `dd-java-agent`, dropped and ignored selections are also counted in the agent health metrics.

## Exposures in your own data store

The provider sends exposures to Datadog. To also record exposures in your own data store, register `ExposureHook` from `dd-openfeature`. It receives every completed evaluation, with the same exposure decision that the provider uses for Datadog.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import com.datadog.openfeature.internal.FeatureFlagsRuntime;
import com.datadog.openfeature.internal.bridge.v1.AgentBridge;
import com.datadog.openfeature.internal.config.Settings;
import com.datadog.openfeature.internal.delivery.FlagSelectionRequest;
import com.datadog.openfeature.internal.evaluation.ConfigurationStore;
import com.datadog.openfeature.internal.evaluation.FlagEvaluator;
import com.datadog.openfeature.internal.exposure.ExposureDeduplicationCache;
Expand Down Expand Up @@ -79,6 +80,7 @@ class DDEvaluator implements Evaluator, Consumer<ServerConfiguration> {
private final Runnable configCallback;
private final AgentBridge bridge;
private final Settings settings;
private final FlagSelectionRequest flagSelection;
private final FlagEvaluator core;
private final ConfigurationStore configuration = new ConfigurationStore();
private volatile FeatureFlagsRuntime runtime;
Expand All @@ -92,9 +94,19 @@ class DDEvaluator implements Evaluator, Consumer<ServerConfiguration> {
final AgentBridge bridge,
final Settings settings,
final ExperimentationOptOutMode experimentationOptOutMode) {
this(configCallback, bridge, settings, experimentationOptOutMode, FlagSelectionRequest.NONE);
}

DDEvaluator(
final Runnable configCallback,
final AgentBridge bridge,
final Settings settings,
final ExperimentationOptOutMode experimentationOptOutMode,
final FlagSelectionRequest flagSelection) {
this.configCallback = configCallback;
this.bridge = bridge;
this.settings = settings;
this.flagSelection = flagSelection;
// When span enrichment is off, the __dd_* span-enrichment metadata is attached only to
// evaluations of allocations logging exposures, for the exposure hook.
this.core =
Expand All @@ -110,7 +122,7 @@ public boolean initialize(
if (this.runtime != null) {
return hasConfiguration();
}
acquired = FeatureFlagsRuntime.acquire(this.bridge, this.settings);
acquired = FeatureFlagsRuntime.acquire(this.bridge, this.settings, this.flagSelection);
this.runtime = acquired;
acquired.addConfigurationListener(this);
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
package com.datadog.openfeature;

import java.util.List;

/**
* The flags a provider loads: the flags that have any of the tags, or whose key matches any of the
* key patterns. A selection with neither loads all the flags.
*
* <p>Set it with {@link Provider.Options#flagSelection(FlagSelection)}.
*/
public final class FlagSelection {
List<String> tags;
List<String> keyPatterns;

/** Creates a selection with no tags and no key patterns. */
public FlagSelection() {}

/**
* Sets the tags. Tags match exactly and case-sensitively, and a flag matches when it has any of
* them.
*
* @param tags the tags, or {@code null} for none.
* @return this selection.
*/
public FlagSelection tags(final List<String> tags) {
this.tags = tags;
return this;
}

/**
* Sets the key patterns. A pattern matches the whole flag key, case-sensitively: {@code *}
* matches any run of characters, and every other character is literal.
*
* @param keyPatterns the key patterns, or {@code null} for none.
* @return this selection.
*/
public FlagSelection keyPatterns(final List<String> keyPatterns) {
this.keyPatterns = keyPatterns;
return this;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import com.datadog.openfeature.internal.bridge.v1.AgentBridge;
import com.datadog.openfeature.internal.bridge.v1.AgentBridges;
import com.datadog.openfeature.internal.config.Settings;
import com.datadog.openfeature.internal.delivery.FlagSelectionRequest;
import com.datadog.openfeature.internal.evaluation.ExperimentationOptOut;
import com.datadog.openfeature.internal.flagevaluation.FlagEvaluationWriter;
import dev.openfeature.sdk.ErrorCode;
Expand Down Expand Up @@ -44,6 +45,7 @@ public class Provider extends EventProvider implements Metadata {
private final AgentBridge bridge;
private final Settings settings;
private final ExperimentationOptOutMode experimentationOptOutMode;
private final FlagSelectionRequest flagSelection;
private final AtomicReference<InitializationState> initializationState =
new AtomicReference<>(InitializationState.NOT_STARTED);
private final FlagEvalMetrics flagEvalMetrics;
Expand Down Expand Up @@ -88,6 +90,11 @@ public Provider(final Options options) {
this.settings.isEnabled()
? ExperimentationOptOut.resolve(options.experimentationOptOutMode, this.settings)
: ExperimentationOptOutMode.DISABLED;
final FlagSelection selection = options.flagSelection;
this.flagSelection =
selection == null
? FlagSelectionRequest.NONE
: FlagSelectionRequest.of(selection.tags, selection.keyPatterns);
FlagEvalMetrics metrics = null;
FlagEvalMetricsHook hook = null;
try {
Expand Down Expand Up @@ -309,7 +316,11 @@ private Evaluator buildEvaluator() {
return evaluator;
}
return new DDEvaluator(
this::onConfigurationChange, this.bridge, this.settings, this.experimentationOptOutMode);
this::onConfigurationChange,
this.bridge,
this.settings,
this.experimentationOptOutMode,
this.flagSelection);
}

private FlagEvaluationWriter flagEvaluationPipeline() {
Expand Down Expand Up @@ -405,6 +416,7 @@ public static class Options {
private TimeUnit unit = SECONDS;
private Boolean evaluationTelemetryOptOutParameterEnabled;
private ExperimentationOptOutMode experimentationOptOutMode = ExperimentationOptOutMode.DEFAULT;
private FlagSelection flagSelection;

/**
* Sets per-subject experimentation opt-out. {@link ExperimentationOptOutMode#DEFAULT} reads
Expand Down Expand Up @@ -463,6 +475,34 @@ private boolean isEvaluationTelemetryOptOutParameterEnabled(final Settings setti
return settings.isEvaluationTelemetryPerSubjectOptOutEnabled();
}

/**
* Loads only the selected flags: the flags that have any of the selection's tags, or whose key
* matches any of its key patterns. Evaluating a flag outside the selection returns the default
* value with {@code FLAG_NOT_FOUND}. Without a selection, or with an empty one, all the flags
* are loaded.
*
* <p>Leading and trailing Unicode white space is trimmed from every value, empty values are
* dropped, and duplicates are removed. A null list is treated as absent. Each list accepts at
* most 31 values, and each tag and key pattern is at most 200 UTF-8 bytes after trimming. A
* selection over a limit, holding a null or non-String value or an unpaired UTF-16 surrogate,
* or making the request URL longer than 8192 bytes once percent-encoded, is not sent: the
* provider logs an error and loads all the flags. The server can also ignore a selection, and
* then returns all the flags.
*
* <p>The provider captures the selection at construction. The providers of a class loader share
* one flag configuration: the first provider initialized decides the selection until the last
* one shuts down, and a later provider with a different selection uses the first one. The first
* such provider logs a warning, once per class loader. The {@code remote_config} configuration
* source does not support a selection and loads all the flags.
*
* @param selection the flag selection, or {@code null} for all the flags.
* @return these options.
*/
public Options flagSelection(final FlagSelection selection) {
this.flagSelection = selection;
return this;
}

/**
* Sets how long provider initialization waits for the initial flag configuration.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
import com.datadog.openfeature.internal.delivery.CdnConfigurationSource;
import com.datadog.openfeature.internal.delivery.DirectIntakeTransport;
import com.datadog.openfeature.internal.delivery.FallbackTransport;
import com.datadog.openfeature.internal.delivery.FlagSelectionRequest;
import com.datadog.openfeature.internal.delivery.RemoteConfigurationService;
import com.datadog.openfeature.internal.exposure.ExposureDeduplicationCache;
import com.datadog.openfeature.internal.exposure.ExposureEvent;
Expand All @@ -32,7 +33,8 @@
* The Feature Flags runtime: configuration delivery and event pipelines. A single runtime is shared
* by all the providers of a class loader, and stopped when the last one releases it, or when the
* application shuts down: by the Datadog Java agent shutdown when attached, or by a JVM shutdown
* hook otherwise.
* hook otherwise. The flag selection of the provider that starts the runtime applies to all of
* them.
*/
public final class FeatureFlagsRuntime {
private static final Logger LOGGER = LoggerFactory.getLogger(FeatureFlagsRuntime.class);
Expand All @@ -42,6 +44,9 @@ public final class FeatureFlagsRuntime {
private static int references;

private final ConfigurationService source;
private final RuntimeServices services;
private final FlagSelectionRequest claimedSelection;
private final FlagSelectionRequest sentSelection;
private final ExposureDeduplicationCache exposureCache = new ExposureDeduplicationCache();
@Nullable private final ExposurePipeline exposures;
@Nullable private final FlagEvaluationPipeline evaluations;
Expand All @@ -50,31 +55,52 @@ public final class FeatureFlagsRuntime {
private final AtomicBoolean stopped = new AtomicBoolean();
@Nullable private volatile AutoCloseable shutdownRegistration;

/**
* @param claimedSelection the selection of the provider starting the runtime.
* @param sentSelection what the configuration source does with it: sends it, or reports why not.
*/
FeatureFlagsRuntime(
final ConfigurationService source,
final RuntimeServices services,
final FlagSelectionRequest claimedSelection,
final FlagSelectionRequest sentSelection,
@Nullable final ExposurePipeline exposures,
@Nullable final FlagEvaluationPipeline evaluations) {
this.source = source;
this.services = services;
this.claimedSelection = claimedSelection;
this.sentSelection = sentSelection;
this.exposures = exposures;
this.evaluations = evaluations;
}

/** Acquires the shared runtime for a provider without a flag selection. */
public static FeatureFlagsRuntime acquire(final AgentBridge bridge, final Settings settings) {
return acquire(bridge, settings, FlagSelectionRequest.NONE);
}

/**
* Acquires the shared runtime, starting it on first acquisition. Each acquisition must be paired
* with a {@link #release()}.
*
* @param bridge the bridge to the Datadog Java agent.
* @param settings the SDK settings.
* @param selection the flag selection of the acquiring provider. The first acquisition, which
* starts the runtime, claims its selection until the last release.
* @return the shared runtime.
* @throws IllegalStateException if Feature Flags is disabled or misconfigured.
*/
public static FeatureFlagsRuntime acquire(final AgentBridge bridge, final Settings settings) {
public static FeatureFlagsRuntime acquire(
final AgentBridge bridge, final Settings settings, final FlagSelectionRequest selection) {
synchronized (SHARED_LOCK) {
if (shared == null) {
final FeatureFlagsRuntime created = create(bridge, settings);
final FeatureFlagsRuntime created = create(bridge, settings, selection);
created.reportSelection(selection);
created.start();
created.registerShutdown(bridge);
shared = created;
} else {
shared.reportSelection(selection);
Comment thread
mark-caii marked this conversation as resolved.
Resolved
}
references++;
return shared;
Expand All @@ -95,6 +121,11 @@ public static void release() {
}

static FeatureFlagsRuntime create(final AgentBridge bridge, final Settings settings) {
return create(bridge, settings, FlagSelectionRequest.NONE);
}

static FeatureFlagsRuntime create(
final AgentBridge bridge, final Settings settings, final FlagSelectionRequest selection) {
final String sourceName = settings.configurationSource();
if (sourceName == null) {
throw new IllegalStateException("Feature Flags is disabled");
Expand All @@ -109,8 +140,14 @@ static FeatureFlagsRuntime create(final AgentBridge bridge, final Settings setti
LOGGER.debug("Feature Flags runtime starting: configurationSource={}", sourceName);
final RuntimeServices services = new RuntimeServices(bridge.healthMetrics());
final ConfigurationService source;
final FlagSelectionRequest sentSelection;
final EventTransport transport;
if (remoteConfig) {
// Before the connector check, so that the warning is logged when the provider falls back to
// the caller defaults too.
if (!selection.isNone()) {
FlagSelectionRequest.warnRemoteConfiguration();
}
final ConfigurationSource remoteConfiguration;
try {
remoteConfiguration = bridge.remoteConfiguration();
Expand All @@ -121,10 +158,13 @@ static FeatureFlagsRuntime create(final AgentBridge bridge, final Settings setti
throw new RemoteConfigurationUnavailableException(null);
}
source = new RemoteConfigurationService(remoteConfiguration);
sentSelection = FlagSelectionRequest.NONE;
// Remote Configuration never falls back to direct intake.
transport = bridge.eventProxy();
} else {
source = new CdnConfigurationSource(settings, services);
final CdnConfigurationSource cdn = new CdnConfigurationSource(settings, services, selection);
source = cdn;
sentSelection = cdn.selection();
final EventTransport proxy = bridge.eventProxy();
final EventTransport direct = DirectIntakeTransport.create(settings);
transport =
Expand All @@ -133,7 +173,7 @@ static FeatureFlagsRuntime create(final AgentBridge bridge, final Settings setti
if (transport == null) {
LOGGER.warn(
"Feature Flags event delivery is disabled: set DD_API_KEY or attach the Datadog Java agent");
return new FeatureFlagsRuntime(source, null, null);
return new FeatureFlagsRuntime(source, services, selection, sentSelection, null, null);
}
final Map<String, String> context = eventContext(settings);
final ExposurePipeline exposures =
Expand Down Expand Up @@ -161,7 +201,31 @@ static FeatureFlagsRuntime create(final AgentBridge bridge, final Settings setti
transport.getClass().getSimpleName(),
exposures != null ? "enabled" : "disabled",
evaluations != null ? "enabled" : "disabled");
return new FeatureFlagsRuntime(source, exposures, evaluations);
return new FeatureFlagsRuntime(
source, services, selection, sentSelection, exposures, evaluations);
}

/**
* Reports what happens to the selection of an acquiring provider: an equal selection is sent, or
* not, as the claimed one is. A different one is not used: it reports its own drop, and warns
* only if it would load other flags, since a dropped selection and no selection both load every
* flag. Remote Configuration uses no selection at all, so only its own warning applies.
*/
private void reportSelection(final FlagSelectionRequest selection) {
if (this.source instanceof RemoteConfigurationService) {
if (!selection.isNone()) {
FlagSelectionRequest.warnRemoteConfiguration();
}
return;
}
if (selection.equals(this.claimedSelection)) {
this.sentSelection.reportNotSent(this.services);
return;
}
selection.reportNotSent(this.services);
if (!selection.selectedFlags().equals(this.sentSelection.selectedFlags())) {
FlagSelectionRequest.warnSecondSelection();
Comment thread
mark-caii marked this conversation as resolved.
Resolved
}
}

/** Signals an unavailable RC connector before any runtime resources have been started. */
Expand Down
Loading
Loading