Akka.Remote Microsoft.Extensions.Hosting support.
$ dotnet add package Akka.Remote.Hosting<a id="akkahosting"></a>
HOCON-less configuration, application lifecycle management, ActorSystem startup, and actor instantiation for Akka.NET.
See the "Introduction to Akka.Hosting - HOCON-less, "Pit of Success" Akka.NET Runtime and Configuration" video for a walkthrough of the library and how it can save you a tremendous amount of time and trouble.
<a id="akkanet-core-packages"></a>
Akka.Hosting - the core Akka.Hosting package, needed for everythingAkka.Remote.Hosting - enables Akka.Remote configuration. Documentation can be read hereAkka.Cluster.Hosting - used for Akka.Cluster, Akka.Cluster.Sharding, and Akka.Cluster.Tools. Documentation can be read hereAkka.Persistence.Hosting - used for adding persistence functionality to perform local database-less testing. Documentation can be read here<a id="akka-persistence-plugins"></a>
Akka.Persistence.SqlServer.Hosting - used for Akka.Persistence.SqlServer support. Documentation can be read hereAkka.Persistence.PostgreSql.Hosting - used for Akka.Persistence.PostgreSql support. Documentation can be read hereAkka.Persistence.Azure.Hosting - used for Akka.Persistence.Azure support. Documentation can be read here<a id="akkamanagement-plugins"></a>
Useful tools for managing Akka.NET clusters running inside containerized or cloud based environment. Akka.Hosting is embedded in each of its packages.
<a id="akkamanagement-core-package"></a>
Akka.Management - core module of the management utilities which provides a central HTTP endpoint for Akka management extensions. Documentation can be read hereAkka.Management.Cluster.Bootstrap - used to bootstrap a cluster formation inside dynamic deployment environments. Documentation can be read here
NOTE
As of version 1.0.0, cluster bootstrap came bundled inside the core
Akka.ManagementNuGet package and are part of the default HTTP endpoint forAkka.Management. AllAkka.Management.Cluster.BootstrapNuGet package versions below 1.0.0 should now be considered deprecated.
<a id="akkadiscovery-plugins"></a>
Akka.Discovery.AwsApi - provides dynamic node discovery service for AWS EC2 environment. Documentation can be read hereAkka.Discovery.Azure - provides a dynamic node discovery service for Azure PaaS ecosystem. Documentation can be read hereAkka.Discovery.KubernetesApi - provides a dynamic node discovery service for Kubernetes clusters. Documentation can be read here<a id="akkacoordination-plugins"></a>
Akka.Coordination.KubernetesApi - provides a lease-based distributed lock mechanism backed by Kubernetes CRD for Akka.NET Split Brain Resolver, Akka.Cluster.Sharding, and Akka.Cluster.Singleton. Documentation can be read hereAkka.Coordination.Azure - provides a lease-based distributed lock mechanism backed by Microsoft Azure Blob Storage for Akka.NET Split Brain Resolver, Akka.Cluster.Sharding, and Akka.Cluster.Singleton. Documentation can be read here<a id="summary"></a>
We want to make Akka.NET something that can be instantiated more typically per the patterns often used with the Microsoft.Extensions.Hosting APIs that are common throughout .NET.
using Akka.Hosting;
using Akka.Actor;
using Akka.Actor.Dsl;
using Akka.Cluster.Hosting;
using Akka.Remote.Hosting;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.WithRemoting("localhost", 8110)
.WithClustering(new ClusterOptions(){ Roles = new[]{ "myRole" },
SeedNodes = new[]{ Address.Parse("akka.tcp://MyActorSystem@localhost:8110")}})
.WithActors((system, registry) =>
{
var echo = system.ActorOf(act =>
{
act.ReceiveAny((o, context) =>
{
context.Sender.Tell($"{context.Self} rcv {o}");
});
}, "echo");
registry.TryRegister<Echo>(echo); // register for DI
});
});
var app = builder.Build();
app.MapGet("/", async (context) =>
{
var echo = context.RequestServices.GetRequiredService<ActorRegistry>().Get<Echo>();
var body = await echo.Ask<string>(context.TraceIdentifier, context.RequestAborted).ConfigureAwait(false);
await context.Response.WriteAsync(body);
});
app.Run();No HOCON. Automatically runs all Akka.NET application lifecycle best practices behind the scene. Automatically binds the ActorSystem and the ActorRegistry, another new 1.5 feature, to the IServiceCollection so they can be safely consumed via both actors and non-Akka.NET parts of users' .NET applications.
This should be open to extension in other child plugins, such as Akka.Persistence.SqlServer:
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.WithRemoting("localhost", 8110)
.WithClustering(new ClusterOptions()
{
Roles = new[] { "myRole" },
SeedNodes = new[] { Address.Parse("akka.tcp://MyActorSystem@localhost:8110") }
})
.WithSqlServerPersistence(builder.Configuration.GetConnectionString("sqlServerLocal"))
.WithShardRegion<UserActionsEntity>("userActions", s => UserActionsEntity.Props(s),
new UserMessageExtractor(),
new ShardOptions(){ StateStoreMode = StateStoreMode.DData, Role = "myRole"})
.WithActors((system, registry) =>
{
var userActionsShard = registry.Get<UserActionsEntity>();
var indexer = system.ActorOf(Props.Create(() => new Indexer(userActionsShard)), "index");
registry.TryRegister<Index>(indexer); // register for DI
});
})<a id="dependency-injection-outside-and-inside-akkanet"></a>
One of the other design goals of Akka.Hosting is to make the dependency injection experience with Akka.NET as seamless as any other .NET technology. We accomplish this through two new APIs:
ActorRegistry, a DI container that is designed to be populated with Types for keys and IActorRefs for values, just like the IServiceCollection does for ASP.NET services.IRequiredActor<TKey> - you can place this type the constructor of any dependency injected resource and it will automatically resolve a reference to the actor stored inside the ActorRegistry with TKey. This is how we inject actors into ASP.NET, SignalR, gRPC, and other Akka.NET actors!N.B. The
ActorRegistryand theActorSystemare automatically registered with theIServiceCollection/IServiceProviderassociated with your application.
<a id="registering-actors-with-the-actorregistry"></a>
ActorRegistryAs part of Akka.Hosting, we need to provide a means of making it easy to pass around top-level IActorRefs via dependency injection both within the ActorSystem and outside of it.
The ActorRegistry will fulfill this role through a set of generic, typed methods that make storage and retrieval of long-lived IActorRefs easy and coherent:
var registry = ActorRegistry.For(myActorSystem); builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.WithActors((system, actorRegistry) =>
{
var actor = system.ActorOf(Props.Create(() => new MyActor));
actorRegistry.TryRegister<MyActor>(actor); // register actor for DI
});
});IActorRef manuallyvar registry = ActorRegistry.For(myActorSystem);
registry.Get<Index>(); // use in DI<a id="injecting-actors-with-irequiredactortkey"></a>
IRequiredActor<TKey>Suppose we have a class that depends on having a reference to a top-level actor, a router, a ShardRegion, or perhaps a ClusterSingleton (common types of actors that often interface with non-Akka.NET parts of a .NET application):
public sealed class MyConsumer
{
private readonly IActorRef _actor;
public MyConsumer(IRequiredActor<MyActorType> actor)
{
_actor = actor.ActorRef;
}
public async Task<string> Say(string word)
{
return await _actor.Ask<string>(word, TimeSpan.FromSeconds(3));
}
}The IRequiredActor<MyActorType> will cause the Microsoft.Extensions.DependencyInjection mechanism to resolve MyActorType from the ActorRegistry and inject it into the IRequired<Actor<MyActorType> instance passed into MyConsumer.
The IRequiredActor<TActor> exposes a single property:
public interface IRequiredActor<TActor>
{
/// <summary>
/// The underlying actor resolved via <see cref="ActorRegistry"/> using the given <see cref="TActor"/> key.
/// </summary>
IActorRef ActorRef { get; }
}By default, you can automatically resolve any actors registered with the ActorRegistry without having to declare anything special on your IServiceCollection:
using var host = new HostBuilder()
.ConfigureServices(services =>
{
services.AddAkka("MySys", (builder, provider) =>
{
builder.WithActors((system, registry) =>
{
var actor = system.ActorOf(Props.Create(() => new MyActorType()), "myactor");
registry.Register<MyActorType>(actor);
});
});
services.AddScoped<MyConsumer>();
})
.Build();
await host.StartAsync();Adding your actor and your type key into the ActorRegistry is sufficient - no additional DI registration is required to access the IRequiredActor<TActor> for that type.
<a id="resolving-irequiredactortkey-within-akkanet"></a>
IRequiredActor<TKey> within Akka.NETAkka.NET does not use dependency injection to start actors by default primarily because actor lifetime is unbounded by default - this means reasoning about the scope of injected dependencies isn't trivial. ASP.NET, by contrast, is trivial: all HTTP requests are request-scoped and all web socket connections are connection-scoped - these are objects have bounded and typically short lifetimes.
Therefore, users have to explicitly signal when they want to use Microsoft.Extensions.DependencyInjection via the IDependencyResolver interface in Akka.DependencyInjection - which is easy to do in most of the Akka.Hosting APIs for starting actors:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IReplyGenerator, DefaultReplyGenerator>();
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.WithRemoting(hostname: "localhost", port: 8110)
.WithClustering(new ClusterOptions{SeedNodes = new []{ "akka.tcp://MyActorSystem@localhost:8110", }})
.WithShardRegion<Echo>(
typeName: "myRegion",
entityPropsFactory: (_, _, resolver) =>
{
// uses DI to inject `IReplyGenerator` into EchoActor
return s => resolver.Props<EchoActor>(s);
},
extractEntityId: ExtractEntityId,
extractShardId: ExtractShardId,
shardOptions: new ShardOptions());
});The dependencyResolver.Props<MySingletonDiActor>() call will leverage the ActorSystem's built-in IDependencyResolver to instantiate the MySingletonDiActor and inject it with all of the necessary dependencies, including IRequiredActor<TKey>.
<a id="microsoftextensionsconfiguration-integration"></a>
<a id="iconfiguration-to-hocon-adapter"></a>
The AddHocon extension method can convert Microsoft.Extensions.Configuration IConfiguration into HOCON Config instance and adds it to the ActorSystem being configured.
IConfiguration, all HOCON key names are case sensitive.IConfiguration key will be treated as a HOCON object key separatorIConfiguration does not support object composition, if you declare the same key multiple times inside multiple configuration providers (JSON/environment variables/etc), only the last one declared will take effect.Example:
appsettings.json:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"akka": {
"cluster": {
"roles": [ "front-end", "back-end" ],
"min-nr-of-members": 3,
"log-info": true
}
}
}Environment variables:
AKKA__ACTOR__TELEMETRY__ENABLE=true
AKKA__CLUSTER__SEED_NODES__0=akka.tcp//mySystem@localhost:4055
AKKA__CLUSTER__SEED_NODES__1=akka.tcp//mySystem@localhost:4056
AKKA__CLUSTER__SEED_NODE_TIMEOUT=00:00:05Note the integer parseable key inside the seed-nodes configuration, seed-nodes will be parsed as an array. These environment variables will be parsed as HOCON settings:
akka {
actor {
telemetry.enabled: on
}
cluster {
seed-nodes: [
"akka.tcp//mySystem@localhost:4055",
"akka.tcp//mySystem@localhost:4056"
]
seed-node-timeout: 5s
}
}Example code:
/*
Both appsettings.json and environment variables are combined
into HOCON configuration:
akka {
actor.telemetry.enabled: on
cluster {
roles: [ "front-end", "back-end" ]
seed-nodes: [
"akka.tcp//mySystem@localhost:4055",
"akka.tcp//mySystem@localhost:4056"
]
min-nr-of-members: 3
seed-node-timeout: 5s
log-info: true
}
}
*/
var host = new HostBuilder()
.ConfigureHostConfiguration(builder =>
{
// Setup IConfiguration to load from appsettings.json and
// environment variables
builder
.AddJsonFile("appsettings.json")
.AddEnvironmentVariables();
})
.ConfigureServices((context, services) =>
{
services.AddAkka("mySystem", (builder, provider) =>
{
// convert IConfiguration to HOCON
var akkaConfig = context.Configuration.GetSection("akka");
builder.AddHocon(akkaConfig, HoconAddMode.Prepend);
});
});This advanced usage of the IConfiguration adapter is solely used for edge cases where HOCON key capitalization needs to be preserved, such as declaring serialization binding. Note that when you're using this feature, none of the keys are normalized, you will have to write all of your keys in a HOCON compatible way.
appsettings.json:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"akka": {
"\"Key.With.Dots\"": "Key Value",
"cluster": {
"roles": [ "front-end", "back-end" ],
"min-nr-of-members": 3,
"log-info": true
}
}
}Note that "Key.With.Dots" needs to be inside escaped double quotes, this is a HOCON requirement that preserves the "." (period) inside HOCON property names.
Environment variables:
PS C:/> [Environment]::SetEnvironmentVariable('akka__actor__telemetry__enabled', 'true')
PS C:/> [Environment]::SetEnvironmentVariable('akka__actor__serialization_bindings__"System.Object"', 'hyperion')
PS C:/> [Environment]::SetEnvironmentVariable('akka__cluster__seed_nodes__0', 'akka.tcp//mySystem@localhost:4055')
PS C:/> [Environment]::SetEnvironmentVariable('akka__cluster__seed_nodes__1', 'akka.tcp//mySystem@localhost:4056')
PS C:/> [Environment]::SetEnvironmentVariable('akka__cluster__seed_node_timeout', '00:00:05')Note that:
Example code:
/*
Both appsettings.json and environment variables are combined
into HOCON configuration:
akka {
"Key.With.Dots": Key Value
actor {
telemetry.enabled: on
serialization-bindings {
"System.Object" = hyperion
}
}
cluster {
roles: [ "front-end", "back-end" ]
seed-nodes: [
"akka.tcp//mySystem@localhost:4055",
"akka.tcp//mySystem@localhost:4056"
]
min-nr-of-members: 3
seed-node-timeout: 5s
log-info: true
}
}
*/
var host = new HostBuilder()
.ConfigureHostConfiguration(builder =>
{
// Setup IConfiguration to load from appsettings.json and
// environment variables
builder
.AddJsonFile("appsettings.json")
.AddEnvironmentVariables();
})
.ConfigureServices((context, services) =>
{
services.AddAkka("mySystem", (builder, provider) =>
{
// convert IConfiguration to HOCON
var akkaConfig = context.Configuration.GetSection("akka");
// Note the last method argument is set to false
builder.AddHocon(akkaConfig, HoconAddMode.Prepend, false);
});
});<a id="microsoftextensionslogging-integration"></a>
<a id="logger-configuration-support"></a>
You can use AkkaConfigurationBuilder extension method called ConfigureLoggers(Action<LoggerConfigBuilder>) to configure how Akka.NET logger behave.
Example:
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.ConfigureLoggers(setup =>
{
// Example: This sets the minimum log level
setup.LogLevel = LogLevel.DebugLevel;
// Example: Clear all loggers
setup.ClearLoggers();
// Example: Add the default logger
// NOTE: You can also use setup.AddLogger<DefaultLogger>();
setup.AddDefaultLogger();
// Example: Add the ILoggerFactory logger
// NOTE:
// - You can also use setup.AddLogger<LoggerFactoryLogger>();
// - To use a specific ILoggerFactory instance, you can use setup.AddLoggerFactory(myILoggerFactory);
setup.AddLoggerFactory();
// Example: Adding a serilog logger
setup.AddLogger<SerilogLogger>();
})
.WithActors((system, registry) =>
{
var echo = system.ActorOf(act =>
{
act.ReceiveAny((o, context) =>
{
Logging.GetLogger(context.System, "echo").Info($"Actor received {o}");
context.Sender.Tell($"{context.Self} rcv {o}");
});
}, "echo");
registry.TryRegister<Echo>(echo); // register for DI
});
});A complete code sample can be viewed here.
Exposed properties are:
LogLevel: Configure the Akka.NET minimum log level filter, defaults to InfoLevelLogConfigOnStart: When set to true, Akka.NET will log the complete HOCON settings it is using at start up, this can then be used for debugging purposes.Currently supported logger methods:
ClearLoggers(): Clear all registered logger types.AddLogger<TLogger>(): Add a logger type by providing its class type.AddDefaultLogger(): Add the default Akka.NET console logger.AddLoggerFactory(): Add the new ILoggerFactory logger.<a id="microsoftextensionsloggingiloggerfactory-logging-support"></a>
You can now use ILoggerFactory from Microsoft.Extensions.Logging as one of the sinks for Akka.NET logger. This logger will use the ILoggerFactory service set up inside the dependency injection ServiceProvider as its sink.
<a id="serilog-support"></a>
If you're interested in using Akka.Logger.Serilog, you can set Akka.NET's default logger and log message formatter to allow for Serilog's semantic logging to be enabled by default:
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.ConfigureLoggers(setup =>
{
// Example: This sets the minimum log level
setup.LogLevel = LogLevel.DebugLevel;
// Example: Clear all loggers
setup.ClearLoggers();
// Add Serilog
setup.AddLogger<SerilogLogger>();
// use the default SerilogFormatter everywhere
setup.WithDefaultLogMessageFormatter<SerilogLogMessageFormatter>();
})
.WithActors((system, registry) =>
{
var echo = system.ActorOf(act =>
{
act.ReceiveAny((o, context) =>
{
Logging.GetLogger(context.System, "echo").Info($"Actor received {o}");
context.Sender.Tell($"{context.Self} rcv {o}");
});
}, "echo");
registry.TryRegister<Echo>(echo); // register for DI
});
});This will eliminate the need to have to do Context.GetLogger<SerilogLoggingAdapter>() everywhere you want to use it.
<a id="microsoftextensionslogging-log-event-filtering"></a>
There will be two log event filters acting on the final log input, the Akka.NET akka.loglevel setting and the Microsoft.Extensions.Logging settings, make sure that both are set correctly or some log messages will be missing.
To set up the Microsoft.Extensions.Logging log filtering, you will need to edit the appsettings.json file. Note that we also set the Akka namespace to be filtered at debug level in the example below.
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information",
"Akka": "Debug"
}
}
}<a id="opentelemetry-trace-correlation"></a>
Akka.NET processes log events asynchronously, which means Activity.Current does not flow across actor mailbox boundaries. To preserve trace correlation, Akka.Hosting captures the ActivityContext at log creation time and includes it in the log state. The AkkaTraceContextProcessor then applies that context to OpenTelemetry LogRecords so exporters can correlate logs with traces.
Minimal setup:
using Akka.Hosting;
using Akka.Hosting.Logging;
using OpenTelemetry.Logs;
using OpenTelemetry.Resources;
builder.Logging.AddOpenTelemetry(options =>
{
options.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("my-service"));
// Register before exporters
options.AddAkkaTraceCorrelation();
// Add OTLP exporter if you have not configured it elsewhere.
// Your mileage may vary; use the OpenTelemetry configuration that fits your app.
options.AddOtlpExporter();
});
builder.Services.AddAkka("MySystem", configBuilder =>
{
configBuilder.ConfigureLoggers(setup =>
{
setup.ClearLoggers();
setup.AddLoggerFactory();
});
});See the demo in src/Examples/Akka.Hosting.OpenTelemetry.AppHost and src/Examples/Akka.Hosting.OpenTelemetry.Demo for a working Aspire setup.
<a id="filtering-logs"></a>
In Akka.NET 1.5.21, we introduced log filtering for log messages based on the LogSource or the content of a log message. Depending on your coding style, you can use this feature in Akka.Hosting in several ways.
Using The LoggerConfigBuilder.WithLogFilter() method.
The LoggerConfigBuilder.WithLogFilter() method lets you set up the LogFilterBuilder
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.ConfigureLoggers(loggerConfigBuilder =>
{
loggerConfigBuilder.WithLogFilter(filterBuilder =>
{
filterBuilder.ExcludeMessageContaining("Test");
});
});
});
Setting the loggerConfigBuilder.LogFilterBuilder property directly.
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.ConfigureLoggers(loggerConfigBuilder =>
{
loggerConfigBuilder.LogFilterBuilder = new LogFilterBuilder();
loggerConfigBuilder.LogFilterBuilder.ExcludeMessageContaining("Test");
});
});
<a id="healthchecks"></a>
We've recently deprecated Akka.HealthChecks in favor of a simpler, more configurable solution that is built directly into Akka.Hosting: IAkkaHealthCheck and WithAkkaHealthCheck:
builder
.WithActorSystemLivenessCheck() // have to opt-in to the built-in health check
.WithHealthCheck("FooActor alive", async (system, registry, cancellationToken) =>
{
/*
* N.B. CancellationToken is set by the call to MSFT.EXT.DIAGNOSTICS.HEALTHCHECK,
* so that value could be "infinite" by default.
*
* Therefore, it might be a really, really good idea to guard this with a non-infinite
* timeout via a LinkedCancellationToken here.
*/
try
{
var fooActor = await registry.GetAsync<FooActor>(cancellationToken);
try
{
var r = await fooActor.Ask<ActorIdentity>(new Identify("foo"), cancellationToken: cancellationToken);
if (r.Subject.IsNobody())
return HealthCheckResult.Unhealthy("FooActor was alive but is now dead");
}
catch (Exception e)
{
return HealthCheckResult.Degraded("FooActor found but non-responsive", e);
}
}
catch (Exception e2)
{
return HealthCheckResult.Unhealthy("FooActor not found in registry", e2);
}
return HealthCheckResult.Healthy("fooActor found and responsive");
});These health checks and any other you register using one of the WithHealthCheck overloads on the AkkaConfigurationBuilder will automatically be registered with the Microsoft.Extensions.Diagnostics.HealthCheckService and will be called just like any other ASP.NET Core, Entity Framework, etc health check.
<a id="healthcheck-di"></a>
As of version 1.5.51, Akka.Hosting supports dependency injection for health checks. You can create custom health check classes that implement IAkkaHealthCheck and have dependencies injected from the DI container:
// Define a custom health check with DI support
public class MyHealthCheckWithDependencies : IAkkaHealthCheck
{
private readonly ILogger<MyHealthCheckWithDependencies> _logger;
private readonly IMyService _myService;
public MyHealthCheckWithDependencies(
ILogger<MyHealthCheckWithDependencies> logger,
IMyService myService)
{
_logger = logger;
_myService = myService;
}
public async Task<HealthCheckResult> CheckHealthAsync(
AkkaHealthCheckContext context,
CancellationToken cancellationToken = default)
{
try
{
_logger.LogInformation("Running health check with DI");
var isHealthy = await _myService.CheckServiceHealthAsync(cancellationToken);
return isHealthy
? HealthCheckResult.Healthy("Service is healthy")
: HealthCheckResult.Unhealthy("Service is not healthy");
}
catch (Exception ex)
{
_logger.LogError(ex, "Health check failed");
return HealthCheckResult.Unhealthy($"Health check failed: {ex.Message}");
}
}
}
// Register the health check using the generic WithHealthCheck<T>() method
builder
.WithActorSystemLivenessCheck()
.WithHealthCheck<MyHealthCheckWithDependencies>(
name: "MyServiceHealth",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready", "service" },
timeout: TimeSpan.FromSeconds(5));The health check type will be resolved from the DI container when the health check is executed, allowing you to leverage constructor injection for any dependencies your health check needs. The health check instance itself doesn't need to be registered in DI - Akka.Hosting will automatically resolve it using ActivatorUtilities.GetServiceOrCreateInstance<T>().
<a id="healthcheck-builtin"></a>
![NOTE] All Akka.NET health checks will be tagged with the
akkatag, so they can easily be filtered via the health check endpoints.
Akka.Hosting and its other packages ship with some built-in health checks:
WithActorSystemLivenessCheck() - a liveness probe that will fail if the ActorSystem is terminated. Generally, Akka.Hosting will try to shut down your process anyway if the ActorSystem dies.WithAkkaClusterReadinessCheck - if you are an Akka.Cluster user, this health check will return HealthStatus.Unhealthy until you successfully join a cluster - that way you can stop load-balancers and other devices from routing traffic to this node until it has access to the cluster. This readiness check is also tagged with the ready tag for filtering purposes.akka, persistence, and either journal or snapshot-store for filtering purposes.You can add health checks for your persistence plugins using the .WithHealthCheck() method when configuring journals and snapshot stores:
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
// Journal with health check
.WithJournal(
new SqlServerJournalOptions
{
ConnectionString = "...",
IsDefaultPlugin = true
},
journal => journal
.AddWriteEventAdapter<MyAdapter>("adapter", new[] { typeof(MyEvent) })
.WithHealthCheck(
unHealthyStatus: HealthStatus.Degraded,
name: "sql-journal"))
// Snapshot store with health check
.WithSnapshot(
new SqlServerSnapshotOptions
{
ConnectionString = "...",
IsDefaultPlugin = true
},
snapshot => snapshot
.WithHealthCheck(
unHealthyStatus: HealthStatus.Degraded,
name: "sql-snapshot"));
});You can also configure both journal and snapshot health checks together:
builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
{
configurationBuilder
.WithJournalAndSnapshot(
new SqlServerJournalOptions
{
ConnectionString = "...",
IsDefaultPlugin = true
},
new SqlServerSnapshotOptions
{
ConnectionString = "...",
IsDefaultPlugin = true
},
journal => journal.WithHealthCheck(),
snapshot => snapshot.WithHealthCheck());
});The health checks will automatically:
Healthy when the plugin is operationalDegraded or Unhealthy (configurable) when issues are detected