Redis journal storage

Orleans Journaling persists durable state changes as ordered journal data which is replayed to recover in-memory durable values and collections managed by IDurableStateManager. Ordinary grains can inject the manager, and DurableGrain provides a convenience base class. See the Journaling overview for its programming model and the Event Sourcing comparison for the boundary between the two features.

The pre-release Microsoft.Orleans.Journaling.Redis package stores journal data in Redis. Its APIs carry diagnostic ORLEANSEXP005.

Configure Redis journal storage

Configure the provider with AddRedisJournalStorage:

var builder = Host.CreateApplicationBuilder();
builder.UseOrleans(siloBuilder =>
{
    siloBuilder.AddRedisJournalStorage(options =>
    {
        options.ConfigurationOptions = new ConfigurationOptions
        {
            EndPoints = { "localhost:6379" },
            AbortOnConnectFail = false
        };
    });
});

using var host = builder.Build();

The runnable Redis Journaling sample uses the same provider with a DurableGrain, acknowledges a durable value update, deactivates the grain, and verifies recovery on a new activation.

The named overload accepts a provider name followed by the options delegate. Use distinct names with independent connections or key prefixes for separate journal namespaces. A named provider’s options, catalog, storage, and state-manager factory resolve together; the unnamed overload continues to configure default grain journaling. Set Orleans:Journaling:{name}:ProviderType to Redis to configure each named storage binding, and use Orleans:Journaling:{name}:ServiceKey to select its client connection from dependency injection. Use Default as the name for grain journaling, for example Orleans:Journaling:Default:ProviderType.

Durable Jobs can select a Redis write provider and retain another provider for draining. Keep the old prefix, credentials, and mutation permissions until every old shard is resolved: claims, retries, cancellation, compaction, and deletion continue there. A Redis catalog scan has live-listing semantics, so successful inventory is an observation rather than a transactionally frozen cluster view. Follow Migrate Durable Jobs storage, including repeated complete inventories after all scheduling silos have cut over.

Storage behavior

The provider stores journal data in Redis strings and journal metadata in Redis hashes. Per-journal reads and mutations use atomic Lua scripts. Catalog operations discover journals by scanning metadata keys on each connected primary Redis server.

Optimistic concurrency protects append, replace, and delete operations. A stale writer receives InconsistentStateException, and the Journaling state manager permanently fences operations and requests grain deactivation. A fresh activation recovers the stored journal. Concurrent reads observe either the journal before a replacement or the complete replacement.

RedisJournalStorageOptions supports:

• ConfigurationOptions for the StackExchange.Redis connection.
• CreateMultiplexer to supply a shared or custom connection multiplexer.
• KeyPrefix to isolate journal keys. The default is {ServiceId}/journaling.
• GetKeyName to customize the journal key component.
• CompactionThresholdBytes to select when the provider requests compaction.
• ReadChunkSize to limit the size of recovery segments supplied to the journal consumer.

The key prefix and key-name function define the location of existing journals. Retain the previous mapping or migrate the stored data before deploying a new mapping.

The default compaction threshold is 128 MiB and the default recovery chunk size is 1 MiB. Compaction replaces the append history with a snapshot of the grain’s current durable states.

Redis returns the journal string as one value. ReadChunkSize divides that value into replay segments after retrieval; capacity planning should account for the full journal value in the Redis client and silo process.

Durability

Redis journal durability depends on the Redis persistence and replication configuration. Configure persistence, such as append-only file (AOF) persistence with an appropriate appendfsync policy, according to the application’s recovery-point requirements.

Use a distinct KeyPrefix when multiple Orleans services share a Redis deployment.

Back up each journal’s string data and hash metadata consistently. Restore both under the same prefix and key mapping before allowing silos to activate the grain.

For capacity, upgrade, backup, and troubleshooting guidance, see Operate and troubleshoot Orleans Journaling.