Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/site/src/content/docs/grains/journaling/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,4 +178,25 @@ The default minimum is seven days. Removal is persisted by a compaction after th

<xref:Orleans.Journaling.JournalingHostingExtensions.AddJournaling*> registers the core services, formats, durable-state factories, and lifecycle integration. Register storage through a provider-specific method or the generic <xref:Orleans.Journaling.JournalingHostingExtensions.AddJournalStorage*> method. Runtime tests and disposable development hosts can use <xref:Orleans.Journaling.JournalingHostingExtensions.AddVolatileJournalStorage*> with a provider name. Its contents live in process memory, so use persistent emulator storage to validate restart recovery and provider migration.

<xref:Orleans.Journaling.VolatileJournalStorageOptions> controls the retained append
history. The defaults request a snapshot after **100 successful appends or 1 MiB
(1,048,576 bytes)** of appended data, whichever limit is reached first:

:::code language="csharp" source="./snippets/journaling/JournalingConfiguration.cs" id="volatile_journal_thresholds":::

The state manager observes that request before its next write. That write replaces
the history with a snapshot of current state; successful replacement resets both
counters. Snapshot bytes are excluded from the appended-byte count. Deletion and
recreation begin with empty history. Each limit must be positive; a single append
can exceed the byte threshold.

Use the overload accepting a provider name and options delegate to configure
independent named thresholds. Providers capture the configured limits when
constructed. Counters belong to each journal and are shared by
handles for the same journal within one provider. Larger limits amortize
full-state snapshot copies over more updates; smaller limits reduce retained
append history and replay work. Size both limits alongside the current snapshot.
Retained memory includes the latest snapshot, appended encoded bytes up to and
including the crossing append, and the storage provider's bookkeeping.

Use the same durable provider category in staging that production uses so recovery, compaction, concurrency, and backup procedures receive realistic validation.
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,18 @@ internal partial class JournalJsonContext : JsonSerializerContext;

