Skip to content

Commit 9dcbf77

Browse files
authored
feat: Count override-affected evaluations separately and send no individual events for them (#219)
## Summary The OVERRIDE specification marks an evaluation as override-affected when any definition it read came from the SDK's override store. Such an evaluation appears in summary events only: it produces no individual feature event and no debug event, whatever the flag's configuration requests, and it is counted in a separate summary counter that carries an `overrideAffected` marker, so override-affected and ordinary evaluations of the same flag, variation, and version are never collapsed together. - `Event.FeatureRequest` carries the marking as a boolean that the SDK sets from its evaluation result. The existing constructors keep working and leave it false; `toDebugEvent()` keeps the value. - `DefaultEventProcessor` keys individual feature event and debug event emission on the marking. Index events and summaries are unchanged. - `EventSummarizer` keeps a second set of counters per flag for marked evaluations, created on first use so unmarked flags pay nothing. `EventOutputFormatter` writes `overrideAffected: true` only on those counters, the same way the `unknown` marker is written. - `EventSummarizerInterface` gains the marker parameter and keeps the previous signature as a default method that delegates with false. Flag overrides are currently experimental and subject to change. The server SDK change that sets the marking depends on the release of this package. [SDK-3246](https://launchdarkly.atlassian.net/browse/SDK-3246) [SDK-3246]: https://launchdarkly.atlassian.net/browse/SDK-3246?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Overview** > Adds **override-affected** handling for flag evaluations tied to the experimental override store: `Event.FeatureRequest` carries an `overrideAffected` flag (existing constructors default to false). > > **`DefaultEventProcessor`** still summarizes and emits index events, but **suppresses individual feature and debug events** whenever `isOverrideAffected()` is true, regardless of `trackEvents` or debug configuration. > > **`EventSummarizer`** (and aggregated/per-context wrappers) buckets those evaluations in a **separate counter map** per flag so they are not merged with normal counts for the same version/variation; **`EventOutputFormatter`** emits `overrideAffected: true` only on those summary counters. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 0e7744f. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
1 parent 808b89f commit 9dcbf77

11 files changed

Lines changed: 379 additions & 42 deletions

File tree

‎lib/shared/internal/src/main/java/com/launchdarkly/sdk/internal/events/AggregatedEventSummarizer.java‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,11 @@ public void summarizeEvent(
3131
int variation,
3232
LDValue value,
3333
LDValue defaultValue,
34-
LDContext context
34+
LDContext context,
35+
boolean overrideAffected
3536
) {
36-
summarizer.summarizeEvent(timestamp, flagKey, flagVersion, variation, value, defaultValue, context);
37+
summarizer.summarizeEvent(timestamp, flagKey, flagVersion, variation, value, defaultValue, context,
38+
overrideAffected);
3739
}
3840

3941
@Override

‎lib/shared/internal/src/main/java/com/launchdarkly/sdk/internal/events/DefaultEventProcessor.java‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -544,8 +544,10 @@ private void processEvent(Event e, EventBuffer outbox) {
544544
if(!fe.isExcludeFromSummaries()) {
545545
outbox.addToSummary(fe);
546546
}
547-
addFullEvent = fe.isTrackEvents();
548-
if (shouldDebugEvent(fe)) {
547+
// An override-affected evaluation appears only in the summary counters. It produces no
548+
// individual feature event and no debug event, whatever the flag's configuration requests.
549+
addFullEvent = fe.isTrackEvents() && !fe.isOverrideAffected();
550+
if (!fe.isOverrideAffected() && shouldDebugEvent(fe)) {
549551
debugEvent = fe.toDebugEvent();
550552
}
551553
} else {
@@ -702,7 +704,8 @@ void addToSummary(Event.FeatureRequest e) {
702704
e.getVariation(),
703705
e.getValue(),
704706
e.getDefaultVal(),
705-
e.getContext()
707+
e.getContext(),
708+
e.isOverrideAffected()
706709
);
707710
}
708711

‎lib/shared/internal/src/main/java/com/launchdarkly/sdk/internal/events/Event.java‎

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ public static final class FeatureRequest extends Event {
155155
private final boolean debug;
156156
private final long samplingRatio;
157157
private final boolean excludeFromSummaries;
158+
private final boolean overrideAffected;
158159

159160
/**
160161
* Constructs a feature request event.
@@ -171,12 +172,14 @@ public static final class FeatureRequest extends Event {
171172
* @param trackEvents true if full event tracking is turned on for this flag
172173
* @param debugEventsUntilDate if non-null, the time until which event debugging should be enabled
173174
* @param debug true if this is a debugging event
174-
* @param excludeFromSummaries true to exclude the event from summaries
175175
* @param samplingRatio the sampling ratio for the event
176+
* @param excludeFromSummaries true to exclude the event from summaries
177+
* @param overrideAffected true if an override affected the evaluation; see {@link #isOverrideAffected()}
176178
*/
177179
public FeatureRequest(long timestamp, String key, LDContext context, int version, int variation, LDValue value,
178180
LDValue defaultVal, EvaluationReason reason, String prereqOf, boolean trackEvents,
179-
Long debugEventsUntilDate, boolean debug, long samplingRatio, boolean excludeFromSummaries) {
181+
Long debugEventsUntilDate, boolean debug, long samplingRatio, boolean excludeFromSummaries,
182+
boolean overrideAffected) {
180183
super(timestamp, context);
181184
this.key = key;
182185
this.version = version;
@@ -190,6 +193,32 @@ public FeatureRequest(long timestamp, String key, LDContext context, int version
190193
this.debug = debug;
191194
this.excludeFromSummaries = excludeFromSummaries;
192195
this.samplingRatio = samplingRatio;
196+
this.overrideAffected = overrideAffected;
197+
}
198+
199+
/**
200+
* Constructs a feature request event that no override affected.
201+
*
202+
* @param timestamp the timestamp in milliseconds
203+
* @param key the flag key
204+
* @param context the context associated with the event
205+
* @param version the flag version, or -1 if the flag was not found
206+
* @param variation the result variation, or -1 if there was an error
207+
* @param value the result value
208+
* @param defaultVal the default value passed by the application
209+
* @param reason the evaluation reason, if it is to be included in the event
210+
* @param prereqOf if this flag was evaluated as a prerequisite, this is the key of the flag that referenced it
211+
* @param trackEvents true if full event tracking is turned on for this flag
212+
* @param debugEventsUntilDate if non-null, the time until which event debugging should be enabled
213+
* @param debug true if this is a debugging event
214+
* @param samplingRatio the sampling ratio for the event
215+
* @param excludeFromSummaries true to exclude the event from summaries
216+
*/
217+
public FeatureRequest(long timestamp, String key, LDContext context, int version, int variation, LDValue value,
218+
LDValue defaultVal, EvaluationReason reason, String prereqOf, boolean trackEvents,
219+
Long debugEventsUntilDate, boolean debug, long samplingRatio, boolean excludeFromSummaries) {
220+
this(timestamp, key, context, version, variation, value, defaultVal, reason, prereqOf, trackEvents,
221+
debugEventsUntilDate, debug, samplingRatio, excludeFromSummaries, false);
193222
}
194223

195224
/**
@@ -311,6 +340,23 @@ public boolean isExcludeFromSummaries() {
311340
return excludeFromSummaries;
312341
}
313342

343+
/**
344+
* True if an override affected this evaluation. The override can be direct or transitive. It is
345+
* direct when the evaluated flag came from the SDK's override store. It is transitive when a
346+
* prerequisite flag at any depth, or a segment read during the evaluation, came from that store.
347+
* <p>
348+
* The event processor keys on this value alone. It produces no individual feature event and no
349+
* debug event for such an evaluation, and it counts the evaluation in a separate summary counter
350+
* that carries the override-affected marker.
351+
* <p>
352+
* Flag overrides are currently experimental and subject to change.
353+
*
354+
* @return true if an override affected the evaluation
355+
*/
356+
public boolean isOverrideAffected() {
357+
return overrideAffected;
358+
}
359+
314360
@Override
315361
public long getSamplingRatio() {
316362
return samplingRatio;
@@ -324,7 +370,7 @@ public long getSamplingRatio() {
324370
public FeatureRequest toDebugEvent() {
325371
return new FeatureRequest(getCreationDate(), getKey(), getContext(), getVersion(),
326372
getVariation(), getValue(), getDefaultVal(), getReason(), getPrereqOf(),
327-
false, null, true, samplingRatio, excludeFromSummaries);
373+
false, null, true, samplingRatio, excludeFromSummaries, overrideAffected);
328374
}
329375
}
330376

‎lib/shared/internal/src/main/java/com/launchdarkly/sdk/internal/events/EventOutputFormatter.java‎

Lines changed: 36 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -280,28 +280,11 @@ private void writeSummaryEvent(EventSummarizer.EventSummary summary, JsonWriter
280280
jw.name("counters");
281281
jw.beginArray();
282282

283-
for (int i = 0; i < flagInfo.versionsAndVariations.size(); i++) {
284-
int version = flagInfo.versionsAndVariations.keyAt(i);
285-
SimpleIntKeyedMap<CounterValue> variations = flagInfo.versionsAndVariations.valueAt(i);
286-
for (int j = 0; j < variations.size(); j++) {
287-
int variation = variations.keyAt(j);
288-
CounterValue counter = variations.valueAt(j);
289-
290-
jw.beginObject();
291-
292-
if (variation >= 0) {
293-
jw.name("variation").value(variation);
294-
}
295-
if (version >= 0) {
296-
jw.name("version").value(version);
297-
} else {
298-
jw.name("unknown").value(true);
299-
}
300-
writeLDValue("value", counter.flagValue, jw);
301-
jw.name("count").value(counter.count);
302-
303-
jw.endObject();
304-
}
283+
writeCounters(jw, flagInfo.versionsAndVariations, false);
284+
SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> overrideAffectedCounters =
285+
flagInfo.overrideAffectedVersionsAndVariationsIfAny();
286+
if (overrideAffectedCounters != null) {
287+
writeCounters(jw, overrideAffectedCounters, true);
305288
}
306289

307290
jw.endArray(); // end of "counters" array
@@ -312,6 +295,37 @@ private void writeSummaryEvent(EventSummarizer.EventSummary summary, JsonWriter
312295
jw.endObject(); // end of summary event object
313296
}
314297

298+
private void writeCounters(JsonWriter jw, SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> versionsAndVariations,
299+
boolean overrideAffected) throws IOException {
300+
for (int i = 0; i < versionsAndVariations.size(); i++) {
301+
int version = versionsAndVariations.keyAt(i);
302+
SimpleIntKeyedMap<CounterValue> variations = versionsAndVariations.valueAt(i);
303+
for (int j = 0; j < variations.size(); j++) {
304+
int variation = variations.keyAt(j);
305+
CounterValue counter = variations.valueAt(j);
306+
307+
jw.beginObject();
308+
309+
if (variation >= 0) {
310+
jw.name("variation").value(variation);
311+
}
312+
if (version >= 0) {
313+
jw.name("version").value(version);
314+
} else {
315+
jw.name("unknown").value(true);
316+
}
317+
// The override-affected marker is present only when true, like the unknown marker.
318+
if (overrideAffected) {
319+
jw.name("overrideAffected").value(true);
320+
}
321+
writeLDValue("value", counter.flagValue, jw);
322+
jw.name("count").value(counter.count);
323+
324+
jw.endObject();
325+
}
326+
}
327+
}
328+
315329
private void writeKindAndCreationDate(JsonWriter jw, String kind, long creationDate) throws IOException {
316330
jw.name("kind").value(kind);
317331
jw.name("creationDate").value(creationDate);

‎lib/shared/internal/src/main/java/com/launchdarkly/sdk/internal/events/EventSummarizer.java‎

Lines changed: 71 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,33 @@ void summarizeEvent(
4747
LDValue defaultValue,
4848
LDContext context
4949
) {
50-
eventsState.incrementCounter(flagKey, flagVersion, variation, value, defaultValue, context);
50+
summarizeEvent(timestamp, flagKey, flagVersion, variation, value, defaultValue, context, false);
51+
}
52+
53+
/**
54+
* Adds information about an evaluation to our counters. An override-affected evaluation is
55+
* counted in a separate counter from other evaluations of the same flag, version, and variation.
56+
*
57+
* @param timestamp the millisecond timestamp
58+
* @param flagKey the flag key
59+
* @param flagVersion the flag version, or -1 if the flag is unknown
60+
* @param variation the result variation, or -1 if none
61+
* @param value the result value
62+
* @param defaultValue the application default value
63+
* @param context the evaluation context
64+
* @param overrideAffected true if an override affected the evaluation
65+
*/
66+
void summarizeEvent(
67+
long timestamp,
68+
String flagKey,
69+
int flagVersion,
70+
int variation,
71+
LDValue value,
72+
LDValue defaultValue,
73+
LDContext context,
74+
boolean overrideAffected
75+
) {
76+
eventsState.incrementCounter(flagKey, flagVersion, variation, value, defaultValue, context, overrideAffected);
5177
eventsState.noteTimestamp(timestamp);
5278
}
5379

@@ -120,7 +146,8 @@ void incrementCounter(
120146
int variation,
121147
LDValue flagValue,
122148
LDValue defaultVal,
123-
LDContext context
149+
LDContext context,
150+
boolean overrideAffected
124151
) {
125152
FlagInfo flagInfo = counters.get(flagKey);
126153
if (flagInfo == null) {
@@ -131,10 +158,12 @@ void incrementCounter(
131158
flagInfo.contextKinds.add(context.getIndividualContext(i).getKind().toString());
132159
}
133160

134-
SimpleIntKeyedMap<CounterValue> variations = flagInfo.versionsAndVariations.get(flagVersion);
161+
SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> versionsAndVariations =
162+
overrideAffected ? flagInfo.overrideAffectedVersionsAndVariations() : flagInfo.versionsAndVariations;
163+
SimpleIntKeyedMap<CounterValue> variations = versionsAndVariations.get(flagVersion);
135164
if (variations == null) {
136165
variations = new SimpleIntKeyedMap<>();
137-
flagInfo.versionsAndVariations.put(flagVersion, variations);
166+
versionsAndVariations.put(flagVersion, variations);
138167
}
139168

140169
CounterValue value = variations.get(variation);
@@ -175,21 +204,55 @@ public int hashCode() {
175204

176205
static final class FlagInfo {
177206
final LDValue defaultVal;
207+
// Counters for evaluations that no override affected, keyed by version and then by variation.
178208
final SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> versionsAndVariations;
209+
// Counters for override-affected evaluations, with the same shape. Most flags never have any,
210+
// so the map is created on first use.
211+
private SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> overrideAffectedVersionsAndVariations;
179212
final Set<String> contextKinds;
180213

181214
FlagInfo(LDValue defaultVal, SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> versionsAndVariations,
182215
Set<String> contextKinds) {
216+
this(defaultVal, versionsAndVariations, null, contextKinds);
217+
}
218+
219+
FlagInfo(LDValue defaultVal, SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> versionsAndVariations,
220+
SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> overrideAffectedVersionsAndVariations,
221+
Set<String> contextKinds) {
183222
this.defaultVal = defaultVal;
184223
this.versionsAndVariations = versionsAndVariations;
224+
this.overrideAffectedVersionsAndVariations = overrideAffectedVersionsAndVariations;
185225
this.contextKinds = contextKinds;
186226
}
227+
228+
/**
229+
* Returns the counters for override-affected evaluations, creating the map on first use.
230+
*
231+
* @return the counters, never null
232+
*/
233+
SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> overrideAffectedVersionsAndVariations() {
234+
if (overrideAffectedVersionsAndVariations == null) {
235+
overrideAffectedVersionsAndVariations = new SimpleIntKeyedMap<>();
236+
}
237+
return overrideAffectedVersionsAndVariations;
238+
}
239+
240+
/**
241+
* Returns the counters for override-affected evaluations, or null if there are none.
242+
*
243+
* @return the counters or null
244+
*/
245+
SimpleIntKeyedMap<SimpleIntKeyedMap<CounterValue>> overrideAffectedVersionsAndVariationsIfAny() {
246+
return overrideAffectedVersionsAndVariations == null || overrideAffectedVersionsAndVariations.size() == 0
247+
? null : overrideAffectedVersionsAndVariations;
248+
}
187249

188250
@Override
189251
public boolean equals(Object other) { // used only in tests
190252
if (other instanceof FlagInfo) {
191253
FlagInfo o = (FlagInfo)other;
192254
return o.defaultVal.equals(this.defaultVal) && o.versionsAndVariations.equals(this.versionsAndVariations) &&
255+
Objects.equals(o.overrideAffectedVersionsAndVariationsIfAny(), this.overrideAffectedVersionsAndVariationsIfAny()) &&
193256
o.contextKinds.equals(this.contextKinds);
194257
}
195258
return false;
@@ -202,8 +265,10 @@ public int hashCode() { // used only in tests
202265

203266
@Override
204267
public String toString() { // used only in tests
205-
return "(default=" + defaultVal + ", counters=" + versionsAndVariations + ", contextKinds=" +
206-
String.join(",", contextKinds) + ")";
268+
return "(default=" + defaultVal + ", counters=" + versionsAndVariations +
269+
(overrideAffectedVersionsAndVariationsIfAny() == null ? "" :
270+
", overrideAffectedCounters=" + overrideAffectedVersionsAndVariations) +
271+
", contextKinds=" + String.join(",", contextKinds) + ")";
207272
}
208273
}
209274

‎lib/shared/internal/src/main/java/com/launchdarkly/sdk/internal/events/EventSummarizerInterface.java‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
*/
1616
public interface EventSummarizerInterface {
1717
/**
18-
* Adds information about an evaluation to the summary.
18+
* Adds information about an evaluation that no override affected to the summary.
1919
*
2020
* @param timestamp the millisecond timestamp
2121
* @param flagKey the flag key
@@ -25,14 +25,42 @@ public interface EventSummarizerInterface {
2525
* @param defaultValue the application default value
2626
* @param context the evaluation context
2727
*/
28-
void summarizeEvent(
28+
default void summarizeEvent(
2929
long timestamp,
3030
String flagKey,
3131
int flagVersion,
3232
int variation,
3333
LDValue value,
3434
LDValue defaultValue,
3535
LDContext context
36+
) {
37+
summarizeEvent(timestamp, flagKey, flagVersion, variation, value, defaultValue, context, false);
38+
}
39+
40+
/**
41+
* Adds information about an evaluation to the summary.
42+
* <p>
43+
* Override-affected evaluations are counted separately from other evaluations of the same flag,
44+
* version, and variation, so the marker takes part in the counter key.
45+
*
46+
* @param timestamp the millisecond timestamp
47+
* @param flagKey the flag key
48+
* @param flagVersion the flag version, or -1 if the flag is unknown
49+
* @param variation the result variation, or -1 if none
50+
* @param value the result value
51+
* @param defaultValue the application default value
52+
* @param context the evaluation context
53+
* @param overrideAffected true if an override affected the evaluation
54+
*/
55+
void summarizeEvent(
56+
long timestamp,
57+
String flagKey,
58+
int flagVersion,
59+
int variation,
60+
LDValue value,
61+
LDValue defaultValue,
62+
LDContext context,
63+
boolean overrideAffected
3664
);
3765

3866
/**

0 commit comments

Comments
 (0)