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.
Defaults
Section titled “Defaults”opts.Checkpoint.AutoTrack = true; // track each processed positionopts.Checkpoint.AutoCheckpoint = true; // commit them on a timeropts.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.
The two switches
Section titled “The two switches”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
Section titled “Interval”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.
Failure policy
Section titled “Failure policy”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.
OnCheckpoint
Section titled “OnCheckpoint”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);}