public static class JournalingConfiguration
{
public static ISiloBuilder ConfigureVolatile(ISiloBuilder siloBuilder)
{
// <volatile_journal_thresholds>
siloBuilder.AddVolatileJournalStorage(options =>
{
options.MaxAppendsBeforeSnapshot = 100;
options.MaxBytesBeforeSnapshot = 1024 * 1024;
});
// </volatile_journal_thresholds>
return siloBuilder;
}

public static IHost ConfigureJson()
{
// <configure_json_format>
Expand Down
39 changes: 38 additions & 1 deletion src/Orleans.Journaling/JournalingHostingExtensions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,44 @@ public static ISiloBuilder AddVolatileJournalStorage(this ISiloBuilder builder)
/// <param name="name">The provider name.</param>
/// <returns>The silo builder.</returns>
public static ISiloBuilder AddVolatileJournalStorage(this ISiloBuilder builder, string name)
=> builder.AddJournalStorage(name, static services => ActivatorUtilities.CreateInstance<VolatileJournalStorageProvider>(services));
=> builder.AddVolatileJournalStorage(name, configureOptions: null);

/// <summary>
/// Registers the default volatile journal provider with configurable snapshot thresholds.
/// </summary>
/// <param name="builder">The silo builder.</param>
/// <param name="configureOptions">Configures the provider's snapshot thresholds.</param>
/// <returns>The silo builder.</returns>
public static ISiloBuilder AddVolatileJournalStorage(this ISiloBuilder builder, Action<VolatileJournalStorageOptions> configureOptions)
=> builder.AddVolatileJournalStorage(ProviderConstants.DEFAULT_STORAGE_PROVIDER_NAME, configureOptions);

/// <summary>
/// Registers a named volatile journal provider with configurable snapshot thresholds.
/// </summary>
/// <param name="builder">The silo builder.</param>
/// <param name="name">The provider name.</param>
/// <param name="configureOptions">Optionally configures the provider's snapshot thresholds.</param>
/// <returns>The silo builder.</returns>
public static ISiloBuilder AddVolatileJournalStorage(
this ISiloBuilder builder, string name, Action<VolatileJournalStorageOptions>? configureOptions)
{
ArgumentNullException.ThrowIfNull(builder);
ArgumentException.ThrowIfNullOrWhiteSpace(name);
var options = builder.Services.AddJournalStorageOptions<VolatileJournalStorageOptions>(name)
.Validate(static configuration => configuration.MaxAppendsBeforeSnapshot > 0,
"MaxAppendsBeforeSnapshot must be positive.")
.Validate(static configuration => configuration.MaxBytesBeforeSnapshot > 0,
"MaxBytesBeforeSnapshot must be positive.");
if (configureOptions is not null)
{
options.Configure(configureOptions);
}

return builder.AddJournalStorage(name, services => new VolatileJournalStorageProvider(
services.GetRequiredService<IOptions<JournaledStateManagerOptions>>(),
services.GetJournalStorageOptions<VolatileJournalStorageOptions>(name),
services.GetService<OrleansInstruments>()));
}

private sealed record JournalStorageRegistration(string Name, Type ProviderType);

Expand Down
18 changes: 18 additions & 0 deletions src/Orleans.Journaling/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,24 @@ Application code uses `IDurableStateManager` to manage the grain's durable state
`IStateMachine` defines the low-level replay and snapshot protocol for state implementations.
`IJournaledStateManager` is an independent contract for journal ownership and lifetime operations.

## Volatile storage snapshot thresholds

`AddVolatileJournalStorage(options => ...)` configures
`VolatileJournalStorageOptions.MaxAppendsBeforeSnapshot` (default 100) and
`MaxBytesBeforeSnapshot` (default 1,048,576 bytes). The named-provider overload
configures each provider independently. Both values must be positive.
Providers capture the configured limits when constructed.

Reaching either threshold requests a snapshot before the next journal write.
Successful replacement resets both counters; the snapshot itself is excluded
from append history. Deletion and recreation reset the history too. A single
append can exceed the byte threshold. Larger limits amortize snapshot copies
over more updates; smaller limits reduce retained history and replay work.
Counters belong to each journal and are shared by handles for the same journal
within one provider.
Retained memory includes the latest snapshot, appended encoded bytes up to and
including the crossing append, and provider bookkeeping.

## Getting Started
To use this package, install it via NuGet:

Expand Down
64 changes: 60 additions & 4 deletions src/Orleans.Journaling/VolatileJournalStorage.cs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ public sealed class VolatileJournalStorageProvider : IJournalStorageProvider, IJ
private readonly SortedSet<string> _storageKeys = new(StringComparer.Ordinal);
private readonly object _catalogLock = new();
private readonly JournalStorageTelemetry _telemetry;
private readonly VolatileJournalStorageOptions _storageOptions = new();

/// <summary>
/// Initializes a new instance of the <see cref="VolatileJournalStorageProvider"/> class using the default journal format.
Expand Down Expand Up @@ -51,6 +52,31 @@ public VolatileJournalStorageProvider(IOptions<JournaledStateManagerOptions> opt
_telemetry = new JournalStorageTelemetry(instruments);
}

/// <summary>
/// Initializes an in-memory provider with configurable snapshot thresholds.
/// </summary>
/// <param name="options">The journaled state manager options.</param>
/// <param name="storageOptions">The provider's snapshot thresholds.</param>
/// <param name="instruments">The optional Orleans runtime metrics meter.</param>
public VolatileJournalStorageProvider(
IOptions<JournaledStateManagerOptions> options,
IOptions<VolatileJournalStorageOptions> storageOptions,
OrleansInstruments? instruments) : this(options)
{
ArgumentNullException.ThrowIfNull(storageOptions);
var configuration = storageOptions.Value;
configuration.Validate();
_storageOptions = new()
{
MaxAppendsBeforeSnapshot = configuration.MaxAppendsBeforeSnapshot,
MaxBytesBeforeSnapshot = configuration.MaxBytesBeforeSnapshot
};
if (instruments is not null)
{
_telemetry = new JournalStorageTelemetry(instruments);
}
}

/// <inheritdoc/>
public IJournalStorage CreateStorage(JournalId journalId)
{
Expand All @@ -73,7 +99,7 @@ public IJournalStorage CreateStorage(JournalId journalId)
}
}

return new VolatileJournalStorage(store, journalFormatKey);
return new VolatileJournalStorage(store, journalFormatKey, _storageOptions);
}

