Skip to content

Checkpointing

A checkpoint is the position a processor resumes from after a restart. The runtime tracks and commits it for you.

Checkpoint, track, and resume with record.CheckpointPosition. Position is where the row lives, and through a pointer stream such as $ce-orders it sits behind the cursor.

opts.Checkpoint.AutoTrack = true; // track each processed position
opts.Checkpoint.AutoCheckpoint = true; // commit them on a timer
opts.Checkpoint.Interval = TimeSpan.FromSeconds(30);
opts.Checkpoint.RetentionCount = 3;
opts.Checkpoint.FailurePolicy = CheckpointFailurePolicy.Continue;

With both switches on, which is the default, you write a handler and never think about position again.

AutoTrack decides whether a processed record advances the tracked position automatically. Turn it off and you call context.Track(...) yourself, which is what you want when a record is handed to something asynchronous and “processed” does not mean “done”. Pass the record, or its CheckpointPosition. A resolved link’s Position is its target, earlier in the log, and the tracker rejects it once the floor has moved past it.

AutoCheckpoint decides whether tracked positions are committed on the interval. Turn it off and you request a commit explicitly.

They are independent. Tracking is what has been processed; checkpointing is when the tracked position becomes durable.

Interval is the commit period, 30 seconds by default. A shorter interval means less replay after a crash and more writes. It is a recovery-time dial, not a correctness one. At-least-once delivery holds either way, so a handler must tolerate seeing a record twice.

CheckpointFailurePolicy.Continue keeps processing when a commit fails. The alternative stops the processor. Continue is the default because a failed commit costs replay, while a stop costs availability.

The hook fires when a position is committed. It is the moment to flush anything that must survive a restart, because the position about to be durable says that work is done:

public async ValueTask OnCheckpoint(CheckpointContext context) {
await _buffer.FlushAsync(context.CancellationToken);
context.Logger.LogInformation("Committed at {Id}", context.CheckpointId);
}