feat: add per-hook evaluation exposure deduplication

[abelonogov-ld]

Summary

Apps that evaluate a flag on every render or inside a loop invoke their hooks for each call, even when the evaluation resolves to the same result every time. This lets a hook ask for a dedupe window so those redundant evaluation series are collapsed.

Only hooks are affected. Analytics events are untouched — feature, debug, and summary events are still recorded for every evaluation, so the evaluation counts LaunchDarkly reports for your flags do not change.

Deduplication is opt-in per hook, and there is no client-wide setting. A hook observes every evaluation until it carries a deduper, so an audit hook can see everything while an observability hook on the same client keeps a long window:

Components.hooks()
    .addHook(new MetricsHook())                                                                // every evaluation
    .addHook(new AuditHook().evaluationExposureDeduper(EvaluationExposureDeduper.disabled()))   // every evaluation, said explicitly
    .addHook(new ObservabilityHook().evaluationExposureDeduper(30_000, 5_000))                  // SDK deduper, own parameters
    .addHook(new ExperimentHook().evaluationExposureDeduper(myCustomDeduper))                   // custom policy

Behavior when a hook carries a window:

• The hook observes an evaluation at most once per window per unique result, keyed on flag key, variation, event version, experiment status, and the fully qualified context key.
• Suppression covers the whole evaluation series: a suppressed evaluation invokes neither beforeEvaluation nor afterEvaluation, so a hook that pairs its stages never sees an unmatched before.
• Each hook is deduplicated independently, so one hook observing an evaluation never suppresses it for another.
• identify clears every hook's deduper, even when the context is unchanged, so identify stays a reliable way for an app to mark a new phase of a session.

This started as a port of flagExposureDedupeWindowMillis from the Web Observability SDK, moved down to the flag SDK level. Companion PR for the iOS SDK: launchdarkly/ios-client-sdk#516

What changed since the first revision

Reviewers who read an earlier description will find three design decisions reversed:

1. Deduplication moved off the event pipeline and onto hooks. It originally suppressed the feature event and the summary event together, which reduced volume the most but also dropped the evaluation counts LaunchDarkly reports. The telemetry the feature is really aimed at is produced by hooks, so gating hooks alone gets the volume reduction without touching what LaunchDarkly reports.
2. The window became a per-hook policy rather than one client-wide setting. A single window forces unrelated hooks to share a deduplication policy, which does not hold up once an app registers hooks with different purposes alongside the observability plugin's.
3. The LDConfig options are gone entirely, and the default is now no deduplication. They survived the previous revision as the fallback for hooks that carried no policy, which meant registering any hook opted it into suppression decided elsewhere in the config. Deduplication is a property of what a hook does with an evaluation, so the hook is now the only place that decides.

EvaluationExposureDeduper.disabled() is therefore equivalent to carrying no deduper. It stays because passing it states the intent explicitly, and because HookRunner recognizes it by identity to skip building exposure keys.

Notes for reviewers

• The decision is made before the series opens, not after the evaluation completes. The mobile observability plugins start a span in beforeEvaluation and end it in afterEvaluation, parking it in a bounded map keyed by an evaluation id. Suppressing only the after stage would leave those spans in the map until eviction force-ended them, producing spans with nonsense durations and no feature_flag event — the same span count as no deduplication, but mostly junk. So HookRunner picks the hooks for an evaluation up front, reading the stored flag to identify the exposure. The stored flag identifies the same exposure the result would, since the result is derived from it.
• This is also why the key cannot come from the evaluation result. The decision precedes the evaluation, so LDClient.exposureKey pre-reads the flag and HookRunner.ExposureKeySupplier exists as the seam. Dropping either would mean either splitting a hook's stages or dropping the version component, and without variation and version a mid-window flag change would go unobserved, since nothing resets the cache except identify.
• Experiment status is its own key component. versionForEvents prefers flagVersion, which only moves when the flag itself changes, so a prerequisite flipping can move an evaluation into or out of an experiment while it lands on the same variation of the same flag version. Without this component, that transition would be suppressed.
• Two hooks given the same deduper instance share its window, so whichever one is told about an evaluation first suppresses it for the other. That is deliberate and documented on the setter, and HookRunnerTest pins it down; give each hook its own instance unless you want that.
• EvaluationExposureDeduper lives in the integrations package and is public, so it can be constructed with different parameters, opted out of with disabled(), or replaced by a subclass. It owns its own DEFAULT_MAX_SIZE and no longer depends on LDConfig. The exposure key it is handed stays internal, in EvaluationExposureKey.
• The fluent setter on Hook also covers plugin-provided hooks, which are returned from Plugin.getHooks() and never pass through HooksConfigurationBuilder.addHook.
• The deduper synchronizes internally, since variationDetail can be called from any thread. shouldRecord combines the check and the mark in one atomic step so two concurrent evaluations of the same flag cannot both be told to record.
• Eviction uses a LinkedHashMap and drops expired entries before falling back to dropping the oldest, in a batch, so a workload with more live keys than the cap doesn't pay for a scan on every exposure. It returns early once reclaiming expired keys brings the map back within the cap, so live keys are never discarded needlessly.
• Named after evaluations, not flags. The Web Observability SDK calls this flagExposureDedupeWindowMillis, but flag carries no information inside a flag SDK, and the local vocabulary is already "evaluation" (recordEvaluationEvent, EvaluationDetail, evaluation events).
• The window is in milliseconds here, but in seconds on iOS. Each SDK follows its own convention: this one names durations ...Millis (pollIntervalMillis, connectTimeoutMillis, flushIntervalMillis), while every duration on iOS's LDConfig is a TimeInterval in seconds.
• The example app is included, so the feature can be exercised on a device. It reads its mobile key and a production/staging switch from local.properties, and registers two hooks with different windows so the display shows them suppressing independently.

