Table of Contents

Interface IProjectionLagReadModel

Namespace
Excalibur.EventSourcing.Projections
Assembly
Excalibur.EventSourcing.dll

Reports per-subscription projection lag: how far each durable subscription's checkpoint trails the global stream head position.

public interface IProjectionLagReadModel

Remarks

Lag is computed as max(0, head - checkpoint) per subscription, so it can never be negative even if a checkpoint transiently reports ahead of an observed head.

That subtraction is an event COUNT only because committed global positions are dense. The event store's Global Stream Ordering contract guarantees that the set of committed positions is a contiguous prefix, so the number of positions between two points equals the number of events between them. The dependency is named here because it is not local: if positions were ever re-scoped, this figure would silently become an upper bound rather than a count, and nothing in this type would say so.

Intended for operational monitoring (dashboards, health signals).

An empty result and an unmeasurable one are different answers, and this contract keeps them apart. Without a global-stream head source there is no head to subtract from, so lag is UNDEFINED — not zero, and not "nothing is behind". Reporting an empty list for that case is the failure mode a monitoring surface can least afford: a dashboard renders it as healthy. See ProjectionLagAvailability.

Methods

GetLagAsync(CancellationToken)

Computes the current lag for every known subscription, and reports whether it could be measured at all.

ValueTask<ProjectionLagReport> GetLagAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ProjectionLagReport>

A report whose Availability states whether lag was measurable, and whose Streams carries one entry per enumerated subscription checkpoint. An empty Streams with Measured means the head was read and no subscription is behind; an empty Streams with NoHeadSource means nothing was measured.

Remarks

This returned a bare list of entries, where an empty list conflated "no subscription is behind" with "lag cannot be computed here". The two have opposite operational meanings and only one of them is good news.