test(ffe): specify exposure and metric semantics

[leoromanovsky]

Motivation

This is PR E in the PHP OpenFeature compatibility stack. PR B adds the PHP 7-safe Datadog feature flag client; this PR specifies the exposure and feature_flag.evaluations metric behavior that the client should drive while native delivery remains gated.

The native exposure buffer, EVP/sidecar flush path, and OpenTelemetry-backed metric exporter are intentionally not implemented here. This PR gives reviewers a small, runnable contract for event shape, deduplication, batch flush, and metric gating without forcing PHP 7 users to install PHP 8-only telemetry packages.

Changes

• Add injectable ExposureWriter and MetricsRecorder contracts with no-op defaults.
• Add BufferedExposureWriter for contract tests around exposure event batching, duplicate suppression, changed assignment re-emission, and empty flush behavior.
• Add CallableMetricsRecorder for contract tests around feature_flag.evaluations attributes and DD_METRICS_OTEL_ENABLED gating.
• Wire DDTrace\FeatureFlags\Client to record one metric per evaluation and write exposure events only for successful evaluations with exposure data and doLog != false.
• Add tests for exposure event shape, doLog=false, provider-not-ready/error skip behavior, duplicate suppression, changed variant/allocation re-emission, batch cap flush, metric success/error/provider-not-ready paths, and root Composer dependency guardrails.

Decisions

• Keep native delivery gated; these writer/recorder contracts are test sinks until the runtime bridge and sidecar/EVP flush path exist.
• Keep metrics optional and callable-based here; root composer.json still does not require open-telemetry/sdk.
• Keep default client behavior no-op for exposures and metrics unless a writer/recorder is injected.
• Stack this PR on PR B so it can use the PHP 7 client and evaluator details contract.

Reference

• Shared PHP OpenFeature compatibility plan: https://docs.google.com/document/d/1NvMfTpZWLBlFmEFNjdnlMyeVpy5l7KD8qujGFco6w2w/edit?tab=t.0

Verification

• find src/api/FeatureFlags tests/api/Unit/FeatureFlags -name '*.php' -print0 | xargs -0 -n1 php -n -l
• php -n vendor/bin/phpunit --config=phpunit.xml tests/api/Unit/FeatureFlags
• vendor/bin/phpunit --config=phpunit.xml tests/api/Unit/FeatureFlags
• vendor/bin/phpcs -s src/api/FeatureFlags tests/api/Unit/FeatureFlags

[datadog-prod-us1-4]

 

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 4 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-php | test_extension_ci: [7.4]     

🔄 Retry job. This looks flaky and may succeed on retry.

Process timed out during installation of the live debugger log probe.

DataDog/apm-reliability/dd-trace-php | test_extension_ci: [8.1]     

🔄 Retry job. This looks flaky and may succeed on retry.

Fatal error: Uncaught Exception: wait for replay timeout in request_replayer.inc:100

DataDog/apm-reliability/dd-trace-php | test_extension_ci: [8.2]     

🔄 Retry job. This looks flaky and may succeed on retry.

Job failed due to timeout while installing a live debugger log probe: process timed out.

View all 4 failed jobs.

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 60.70% (-0.05%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 24d062a | Docs | Datadog PR Page | Give us feedback!}

[pr-commenter]

Benchmarks [ tracer ]

Benchmark execution time: 2026-05-21 23:10:03

Comparing candidate commit 24d062a in PR branch leo.romanovsky/pr-e-exposure-metrics with baseline commit cb48670 in branch leo.romanovsky/pr-b-feature-flags-client.

Found 1 performance improvements and 4 performance regressions! Performance is the same for 187 metrics, 2 unstable metrics.

scenario:MessagePackSerializationBench/benchMessagePackSerialization-opcache

• 🟩 execution_time [-3.654µs; -2.086µs] or [-3.512%; -2.005%]

scenario:SamplingRuleMatchingBench/benchRegexMatching1

• 🟥 execution_time [+74.428ns; +135.572ns] or [+5.118%; +9.323%]

scenario:SamplingRuleMatchingBench/benchRegexMatching3

• 🟥 execution_time [+49.156ns; +117.844ns] or [+3.337%; +7.999%]

scenario:SamplingRuleMatchingBench/benchRegexMatching4

• 🟥 execution_time [+51.351ns; +119.049ns] or [+3.488%; +8.085%]

scenario:TraceAnnotationsBench/benchTraceAnnotationOverhead-opcache

• 🟥 execution_time [+4.335µs; +12.046µs] or [+2.431%; +6.755%]