Known limitation

The key has no notion of where a flag was read, so two evaluations from different code paths that land on the same variation collapse into one. For a hook counting exposures that is correct, since the exposure belongs to the user and the variation. For a hook building traces it means a span can be missing a flag it depended on, and because it depends on the window, the gap is timing-sensitive. A hook that needs per-operation fidelity can subclass the deduper and fold the active span id into the key, which reduces suppression to repeats within one span, where the first read has already annotated that span. Whether the SDK should offer that scope as a first-class concept is left for a follow-up.

Test plan

• EvaluationExposureDeduperTest — 12 unit tests covering the disabled instance, suppression, window expiry, independent keys, reset, eviction, re-recording, keeping live keys when reclaiming expired ones suffices, key construction, and concurrent access
• HookRunnerTest — 28 unit tests covering per-hook dedupers, a hook without one observing everything, independent suppression between hooks, two hooks sharing one deduper, reset, exposure key lookup and the fast path that skips it, and hooks added after initialization
• LDClientHooksTest — 8 instrumented tests covering the end-to-end path: deduplication being off unless a hook asks for it, suppression within a hook's window, re-reporting after identify, different flags tracked separately, and three hooks with different policies on one client suppressing independently
• LDClientEventTest — instrumented test asserting evaluation events are still recorded for evaluations that were deduplicated for hooks
• ./gradlew :launchdarkly-android-client-sdk:testDebugUnitTest: 713 tests, 0 failures (StreamingDataSourceTest.startSendsRequestWithoutReasonsWhenDisabled is flaky and unrelated; it passes on re-run)
• ./gradlew :launchdarkly-android-client-sdk:javadoc: no unresolved references
• Instrumented tests run on an emulator, green
• Example app builds and runs against a real environment

---

Note

Medium Risk
Touches core evaluation and hook paths in HookRunner and LDClient (including pre-evaluation exposure keys and identify resets); behavior is well covered by tests but incorrect dedupe could affect observability hooks in production.

Overview
Adds opt-in, per-hook deduplication so repeated flag evaluations that resolve to the same exposure can skip the hook’s full beforeEvaluation / afterEvaluation series within a configurable time window—without changing LaunchDarkly analytics event counts.

Hooks opt in via fluent Hook#evaluationExposureDeduper(...) (default window/cap, custom millis + max keys, custom EvaluationExposureDeduper, or disabled()). HookRunner decides which hooks run before the evaluation series opens, using EvaluationExposureKey (environment, flag, variation, event version, experiment status, context). LDClient#identify clears all hook dedupe caches, including when the context is unchanged.

The example app loads mobile key and staging endpoints from local.properties, registers two hooks with different windows, and surfaces live dedupe stats. HooksConfigurationBuilder gains addHook.

^{Reviewed by Cursor Bugbot for commit f46f1c9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

Some SDKs used to have functionality like this and it was removed. Not all data is available in the client as to which events matter when. Like an experiment iteration. So we don't dedupe events. We can offer ways and guidance about how to avoid these situations. And you are welcome to de-dupe obersavability data.

[abelonogov-ld]

Some SDKs used to have functionality like this and it was removed. Not all data is available in the client as to which events matter when. Like an experiment iteration. So we don't dedupe events. We can offer ways and guidance about how to avoid these situations. And you are welcome to de-dupe obersavability data.

@kinyoklion Sure, I am not going to dedup events at all, it should only dedup evaluation hook call. I will removes events from it. I feel this functionality where triggered by a customer story

[tanderson-ld]

it should only dedup evaluation hook call

I'm not sure I agree with this. I think we should put this dedupe logic in as narrow a spot and as close to the consumer as possible since it does result in loss of information. If you want one hook to get all evals and another to get deduped, configuring it at the top level doesn't work.

Can you make a hook decorator that does the deduping and you just wrap your hook in deduping decoration if you want it?

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a6600c1. Configure here.}

[tanderson-ld]

I still prefer decoration with static helpers to increasing the amount of functionality in the Hook abstract class.

[tanderson-ld]

Making a string for this isn't efficient is it? Can't this just a be a class/struct depending on the language this will be done in?