Event-time windows: place each event by occurrence, not arrival

Last updated: 5 Oct 20265 min read

tutorial

A streaming window groups an unbounded event sequence into finite intervals under a stated clock and boundary convention.

Separate clocks

A receipt may be submitted at 09:59 but delivered to analytics at 10:04 after a network retry. An event-time 09:00–10:00 window counts it in the earlier hour; a processing-time window counts it in the later one. Choose based on the business question and keep both timestamps. Calendar policy determines time zone and reporting cutoff.

Declare the window

A tumbling one-hour window gives each event one interval. A sliding one-hour window advancing every ten minutes can count an event in several windows; those overlapping counts cannot be summed into an overall total. Use half-open intervals so an event exactly at 10:00 belongs to 10:00–11:00, not both hours.

Keep identity and denominator

If a receipt emits submitted and corrected events, counting both as submissions inflates volume. Filter event types and deduplicate business facts before aggregation. For a completion-rate stream, numerator and denominator may arrive on different schedules; publish provisional rates or delay publication until both are sufficiently complete. Metric grain remains important in streaming.

Test boundaries

With a 60-minute tumbling window, events at minutes 59, 60 and 119 map to windows starting at 0, 60 and 60. Test a negative timestamp if the chosen epoch representation permits it; integer division should still place it consistently. Then deliver minute 59 after minute 60 and verify event time, not arrival order, controls membership.

Implementation

def tumbling_window_start(event_minute, window_minutes=60):
    if window_minutes < 1:
        raise ValueError("window length must be positive")
    return (event_minute // window_minutes) * window_minutes

assert [tumbling_window_start(minute) for minute in (59, 60, 119)] == [0, 60, 60]

Performance and operating cost

Window assignment is O(1) per event. Maintaining W active keyed windows needs O(W) state; overlapping sliding windows can multiply state and update work, so define the analysis need before choosing a shorter slide.

Common Mistakes

Do not mix event time and arrival time in one metric without a label.
Do not sum overlapping sliding-window counts as a unique total.
Do not count a correction event as a new submission by default.