Handle incompatible OpenFeature SDK event APIs gracefully

[leoromanovsky]

What Does This Do

Prevents an incompatible OpenFeature SDK from letting provider-event linkage failures escape the Datadog configuration callback. The provider now emits one actionable warning with the loaded SDK version and upgrade requirement, while configuration delivery and flag evaluation can continue.

It also adds a dedicated compatibility job that continuously exercises the supported OpenFeature SDK and dd-java-agent version boundaries.

Motivation

dd-openfeature is compiled against OpenFeature SDK 1.20.1, where EventProvider.emit(...) returns Awaitable. OpenFeature SDK 1.15.1 exposes the same method with a void return type. If that unsupported SDK wins runtime dependency resolution, a configuration-change event raises NoSuchMethodError and interrupts the Remote Configuration callback.

The documented compatibility floor remains OpenFeature SDK 1.20.1 or later. An unsupported dependency should still fail gracefully and explain how to recover instead of repeatedly surfacing an uncaught linkage error. The supported dependency boundaries should also be tested explicitly so future SDK or agent changes cannot silently break them.

Changes

• Route ready, configuration-changed, and error events through a compatibility boundary.
• Contain provider-event LinkageErrors and emit a warning once per provider.
• Report the detected OpenFeature SDK version, the 1.20.1 minimum, and explicit upgrade guidance; retain the stack trace at debug level.
• Add focused unit coverage for containment and warning behavior.
• Add a Gradle compatibility suite that compiles against the supported API and runs with OpenFeature SDK 1.15.1 to reproduce the real return-type NoSuchMethodError.
• Add a dedicated test_openfeature_compatibility CI job with three integration lanes:
  • minimum supported OpenFeature SDK 1.20.1 with the development provider and agent;
  • latest stable OpenFeature SDK with the minimum supported 1.65.0 provider and agent;
  • latest stable OpenFeature SDK with the development provider and agent, running the full current smoke suite.

Decisions

• Keep OpenFeature SDK 1.20.1 as the support floor; this change does not claim compatibility with older SDKs.
• Contain the failure only at the provider-event boundary so configuration ingestion and evaluation are not discarded because event notification is incompatible.
• Warn once per provider to provide an actionable signal without flooding logs on every configuration update.
• Detect the loaded version from package metadata first and Maven pom.properties second, falling back to unknown without interfering with error handling.
• Resolve the latest upstream SDK dynamically while rejecting snapshots, so the compatibility job becomes an early warning when OpenFeature publishes a new stable release.
• Pair the minimum 1.65.0 agent with its matching published provider because their internal UFC API must stay aligned.
• Use a stable evaluation/exposure contract for cross-version lanes, while retaining the exhaustive current fixture and span-enrichment checks for the development/development lane.

Additional Notes

Validated with:

• ./gradlew :dd-smoke-tests:openfeature:openFeatureCompatibilityTest -PtestJvm=11 -PskipFlakyTests
  • OpenFeature SDK 1.20.1 + development provider/agent: passed.
  • OpenFeature SDK 1.22.1 + provider/agent 1.65.0: passed.
  • OpenFeature SDK 1.22.1 + development provider/agent: passed with the full smoke suite.
• ./gradlew :dd-smoke-tests:openfeature:test -PtestJvm=11 -PskipFlakyTests --rerun-tasks
• ./gradlew :products:feature-flagging:feature-flagging-api:spotlessCheck :products:feature-flagging:feature-flagging-api:test :products:feature-flagging:feature-flagging-api:legacyOpenFeatureSdkTest :products:feature-flagging:feature-flagging-api:forbiddenApisMain :products:feature-flagging:feature-flagging-api:spotbugsMain :dd-smoke-tests:openfeature:spotlessCheck -PtestJvm=11 -PskipFlakyTests
• 175 normal provider tests passed, plus the OpenFeature SDK 1.15.1 runtime compatibility test.
• The aggregate provider module check reaches and passes both test suites but fails the repository's pre-existing per-class JaCoCo gate. A clean master at 61071ab6829a6bd24465bb174b20bb99776e1106 produces the same eight coverage violations and rounded ratios.
• git diff --check

Contributor Checklist

• Format the title according to the contribution guidelines.
• Assign the required type: and comp: labels.
• Existing CODEOWNERS coverage applies to the added compatibility tests.
• The public compatibility documentation already requires OpenFeature SDK 1.20.1 or later; no configuration documentation change is needed.
• Once approved, use merge queue to merge the PR.

[dd-octo-sts]

🟢 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.83 s	14.78 s	[-0.3%; +1.1%] (no difference)
startup:insecure-bank:tracing:Agent	13.63 s	13.66 s	[-1.1%; +0.6%] (no difference)
startup:petclinic:appsec:Agent	17.03 s	16.89 s	[+0.1%; +1.5%] (maybe worse)
startup:petclinic:iast:Agent	16.99 s	17.07 s	[-1.3%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	16.80 s	16.80 s	[-1.1%; +1.1%] (no difference)
startup:petclinic:sca:Agent	17.05 s	16.79 s	[+0.4%; +2.7%] (maybe worse)
startup:petclinic:tracing:Agent	16.14 s	16.20 s	[-1.3%; +0.6%] (no difference)

Commit: 49824636 · 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.