/// <inheritdoc/>
Expand Down Expand Up @@ -147,6 +173,8 @@ private string GetJournalFormatKey()
public sealed class VolatileJournalStorage : IJournalStorage
{
private readonly Store _store;
private readonly int _maxAppendsBeforeSnapshot;
private readonly long _maxBytesBeforeSnapshot;
private string? _configuredJournalFormatKey;

/// <summary>
Expand All @@ -164,10 +192,24 @@ public VolatileJournalStorage(string? journalFormatKey) : this(new Store(CreateV
{
}

internal VolatileJournalStorage(Store store, string? journalFormatKey)
/// <summary>
/// Initializes an isolated in-memory journal with configurable snapshot thresholds.
/// </summary>
/// <param name="journalFormatKey">The journal format key to stamp on writes.</param>
/// <param name="options">The snapshot thresholds.</param>
public VolatileJournalStorage(string? journalFormatKey, VolatileJournalStorageOptions options)
: this(new Store(CreateVolatileStorageId()), journalFormatKey, options ?? throw new ArgumentNullException(nameof(options)))
{
}

internal VolatileJournalStorage(Store store, string? journalFormatKey, VolatileJournalStorageOptions? options = null)
{
ArgumentNullException.ThrowIfNull(store);
options ??= new();
options.Validate();
_store = store;
_maxAppendsBeforeSnapshot = options.MaxAppendsBeforeSnapshot;
_maxBytesBeforeSnapshot = options.MaxBytesBeforeSnapshot;
SetConfiguredJournalFormatKey(journalFormatKey);
}

Expand All @@ -178,7 +220,7 @@ public bool IsCompactionRequested
{
lock (_store.SyncRoot)
{
return _store.Segments.Count > 10;
return _store.AppendCount >= _maxAppendsBeforeSnapshot || _store.AppendedBytes >= _maxBytesBeforeSnapshot;
}
}
}
Expand Down Expand Up @@ -295,6 +337,8 @@ public ValueTask AppendAsync(ReadOnlySequence<byte> segment, CancellationToken c
_store.Exists = true;
_store.StoredJournalFormatKey = _configuredJournalFormatKey;
_store.Segments.Add(segment.ToArray());
_store.AppendedBytes += segment.Length;
_store.AppendCount++;
_store.RefreshETag();
}

Expand All @@ -305,12 +349,15 @@ public ValueTask AppendAsync(ReadOnlySequence<byte> segment, CancellationToken c
public ValueTask ReplaceAsync(ReadOnlySequence<byte> snapshot, CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();
var data = snapshot.ToArray();
lock (_store.SyncRoot)
{
_store.Exists = true;
_store.StoredJournalFormatKey = _configuredJournalFormatKey;
_store.Segments.Clear();
_store.Segments.Add(snapshot.ToArray());
_store.Segments.Add(data);
_store.AppendedBytes = 0;
_store.AppendCount = 0;
_store.RefreshETag();
}

Expand All @@ -337,6 +384,11 @@ internal sealed class Store(string storageId)

public List<byte[]> Segments { get; } = [];

public long AppendCount { get; set; }

// List count and each stored array length fit in int, so their total fits in long.
public long AppendedBytes { get; set; }

public Dictionary<string, string> Properties { get; } = new(StringComparer.Ordinal);

public string? StoredJournalFormatKey { get; set; }
Expand All @@ -351,6 +403,8 @@ public void Create(IReadOnlyDictionary<string, string>? properties)
{
Exists = true;
Segments.Clear();
AppendCount = 0;
AppendedBytes = 0;
Properties.Clear();
StoredJournalFormatKey = null;
if (properties is not null)
Expand All @@ -368,6 +422,8 @@ public void Delete()
{
Exists = false;
Segments.Clear();
AppendCount = 0;
AppendedBytes = 0;
Properties.Clear();
StoredJournalFormatKey = null;
ETag = null;
Expand Down
34 changes: 34 additions & 0 deletions src/Orleans.Journaling/VolatileJournalStorageOptions.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
namespace Orleans.Journaling;

/// <summary>
/// Configures the journal history retained by volatile storage between snapshots.
/// </summary>
/// <remarks>
/// Providers and isolated storage instances capture these values during construction.
/// Each journal counts successful storage append calls, including empty appends.
/// </remarks>
public sealed class VolatileJournalStorageOptions
{
/// <summary>
/// Gets or sets the number of successful appends after which storage requests a snapshot.
/// The default is 100. The value must be positive.
/// </summary>
public int MaxAppendsBeforeSnapshot { get; set; } = 100;

/// <summary>
/// Gets or sets the appended byte count after which storage requests a snapshot.
/// The default is 1 MiB (1,048,576 bytes). The value must be positive.
/// </summary>
/// <remarks>
/// Storage requests a snapshot when either limit is reached. The appended byte count measures
/// encoded journal bytes, with snapshot bytes excluded. A successful snapshot or deletion resets both counters.
/// The state manager checks the request before its next write, so an individual append can exceed this limit.
/// </remarks>
public long MaxBytesBeforeSnapshot { get; set; } = 1024 * 1024;

internal void Validate()
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(MaxAppendsBeforeSnapshot);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(MaxBytesBeforeSnapshot);
}
}
15 changes: 15 additions & 0 deletions src/api/Orleans.Journaling/Orleans.Journaling.cs
Original file line number Diff line number Diff line change
Expand Up @@ -492,6 +492,10 @@ public static Microsoft.Extensions.DependencyInjection.IServiceCollection AddSta
public static Microsoft.Extensions.DependencyInjection.IServiceCollection AddStateMachine<TState, TImplementation>(this Microsoft.Extensions.DependencyInjection.IServiceCollection services)
where TState : class where TImplementation : class, TState, IStateMachine { throw null; }

public static Hosting.ISiloBuilder AddVolatileJournalStorage(this Hosting.ISiloBuilder builder, System.Action<VolatileJournalStorageOptions> configureOptions) { throw null; }

public static Hosting.ISiloBuilder AddVolatileJournalStorage(this Hosting.ISiloBuilder builder, string name, System.Action<VolatileJournalStorageOptions>? configureOptions) { throw null; }

public static Hosting.ISiloBuilder AddVolatileJournalStorage(this Hosting.ISiloBuilder builder, string name) { throw null; }

public static Hosting.ISiloBuilder AddVolatileJournalStorage(this Hosting.ISiloBuilder builder) { throw null; }
Expand Down Expand Up @@ -593,6 +597,8 @@ public sealed partial class VolatileJournalStorage : IJournalStorage
{
public VolatileJournalStorage() { }

public VolatileJournalStorage(string? journalFormatKey, VolatileJournalStorageOptions options) { }

public VolatileJournalStorage(string? journalFormatKey) { }

public bool IsCompactionRequested { get { throw null; } }
Expand All @@ -612,10 +618,19 @@ public VolatileJournalStorage(string? journalFormatKey) { }
public System.Threading.Tasks.ValueTask<IJournalMetadata?> UpdateMetadataAsync(System.Collections.Generic.IReadOnlyDictionary<string, string>? set = null, System.Collections.Generic.IEnumerable<string>? remove = null, string? expectedETag = null, System.Threading.CancellationToken cancellationToken = default) { throw null; }
}

public sealed partial class VolatileJournalStorageOptions
{
public int MaxAppendsBeforeSnapshot { get { throw null; } set { } }

public long MaxBytesBeforeSnapshot { get { throw null; } set { } }
}

public sealed partial class VolatileJournalStorageProvider : IJournalStorageProvider, IJournalStorageCatalog
{
public VolatileJournalStorageProvider() { }

public VolatileJournalStorageProvider(Microsoft.Extensions.Options.IOptions<JournaledStateManagerOptions> options, Microsoft.Extensions.Options.IOptions<VolatileJournalStorageOptions> storageOptions, Runtime.OrleansInstruments? instruments) { }

public VolatileJournalStorageProvider(Microsoft.Extensions.Options.IOptions<JournaledStateManagerOptions> options, Runtime.OrleansInstruments instruments) { }

public VolatileJournalStorageProvider(Microsoft.Extensions.Options.IOptions<JournaledStateManagerOptions> options) { }
Expand Down
Loading
Loading