Orleans Journaling overview

Orleans Journaling is an experimental persistence model that records mutations to durable values and collections in an ordered per-grain journal. When a grain activates, Orleans replays that journal to reconstruct its in-memory state. A single write can persist changes from multiple durable states owned by the grain.

Programming model

A journaling grain derives from DurableGrain and receives named durable states through keyed dependency injection. Orleans currently provides:

IDurableValue<T>
IDurableDictionary<T, U>
IDurableList<T>
IDurableQueue<T>
IDurableSet<T>
IDurableTaskCompletionSource<T>
IPersistentState<T> backed by the grain’s journal

Mutations update the activation’s in-memory state and add encoded operations to its pending journal buffer. Await WriteStateAsync at the application durability point. The returned task completes after the storage provider acknowledges the append or snapshot replacement.

Each named state has a stable stream identity within the grain journal. Keep those names stable across deployments so recovery can bind stored operations to the intended state.

Journal lifecycle

During activation setup, Orleans reads the journal in order and replays each state stream.
Grain code synchronously mutates durable values and collections during a grain turn.
WriteStateAsync gathers pending operations for the grain and submits one atomic journal append or replacement to storage.
The storage provider can request compaction when its configured size or row threshold is reached. The next write creates a snapshot of the current durable states and atomically replaces the journal.
A later activation replays the latest snapshot and subsequent operations to restore the same durable state.

For the detailed guarantees, see Runtime behavior and consistency.

Journal formats

JSON Lines is the default write format. Each line contains a state stream identifier and one encoded operation. Configure source-generated JsonSerializerContext metadata for journaled key, value, and state types when using trimming or Native AOT.

The earlier Orleans binary format remains registered so deployments can read existing data. Providers store the journal format key with the journal. When the configured write format differs from the stored format, recovery uses the stored reader and the next write snapshots the journal in the configured format.

See Configure Journaling for format and migration guidance.

Journaling and Event Sourcing

Orleans offers two separate journal-oriented programming models:

Model	Application state model	Persistence coordination
Orleans Journaling	Mutable durable values and collections on DurableGrain	One per-grain journal managed by `Microsoft.Orleans.Journaling`
Orleans Event Sourcing	Application-defined events applied to `JournaledGrain<TState, TEvent>`	Log-consistency providers confirm, persist, and synchronize events

Choose Journaling when evaluating operation-based persistence for built-in mutable state structures. Choose Event Sourcing when domain events, event history, and the supported log-consistency programming model are application requirements.