Adding Akka.Persistence health checks #662

Aaronontheweb · 2025-09-30T21:58:00Z

Changes

Checklist

For significant changes, please ensure that the following have been completed (delete if not relevant):

This change follows the Akka.NET API Compatibility Guidelines.
This change follows the Akka.NET Wire Compatibility Guidelines.
I have reviewed my own pull request.
Design discussion issue Akka.Persistence HealthChecks akka.net#7842
Changes in public API reviewed, if any.
I have added website documentation for this feature.

Aaronontheweb · 2025-09-30T21:58:52Z

src/Akka.Persistence.Hosting/AkkaPersistenceHostingExtensions.cs

    /// <summary>
    /// Used to help build journal configurations
    /// </summary>
    public sealed class AkkaPersistenceJournalBuilder


I am going to make some significant structural changes to how Akka.Persistence.Hosting works. There's two competing paradigms (builder vs. options) when they should really be one and the same. I think this should be largely a superficial change.

Merged declarative (JournalOptions/SnapshotOptions) and fluent (builder actions) configuration patterns into a single coherent API. Changes: - Added AkkaPersistenceSnapshotBuilder with health check support - Added new overloads: WithJournal(options, builder), WithSnapshot(options, builder), and WithJournalAndSnapshot(options, options, builder, builder) - Deprecated WithJournal(string, builder) in favor of unified approach - Updated EventAdapterSpecs to demonstrate new unified API pattern - Added comprehensive test coverage in UnifiedApiSpecs.cs Benefits: - Single canonical way to configure persistence plugins - Plugin properties and event adapters/health checks in one call - Binary compatible - all existing APIs continue to work - Follows extend-only design principles per API compatibility guidelines - Ready for Akka.NET persistence health check integration API Example: builder.WithJournal( new SqlServerJournalOptions { ConnectionString = "..." }, journal => journal .AddWriteEventAdapter<MyAdapter>("adapter", types) .WithHealthCheck());

…de duplication - Fixed health check plugin IDs to use full paths (akka.persistence.journal.{id}) instead of just identifiers - Corrected test resource InternalDefaultConfig to avoid double-nesting of configuration paths - Added comprehensive health check verification to unified API tests - Refactored WithJournal/WithSnapshot/WithJournalAndSnapshot methods to use method chaining, establishing single source of truth for each operation - All 15 persistence hosting tests now pass with health checks returning accurate results

…theweb/Akka.Hosting into persistence-healthchecks

Aaronontheweb

Detailed my changes

Aaronontheweb · 2025-10-01T18:28:15Z

src/Akka.Persistence.Hosting/AkkaPersistenceHostingExtensions.cs

