Skip to content

Add a flag selection option to the OpenFeature provider - #13291

Merged
gh-worker-dd-mergequeue-cf854d[bot] merged 10 commits into
masterfrom
mark.cai/FFL-3572
Nov 16, 2026
Merged

gh-worker-dd-mergequeue-cf854d[bot] merged 10 commits into
masterfrom
mark.cai/FFL-3572

Conversation

@mark-caii

@mark-caii mark-caii commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

What Does This Do

Lets an application load only part of its flag configuration:

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

With a selection, the agentless configuration request carries repeated selected_flag_tags and selected_flag_key_patterns query parameters, and the provider serves only the flags the backend returns. A flag outside the selection evaluates to the default value with FLAG_NOT_FOUND. Without a selection, the request, the ETag handling and the loaded configuration are unchanged.

Motivation

A service that uses a few flags of a large Datadog project still downloads, parses and holds the whole flag configuration. A flag selection lets it fetch and keep only the flags it needs, which shrinks the payload and the memory it holds. The browser, iOS and Android SDKs already support it; this gives the Java server SDK the same option, with the same canonical form and diagnostics.

Additional Notes

  • Same canonical form as the other SDKs. Each list is trimmed of Unicode White_Space, deduplicated and sorted by UTF-8 bytes, then percent-encoded per RFC 3986. The JDK helpers don't fit: String.trim() and String.strip() each disagree with White_Space, String.compareTo sorts by UTF-16 code units, and URLEncoder is form encoding (+ for a space, * kept). FlagSelectionVectorsTest runs the 38 SDK cases of the shared flag-selection/selection-vectors.json and skips the 6 rawQuery cases, which test the server's percent-decoding. The ffe-system-test-data submodule moves from 8c4d241 to e8777633, a single commit that adds these vectors and their validator.
  • Invalid input never throws. A null selection or a null list means no selection. A null or non-String element (possible through a raw list) or an unpaired surrogate is malformed_selection. More than 31 values in a list, a value over 200 UTF-8 bytes, or a request URL over 8192 bytes also drops the selection. A dropped selection is not sent: the provider logs one error per provider initialization, naming the reason and the limit but never the values, and loads all the flags. For malformed_selection the limit text is the browser SDK's, with "lists" for the Java type: flagSelection must be an object with optional tags and keyPatterns string lists.
  • Selections the server ignores. The DD-Flag-Selection-Ignored response header is read only on a 200 to a request that carried a selection. Its value is kept only when it is exactly one of the five known reasons, and is unknown otherwise. It is logged once per reason, after the configuration is applied.
  • One selection per class loader. The providers of a class loader share one configuration runtime, so the first provider initialized claims the selection until the last provider shuts down. A provider without a selection claims too, meaning all the flags. A later provider with a different selection uses the first selection; the first such provider logs a warning, once per class loader. A custom configuration endpoint must forward the selected_flag_* query parameters and the DD-Flag-Selection-Ignored header.
  • Remote Config delivers the full configuration and does not support a selection. The first provider with a selection logs a warning, once per class loader, and no provider gets the second-selection warning, since no selection is in use.
  • Telemetry. flag_selection.dropped and flag_selection.ignored, tagged with reason, go through the existing health metrics once per reason, so they need dd-java-agent. Without the agent, the error logs are the only signal. The telemetry intake drops these two counts until they are registered there, which is separate work.
  • API. FlagSelection and Options.flagSelection are new public API, also on the deprecated datadog.trace.api.openfeature.Provider.Options alias. The option is set in code only: there is no environment variable or system property.
  • Test data pin. This PR and the bot bump Bump dd-smoke-tests/openfeature/src/test/resources/ffe-system-test-data from 8c4d241 to d8911fd #13183 both move the ffe-system-test-data submodule. Whichever merges second should take d8911fd, Bump dd-smoke-tests/openfeature/src/test/resources/ffe-system-test-data from 8c4d241 to d8911fd #13183's commit, whose flag-selection/ is identical to e8777633.
  • Known issues. ProviderTest.testNullConfigurationAfterReadyTransitionsToErrorAndRecovers failed once in a full local run of the module (a Mockito invocation count on a configuration-change handler) and passed in isolated runs on this branch and on master. The test and its no-selection path are unchanged here, so it looks like an existing timing flake.
  • Validation.
    • System-tests flag-selection suite (local, forced): tests/parametric/test_ffe/test_flag_selection.py from DataDog/system-tests at 43145a9454085892244bd237269df9bc2c66169c, against this branch at e3d668be4ca4b45f440e7187693a860bf34ccb30, loaded through binaries/ (the dd-java-agent, dd-trace-api and dd-openfeature jars built from this commit); the run reported the library as java@1.69.0-SNAPSHOT+e3d668be4c. Command: TEST_LIBRARY=java ./run.sh PARAMETRIC -F tests/parametric/test_ffe/test_flag_selection.py tests/parametric/test_ffe/test_flag_selection.py. Result: 12/12 pass (the 11 case files of the flag-selection evaluation suite (tags, key-patterns, tags-or-key-patterns, canonical-form, interior-whitespace-tag, selection-matches-no-flag, sdk-sends-selection-at-limits, server-ignores-selection, empty-selection, sdk-drops-too-many-values, sdk-drops-long-url) plus the ETag revalidation test). Regression check, all of tests/parametric/test_ffe/ without -F: 98 passed, 0 failed. Parametric-app wiring used locally: FeatureFlagEvaluatorController takes an optional /start body, stores the selection before the lazy client is first used, and calls Options.flagSelection(FlagSelection) by reflection so the app still compiles against released versions. The suite's manifest entry for this library is still missing_feature and the parametric-app wiring lands in a separate system-tests PR, so PR CI cannot show this run yet.
    • Staging end to end, at 31c92052b4, an earlier head of this branch: a staging end-to-end harness builds the provider with each selection against the staging backend. 11/11 cases pass direct and 13/13 through a recording proxy that checks the exact query sent; a negative control without the option loads every flag for all 8 selection cases.

