feat: Add optional support for per-context summary events.

Author: kinyoklion

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

@@ -363,7 +363,7 @@ public Thread newThread(Runnable r) {
       // all the workers are busy.
       final BlockingQueue<FlushPayload> payloadQueue = new ArrayBlockingQueue<>(1);
 
-      final EventBuffer outbox = new EventBuffer(eventsConfig.capacity, logger);
+      final EventBuffer outbox = new EventBuffer(eventsConfig.capacity, eventsConfig.perContextSummarization, logger);
       this.contextDeduplicator = eventsConfig.contextDeduplicator;
 
       Thread mainThread = threadFactory.newThread(new Thread() {
@@ -608,7 +608,13 @@ private void triggerFlush(EventBuffer outbox, BlockingQueue<FlushPayload> payloa
       }
       FlushPayload payload = outbox.getPayload();
       if (diagnosticStore != null) {
-        int eventCount = payload.events.length + (payload.summary.isEmpty() ? 0 : 1);
+        int summaryCount = 0;
+        for (EventSummary summary : payload.summaries) {
+          if (!summary.isEmpty()) {
+            summaryCount++;
+          }
+        }
+        int eventCount = payload.events.length + summaryCount;
         diagnosticStore.recordEventsInBatch(eventCount);
       }
       busyFlushWorkersCount.incrementAndGet();
@@ -618,7 +624,10 @@ private void triggerFlush(EventBuffer outbox, BlockingQueue<FlushPayload> payloa
       } else {
         logger.debug("Skipped flushing because all workers are busy");
         // All the workers are busy so we can't flush now; keep the events in our state
-        outbox.summarizer.restoreTo(payload.summary);
+        // Only restore if using single summarizer (not per-context)
+        if (outbox.summarizer != null && !payload.summaries.isEmpty()) {
+          outbox.summarizer.restoreTo(payload.summaries.get(0));
+        }
         synchronized(busyFlushWorkersCount) {
           busyFlushWorkersCount.decrementAndGet();
           busyFlushWorkersCount.notify();
@@ -661,15 +670,25 @@ public void run() {
 
   private static final class EventBuffer {
     final List<Event> events = new ArrayList<>();
-    final EventSummarizer summarizer = new EventSummarizer();
+    final EventSummarizer summarizer; // used when perContextSummarization is false
+    final MultiContextEventSummarizer multiContextSummarizer; // used when perContextSummarization is true
+    private final boolean perContextSummarization;
     private final int capacity;
     private final LDLogger logger;
     private boolean capacityExceeded = false;
     private long droppedEventCount = 0;
 
-    EventBuffer(int capacity, LDLogger logger) {
+    EventBuffer(int capacity, boolean perContextSummarization, LDLogger logger) {
       this.capacity = capacity;
+      this.perContextSummarization = perContextSummarization;
       this.logger = logger;
+      if (perContextSummarization) {
+        this.summarizer = null;
+        this.multiContextSummarizer = new MultiContextEventSummarizer();
+      } else {
+        this.summarizer = new EventSummarizer();
+        this.multiContextSummarizer = null;
+      }
     }
 
     void add(Event e) {
@@ -686,19 +705,35 @@ void add(Event e) {
     }
 
     void addToSummary(Event.FeatureRequest e) {
-      summarizer.summarizeEvent(
-          e.getCreationDate(),
-          e.getKey(),
-          e.getVersion(),
-          e.getVariation(),
-          e.getValue(),
-          e.getDefaultVal(),
-          e.getContext()
-          );
+      if (perContextSummarization) {
+        multiContextSummarizer.summarizeEvent(
+            e.getCreationDate(),
+            e.getKey(),
+            e.getVersion(),
+            e.getVariation(),
+            e.getValue(),
+            e.getDefaultVal(),
+            e.getContext()
+            );
+      } else {
+        summarizer.summarizeEvent(
+            e.getCreationDate(),
+            e.getKey(),
+            e.getVersion(),
+            e.getVariation(),
+            e.getValue(),
+            e.getDefaultVal(),
+            e.getContext()
+            );
+      }
     }
 
     boolean isEmpty() {
-      return events.isEmpty() && summarizer.isEmpty();
+      if (perContextSummarization) {
+        return events.isEmpty() && multiContextSummarizer.isEmpty();
+      } else {
+        return events.isEmpty() && summarizer.isEmpty();
+      }
     }
 
     long getAndClearDroppedCount() {
@@ -709,23 +744,33 @@ long getAndClearDroppedCount() {
 
     FlushPayload getPayload() {
       Event[] eventsOut = events.toArray(new Event[events.size()]);
-      EventSummarizer.EventSummary summary = summarizer.getSummaryAndReset();
-      return new FlushPayload(eventsOut, summary);
+      List<EventSummarizer.EventSummary> summaries;
+      if (perContextSummarization) {
+        summaries = multiContextSummarizer.getSummariesAndReset();
+      } else {
+        EventSummarizer.EventSummary summary = summarizer.getSummaryAndReset();
+        summaries = java.util.Collections.singletonList(summary);
+      }
+      return new FlushPayload(eventsOut, summaries);
     }
 
     void clear() {
       events.clear();
-      summarizer.clear();
+      if (perContextSummarization) {
+        multiContextSummarizer.clear();
+      } else {
+        summarizer.clear();
+      }
     }
   }
 
   private static final class FlushPayload {
     final Event[] events;
-    final EventSummary summary;
+    final List<EventSummary> summaries;
 
-    FlushPayload(Event[] events, EventSummary summary) {
+    FlushPayload(Event[] events, List<EventSummary> summaries) {
       this.events = events;
-      this.summary = summary;
+      this.summaries = summaries;
     }
   }
 
@@ -774,7 +819,7 @@ public void run() {
         try {
           ByteArrayOutputStream buffer = new ByteArrayOutputStream(INITIAL_OUTPUT_BUFFER_SIZE);
           Writer writer = new BufferedWriter(new OutputStreamWriter(buffer, Charset.forName("UTF-8")), INITIAL_OUTPUT_BUFFER_SIZE);
-          int outputEventCount = formatter.writeOutputEvents(payload.events, payload.summary, writer);
+          int outputEventCount = formatter.writeOutputEvents(payload.events, payload.summaries, writer);
           writer.flush();
           EventSender.Result result = eventsConfig.eventSender.sendAnalyticsEvents(
               buffer.toByteArray(),

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

@@ -11,6 +11,7 @@
 
 import java.io.IOException;
 import java.io.Writer;
+import java.util.List;
 import java.util.Map;
 
 import static com.launchdarkly.sdk.internal.GsonHelpers.gsonInstance;
@@ -33,7 +34,7 @@ final class EventOutputFormatter {
         config.privateAttributes.toArray(new AttributeRef[config.privateAttributes.size()]));
   }
 
-  int writeOutputEvents(Event[] events, EventSummarizer.EventSummary summary, Writer writer) throws IOException {
+  int writeOutputEvents(Event[] events, List<EventSummarizer.EventSummary> summaries, Writer writer) throws IOException {
     int count = 0;
     JsonWriter jsonWriter = new JsonWriter(writer);
     jsonWriter.beginArray();
@@ -42,9 +43,11 @@ int writeOutputEvents(Event[] events, EventSummarizer.EventSummary summary, Writ
         count++;
       }
     }
-    if (!summary.isEmpty()) {
-      writeSummaryEvent(summary, jsonWriter);
-      count++;
+    for (EventSummarizer.EventSummary summary : summaries) {
+      if (!summary.isEmpty()) {
+        writeSummaryEvent(summary, jsonWriter);
+        count++;
+      }
     }
     jsonWriter.endArray();
     jsonWriter.flush();
@@ -234,6 +237,11 @@ private void writeSummaryEvent(EventSummarizer.EventSummary summary, JsonWriter
     jw.name("endDate");
     jw.value(summary.endDate);
 
+    // Include context if present (per-context summarization)
+    if (summary.context != null) {
+      writeContext(summary.context, jw, true); // redact anonymous attributes
+    }
+
     jw.name("features");
     jw.beginObject();
 

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

@@ -16,9 +16,15 @@
  */
 final class EventSummarizer {
   private EventSummary eventsState;
-  
+  private final LDContext context; // nullable - only set for per-context summarization
+
   EventSummarizer() {
-    this.eventsState = new EventSummary();
+    this(null);
+  }
+
+  EventSummarizer(LDContext context) {
+    this.context = context;
+    this.eventsState = new EventSummary(context);
   }
 
   /**
@@ -76,22 +82,29 @@ boolean isEmpty() {
   }
 
   void clear() {
-    eventsState = new EventSummary();
+    eventsState = new EventSummary(context);
   }
 
   static final class EventSummary {
     final Map<String, FlagInfo> counters;
     long startDate;
     long endDate;
-    
+    final LDContext context; // nullable for backward compatibility
+
     EventSummary() {
-      counters = new HashMap<>();
+      this((LDContext) null);
+    }
+
+    EventSummary(LDContext context) {
+      this.counters = new HashMap<>();
+      this.context = context;
     }
 
     EventSummary(EventSummary from) {
       counters = new HashMap<>(from.counters);
       startDate = from.startDate;
       endDate = from.endDate;
+      context = from.context;
     }
 
     boolean isEmpty() {
@@ -142,7 +155,8 @@ void noteTimestamp(long time) {
     public boolean equals(Object other) {
       if (other instanceof EventSummary) {
         EventSummary o = (EventSummary)other;
-        return o.counters.equals(counters) && startDate == o.startDate && endDate == o.endDate;
+        return o.counters.equals(counters) && startDate == o.startDate && endDate == o.endDate &&
+            Objects.equals(context, o.context);
       }
       return false;
     }

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

@@ -30,10 +30,11 @@ public final class EventsConfiguration {
   final boolean initiallyInBackground;
   final boolean initiallyOffline;
   final List<AttributeRef> privateAttributes;
+  final boolean perContextSummarization;
 
   /**
    * Creates an instance.
-   * 
+   *
    * @param allAttributesPrivate true if all attributes are private
    * @param capacity event buffer capacity (if zero or negative, a value of 1 is used to prevent errors)
    * @param contextDeduplicator optional EventContextDeduplicator; null for client-side SDK
@@ -63,6 +64,45 @@ public EventsConfiguration(
       boolean initiallyOffline,
       Collection<AttributeRef> privateAttributes
       ) {
+    this(allAttributesPrivate, capacity, contextDeduplicator, diagnosticRecordingIntervalMillis,
+        diagnosticStore, eventSender, eventSendingThreadPoolSize, eventsUri, flushIntervalMillis,
+        initiallyInBackground, initiallyOffline, privateAttributes, false);
+  }
+
+  /**
+   * Creates an instance.
+   *
+   * @param allAttributesPrivate true if all attributes are private
+   * @param capacity event buffer capacity (if zero or negative, a value of 1 is used to prevent errors)
+   * @param contextDeduplicator optional EventContextDeduplicator; null for client-side SDK
+   * @param diagnosticRecordingIntervalMillis diagnostic recording interval
+   * @param diagnosticStore optional DiagnosticStore; null if diagnostics are disabled
+   * @param eventSender event delivery component; must not be null
+   * @param eventSendingThreadPoolSize number of worker threads for event delivery; zero to use the default
+   * @param eventsUri events base URI
+   * @param flushIntervalMillis event flush interval
+   * @param initiallyInBackground true if we should start out in background mode (see
+   *   {@link DefaultEventProcessor#setInBackground(boolean)})
+   * @param initiallyOffline true if we should start out in offline mode (see
+   *   {@link DefaultEventProcessor#setOffline(boolean)})
+   * @param privateAttributes list of private attribute references; may be null
+   * @param perContextSummarization true to generate separate summary events per context
+   */
+  public EventsConfiguration(
+      boolean allAttributesPrivate,
+      int capacity,
+      EventContextDeduplicator contextDeduplicator,
+      long diagnosticRecordingIntervalMillis,
+      DiagnosticStore diagnosticStore,
+      EventSender eventSender,
+      int eventSendingThreadPoolSize,
+      URI eventsUri,
+      long flushIntervalMillis,
+      boolean initiallyInBackground,
+      boolean initiallyOffline,
+      Collection<AttributeRef> privateAttributes,
+      boolean perContextSummarization
+      ) {
     super();
     this.allAttributesPrivate = allAttributesPrivate;
     this.capacity = capacity >= 0 ? capacity : 1;
@@ -77,5 +117,6 @@ public EventsConfiguration(
     this.initiallyInBackground = initiallyInBackground;
     this.initiallyOffline = initiallyOffline;
     this.privateAttributes = privateAttributes == null ? Collections.emptyList() : new ArrayList<>(privateAttributes);
+    this.perContextSummarization = perContextSummarization;
   }
 }