+        /// or <see cref="PersistenceHealthStatus.Degraded"/>. Defaults to degraded.</param>
+        /// <param name="name">Optional name to add to the health check.</param>
+        /// <returns></returns>
+        public AkkaPersistenceJournalBuilder WithHealthCheck(HealthStatus unHealthyStatus = HealthStatus.Degraded,


Registers the Akka.Persistence health check definition is inside the AsyncWriteJournal - by default it just looks as the state of the CircuitBreaker, which is a "good enough" heuristic typically.

Aaronontheweb · 2025-10-01T18:28:30Z

src/Akka.Persistence.Hosting/AkkaPersistenceHostingExtensions.cs

+
+            // add the health checks if specified
+            if(HealthCheckRegistration != null)
+                Builder.WithHealthCheck(HealthCheckRegistration);


Add the health checks to the AkkaConfigurationBuilder if they've been defined.

Aaronontheweb · 2025-10-01T18:35:20Z

src/Akka.Persistence.Hosting/AkkaPersistenceHostingExtensions.cs

+        ///         .WithHealthCheck());
+        /// </code>
+        /// </example>
+        public static AkkaConfigurationBuilder WithJournalAndSnapshot(


DX improvement: the JournalOptions and JournalBuilder should be part of the same "configuration" - the way it's defined in v1.5.50 right now is as two separate islands of configuration that reference the same thing via a shared pluginId.

We should, instead, make it clear to end-users that both of these components work against the same "thing".

We have also followed this pattern for the snapshot store too.

Aaronontheweb · 2025-10-01T18:50:50Z

src/Akka.Persistence.Hosting.Tests/UnifiedApiSpecs.cs

+/// <summary>
+/// Shared test resources for unified API specs
+/// </summary>
+public static class UnifiedApiTestResources


Tests the "unified" Akka.Persistence.Hosting APIs and tries to get test coverage over the PersistenceHostingExtensions

Aaronontheweb · 2025-10-01T18:51:42Z

src/Akka.Persistence.Hosting.Tests/UnifiedApiSpecs.cs

+/// <summary>
+/// Test WithJournalAndSnapshot with builder actions
+/// </summary>
+public sealed class JournalAndSnapshotWithBuildersSpec : Akka.Hosting.TestKit.TestKit


End to end integration test - also asserts that the health checks on each plugin work.

Aaronontheweb · 2025-10-01T18:54:11Z

src/Akka.Persistence.Hosting/HealthChecks.cs

+
+namespace Akka.Persistence.Hosting;
+
+internal static class HealthCheckExt


Maps the Akka.Persistence health check data structures into Microsoft.Extensions.HealthChecks data structures

Aaronontheweb · 2025-10-01T18:57:53Z

src/Akka.Persistence.Hosting/HealthChecks.cs

+    public async Task<HealthCheckResult> CheckHealthAsync(AkkaHealthCheckContext context, CancellationToken cancellationToken = default)
+    {
+        var persistence = Persistence.Instance.Apply(context.ActorSystem);
+        var journalResult = await persistence.CheckJournalHealthAsync(_journalPluginId, cancellationToken);


Runs the health checks we added in akkadotnet/akka.net#7842 and pipes them through the MSFT.EXT.HealthCheck functionality

Aaronontheweb · 2025-10-01T18:58:04Z

src/Akka.Persistence.Hosting/HealthChecks.cs

+    public async Task<HealthCheckResult> CheckHealthAsync(AkkaHealthCheckContext context, CancellationToken cancellationToken = default)
+    {
+        var persistence = Persistence.Instance.Apply(context.ActorSystem);
+        var ssResult = await persistence.CheckSnapshotStoreHealthAsync(_snapshotStorePluginId, cancellationToken);


Does the same as above, but for snapshots.

Aaronontheweb · 2025-10-01T18:58:21Z

src/Akka.Persistence.Hosting/SnapshotOptions.cs

+        {
+            var pluginId = $"akka.persistence.snapshot-store.{SnapshotStoreId}";
+            var registration = new AkkaHealthCheckRegistration(
+                name ?? $"Akka.Persistence.SnapshotStore.{SnapshotStoreId}",


default health check name if left blank.

Aaronontheweb · 2025-10-01T18:58:32Z

Directory.Build.props

-     <XunitRunneVisualstudio>3.1.5</XunitRunneVisualstudio>
-    <AkkaVersion>1.5.50</AkkaVersion>
+    <XunitRunneVisualstudio>3.1.5</XunitRunneVisualstudio>
+    <AkkaVersion>1.5.51</AkkaVersion>


Upgraded to Akka.NET v1.5.51 in order to get access to akkadotnet/akka.net#7842

Arkatufus

LGTM

Fixes akkadotnet#665 The Adapters property created confusion by providing two competing patterns for configuring event adapters. This deprecates the property in favor of the unified callback pattern introduced in PR akkadotnet#662. Changes: - Mark JournalOptions.Adapters as [Obsolete] with clear migration message - Remove internal usage of the property (Adapters.AppendAdapters call) - Add regression test DeprecatedAdaptersPropertySpec that verifies: * Deprecated property is ignored and does not configure adapters * Callback pattern continues to work correctly * Uses #pragma warning disable to test deprecated API Benefits: - Single, consistent pattern for configuring adapters and health checks - Cleaner API surface with options containing only configuration data - Clear migration path with deprecation warning Migration: Before (deprecated): var options = new JournalOptions(); options.Adapters.AddWriteEventAdapter<Foo>(...); builder.WithJournal(options); After (recommended): var options = new JournalOptions(); builder.WithJournal(options, journal => journal.AddWriteEventAdapter<Foo>(...)); All 17 tests pass.

Adding Akka.Persistence health checks

ef0160b

Aaronontheweb commented Sep 30, 2025

View reviewed changes

Aaronontheweb added 6 commits October 1, 2025 09:20

upgrade to Akka.NET v1.5.51

4ea9841

Merge branch 'dev' into persistence-healthchecks

4be1301

Merge branch 'persistence-healthchecks' of https://github.com/Aaronon…

dab033c

…theweb/Akka.Hosting into persistence-healthchecks

simplify source of truth code

772060d

Aaronontheweb mentioned this pull request Oct 1, 2025

Flaky test: ShardedDaemonProcessProxySpecs.ShardedDaemonProcessProxy_must_start_daemon_process_on_proxy #663

Open

Aaronontheweb commented Oct 1, 2025

View reviewed changes

Added documentation for Akka.Persistence health checks

d3aa948

Aaronontheweb marked this pull request as ready for review October 1, 2025 19:04

Arkatufus approved these changes Oct 1, 2025

View reviewed changes

Aaronontheweb merged commit 6cf713e into akkadotnet:dev Oct 1, 2025
2 checks passed

Aaronontheweb deleted the persistence-healthchecks branch October 1, 2025 19:21

Aaronontheweb mentioned this pull request Oct 1, 2025

Release 1.5.51 #664

Merged

Aaronontheweb mentioned this pull request Oct 2, 2025

Deprecate JournalOptions.Adapters property in favor of callback API #669

Merged


		namespace Akka.Persistence.Hosting;

		internal static class HealthCheckExt

Adding Akka.Persistence health checks #662

Adding Akka.Persistence health checks #662

Uh oh!

Conversation

Aaronontheweb commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aaronontheweb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Arkatufus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Aaronontheweb commented Sep 30, 2025 •

edited

Loading