Contributor Checklist

Jira ticket: FFL-3572

Move the ffe-system-test-data submodule from 8c4d241 to e8777633, which
adds the shared flag-selection/selection-vectors.json.

Environment: Datadog workspace
Provider.Options.flagSelection(FlagSelection) sends the selected tags and
key patterns on the agentless configuration request, so the provider loads
only the flags the backend returns. The selection is canonicalized and
validated as in the other Datadog SDKs and checked against the shared
flag-selection vectors. A selection that cannot be sent is dropped with an
error log and the full configuration is loaded; a selection the server
ignores is logged once per reason after the configuration is applied. The
first provider initialized in a class loader claims the selection until
the last provider shuts down.

Solves FFL-3572.

Environment: Datadog workspace
A provider joining a Remote Config runtime with a selection now logs the
Remote Config warning too, once per class loader, instead of only the
provider that started the runtime. Also write the White_Space set and the
non-ASCII test values as escapes, and cover the legacy Remote Config
setting and repeated polls over the URL limit.

Environment: Datadog workspace
@mark-caii mark-caii added type: feature Enhancements and improvements comp: openfeature OpenFeature tag: ai generated Largely based on code generated by an AI or LLM labels Nov 6, 2026 — with ddtool CLI
@datadog-datadog-us1-prod

datadog-datadog-us1-prod Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

🎯 Code Coverage (details)
• Patch Coverage: 97.44%
• Overall Coverage: 73.87% (+13.62%)

This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 7b0cd97 | Docs | Give us feedback!

@mark-caii mark-caii added the crucible: reviewing A Crucible review has started; this PR has reviewer attention. label Nov 6, 2026 — with ddtool CLI
Copy the arrays a selection list returns, so a list breaking the
toArray contract is malformed input instead of a NullPointerException.
Cover the Remote Config warning for an invalid selection, a joining
provider with a different dropped selection, the once-per-reason counts
across reasons and kinds, the deprecated alias return type and an
encoded endpoint path. Document the URL-length drop, the once per class
loader second-selection warning and the query parameters a custom
endpoint must forward, and use a non-team tag in examples.

Environment: Datadog workspace
Remote Configuration delivers the full configuration and uses no flag
selection, so a later provider with a different selection only gets the
Remote Config warning: "Using the first selection" would be inaccurate.

Environment: Datadog workspace
@mark-caii
mark-caii marked this pull request as ready for review November 6, 2026 20:10
@mark-caii
mark-caii requested review from a team as code owners November 6, 2026 20:10
@mark-caii
mark-caii requested review from ValentinZakharov and removed request for a team November 6, 2026 20:10
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-06T20:15:11.801933Z 0f4d62b Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f4d62b6bf

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@datadog-datadog-us1-prod datadog-datadog-us1-prod Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bits Code Review: PASS

More details

Validation is limited to source review: backend interoperability remains unverified, and the shared canonicalization vectors could not be inspected because the test-data submodule was unavailable.

Was this helpful? React 👍 or 👎

Open Bits AI session

🤖 Bits Code Review · Commit 0f4d62b

@mark-caii mark-caii removed the crucible: reviewing A Crucible review has started; this PR has reviewer attention. label Nov 10, 2026
@DataDog DataDog deleted a comment from dd-octo-sts Bot Nov 10, 2026
@dougqh

dougqh commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

A broader note about dd-openfeature. This is not something to handle in this PR, just context for a separate follow-up.

catch (LinkageError) guards. The module has about 20 of these. They came from a period before the SDK/agent version rules were defined, and catching LinkageError was a way to stop the bleeding. With the versioned bridge in place, a guard only makes sense at a real version-skew boundary: calls across the agent bridge, the app's OpenTelemetry API version (for example getOrNoop(), added in 1.57), and possibly the app's dev.openfeature:sdk version. This PR copies the pattern into the logging helpers in FlagSelectionRequest. There it protects nothing: the slf4j methods used exist in 1.x and 2.x, and if slf4j were missing the class would already fail when its static LOGGER loads. The guard around the metric call crosses the bridge, so that one is fine. No need to change this here; I mention it so the pattern doesn't keep spreading.

Dependencies. I think a standalone SDK like this should have no dependencies of its own, or bundle (shade) the ones it needs:

  • dev.openfeature:sdk and opentelemetry-api are fine as they are. They have to be the app's own copies: one is the interface the provider implements, and the other has to reach the app's GlobalOpenTelemetry.
  • jackson-core is declared api but is only used in two internal classes (JsonWriting, UniversalFlagConfigParser). It could be shaded, or replaced with the repo's dependency-free components/json, so it stops showing up in every customer's dependency resolution.
  • slf4j is not declared at all. It arrives through the OpenFeature SDK, and the module uses it because it is there. The JDK's System.Logger (Java 9+; this module targets 11), or sending logs through the agent bridge when the agent is attached, would remove that coupling.

Again, none of this blocks this PR. It should be a separate piece of work.

Encode each value to UTF-8 once and reuse it for the size check and the
request URL, replace the toArray() copy with a null check, hash without a
varargs array, and stop asserting exact vector counts so new cases in the
shared test data do not break the test.

Environment: Datadog workspace

Copy link
Copy Markdown
Contributor Author

@dougqh Thanks for the context on the LinkageError guards and the module's dependencies. Agreed it's out of scope here; we'll take it up as a separate follow-up for dd-openfeature.

— Claude Code working with Mark

@leoromanovsky leoromanovsky left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One additional finding from the HTTP reproduction.

Read every DD-Flag-Selection-Ignored field and join repeated fields with
", ", the way the other SDKs read them, so duplicates and an empty first
field report unknown instead of taking only the first value. The test
server can now send a header name more than once.

Environment: Datadog workspace
@leoromanovsky
leoromanovsky self-requested a review November 12, 2026 15:47
…flags differ

A provider joining the shared runtime with a selection that differs from the
claimed one now logs and counts its own drop (malformed or over a limit), and
gets the "differs" warning only when it would load different flags than the
runtime does. A dropped selection and no selection both load every flag, so
they no longer trigger a false "differs".

Environment: Datadog workspace
@DataDog DataDog deleted a comment from dd-octo-sts Bot Nov 16, 2026
@DataDog DataDog deleted a comment from dd-octo-sts Bot Nov 16, 2026
Take master's ffe-system-test-data pointer (6df74e6), which already
contains the PR's pointer (e877763).
@dd-octo-sts

dd-octo-sts Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite Status
Startup 🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results
Scenario Candidate master Δ (95% CI of mean)
startup:insecure-bank:iast:Agent 14.82 s 14.71 s [+0.0%; +1.5%] (maybe worse)
startup:insecure-bank:tracing:Agent 13.59 s 13.66 s [-1.3%; +0.2%] (no difference)
startup:petclinic:appsec:Agent 17.19 s 17.01 s [+0.2%; +1.8%] (maybe worse)
startup:petclinic:iast:Agent 16.96 s 17.08 s [-1.6%; +0.2%] (no difference)
startup:petclinic:profiling:Agent 16.62 s 16.77 s [-1.9%; +0.1%] (no difference)
startup:petclinic:sca:Agent 17.14 s 16.85 s [+0.8%; +2.7%] (maybe worse)
startup:petclinic:tracing:Agent 15.71 s 16.20 s [-7.2%; +1.2%] (no difference)

Commit: 7b0cd978 · CI Pipeline · Benchmarking Platform UI


Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

Copy link
Copy Markdown
Contributor Author

/merge

@gh-worker-devflow-routing-ef8351

gh-worker-devflow-routing-ef8351 Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

View all feedbacks in Devflow UI.

2026-11-16 16:44:40 UTC ℹ️ Start processing command /merge


2026-11-16 16:44:44 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 1h (p90).


2026-11-16 17:38:47 UTC ℹ️ MergeQueue: This merge request was merged

@mark-caii
mark-caii added this pull request to the merge queue Nov 16, 2026
@dd-octo-sts

dd-octo-sts Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

/merge

@gh-worker-devflow-routing-ef8351

gh-worker-devflow-routing-ef8351 Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

View all feedbacks in Devflow UI.

2026-11-16 16:48:48 UTC ℹ️ Start processing command /merge


2026-11-16 16:48:50 UTC ❌ MergeQueue

PR already in the queue with status in_progress

@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 16, 2026
@gh-worker-dd-mergequeue-cf854d
gh-worker-dd-mergequeue-cf854d Bot merged commit 88ee6a6 into master Nov 16, 2026
686 checks passed
@gh-worker-dd-mergequeue-cf854d
gh-worker-dd-mergequeue-cf854d Bot deleted the mark.cai/FFL-3572 branch November 16, 2026 17:38
@github-actions github-actions Bot added this to the 1.70.0 milestone Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp: openfeature OpenFeature tag: ai generated Largely based on code generated by an AI or LLM type: feature Enhancements and improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants