Introduce per-HealthCheck Delay and Period

[francedot]

In the current implementation, delay, periodicity of the healthchecks are set at the HealthCheckPublisherOptions configuration level and shared among all the HealthCheckRegistration:

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(10);
    options.Period = TimeSpan.FromSeconds(2);
});

API proposal is to introduce per-HealthCheck parameters to the HealthCheckRegistration used by IHealthChecksBuilder.Add(HealthCheckRegistration registration). Here is an example of how the new flavor of HealthChecks would be used:

builder.Services.AddHealthChecks()
   .Add(new HealthCheckRegistration(
               name: "SampleHealthCheck1",
               instance: new DelegateHealthCheck(_ => Task.FromResult(HealthCheckResult.Healthy(HealthyMessage))),
               failureStatus: null,
               tags: null,
               timeout: default,
               delay: TimeSpan.FromSeconds(40),
               period: TimeSpan.FromSeconds(30)));

Proposed API

HealthCheckRegistration.cs

namespace Microsoft.Extensions.Diagnostics.HealthChecks;

public sealed class HealthCheckRegistration
{
     public HealthCheckRegistration(string name, IHealthCheck instance, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout);
+    public HealthCheckRegistration(string name, IHealthCheck instance, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout, TimeSpan? delay);
+    public HealthCheckRegistration(string name, IHealthCheck instance, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout, TimeSpan? delay, TimeSpan? period);
     public HealthCheckRegistration(string name, Func<IServiceProvider, IHealthCheck> factory, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout);
+    public HealthCheckRegistration(string name, Func<IServiceProvider, IHealthCheck> factory, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout, TimeSpan? delay);
+    public HealthCheckRegistration(string name, Func<IServiceProvider, IHealthCheck> factory, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout, TimeSpan? delay, TimeSpan? period);

+    public TimeSpan? Delay { get; }
+    public TimeSpan? Period { get; }
}

Usage Examples

builder.Services.AddHealthChecks()
   .Add(new HealthCheckRegistration(
               name: "SampleHealthCheck1",
               instance: new DelegateHealthCheck(_ => Task.FromResult(HealthCheckResult.Healthy(HealthyMessage))),
               failureStatus: null,
               tags: null,
               timeout: default,
               delay: TimeSpan.FromSeconds(40),
               period: TimeSpan.FromSeconds(30)));

Alternative Designs

It might have been possible to implement HC periodicity by reusing the HC Registration Predicate delegate to condition the execution of the check instance i.e. <Timer_Run> * MULTIPLIER < HC_Periodicity. Although this would only to create HCs with periodicity set to a multiple of the default one.

Risks

Performance regressions due to multiple timers introduction in HealthCheckPublisherHostedService.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

API review notes:

• Let's make sure the proposed API matches the PR.
• Let's update the full proposed API to be a diff like the way the HealthChecksBuilderDelegateExtensions.cs section was edited.

[francedot]

API review notes:

• Let's make sure the proposed API matches the PR.
• Let's update the full proposed API to be a diff like the way the HealthChecksBuilderDelegateExtensions.cs section was edited.

These are now aligned with changes from related PR.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

API Review Notes:

• Do we need to add "Individual" in the new API names, or can we add new overloads?
  • We are worried that this would be a source breaking change without a new method name.
  • But only for AddIndividualTypeActivatedCheck, so let's only keep that as a non-overload.
• Do we want to add new async callbacks that don't take a CancellationToken?
  • This is the existing pattern, but we don't want to continue doing this.
• Can we make AddIndividualTypeActivatedCheck's TimeSpan parameters nullable?
• Task to ValueTask for AddAsyncCheck since the Func can probably complete immediately in many cases.

API Approved!

namespace Microsoft.Extensions.Diagnostics.HealthChecks;

public sealed class HealthCheckRegistration
{
     public HealthCheckRegistration(string name, IHealthCheck instance, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout);
+    public HealthCheckRegistration(string name, IHealthCheck instance, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout, TimeSpan? delay, TimeSpan? period);
     public HealthCheckRegistration(string name, Func<IServiceProvider, IHealthCheck> factory, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout);
+    public HealthCheckRegistration(string name, Func<IServiceProvider, IHealthCheck> factory, HealthStatus? failureStatus, IEnumerable<string>? tags, TimeSpan? timeout, TimeSpan? delay, TimeSpan? period);

+    public TimeSpan Delay { get; set; }
+    public TimeSpan Period { get; set; }
}

namespace Microsoft.Extensions.DependencyInjection;

public static HealthChecksBuilderAddCheckExtensions
{
     public static IHealthChecksBuilder AddCheck(this IHealthChecksBuilder builder, string name, IHealthCheck instance, HealthStatus? failureStatus = null, IEnumerable<string>? tags = null, TimeSpan? timeout = null);
+    public static IHealthChecksBuilder AddCheck(this IHealthChecksBuilder builder, string name, IHealthCheck instance, HealthStatus? failureStatus = null, IEnumerable<string>? tags = null, TimeSpan? timeout = null, TimeSpan? delay = null, TimeSpan? period = null);
+    public static IHealthChecksBuilder AddCheck<T>(this IHealthChecksBuilder builder, string name, HealthStatus? failureStatus = null, IEnumerable<string>? tags = null, TimeSpan? timeout = null, TimeSpan? delay = null, TimeSpan? period = null);
+    public static IHealthChecksBuilder AddIndividualTypeActivatedCheck<T>(this IHealthChecksBuilder builder, string name, HealthStatus? failureStatus, IEnumerable<string> tags, TimeSpan timeout, TimeSpan? delay, TimeSpan? period, params object[] args);
}

public static HealthChecksBuilderDelegateExtensions
{
     public static IHealthChecksBuilder AddCheck(this IHealthChecksBuilder builder, string name, Func<HealthCheckResult> check, IEnumerable<string>? tags = null, TimeSpan? timeout = default);
+    public static IHealthChecksBuilder AddAsyncCheck(this IHealthChecksBuilder builder, string name, Func<CancellationToken, ValueTask<HealthCheckResult>> check, IEnumerable<string>? tags = null, TimeSpan? timeout = null, TimeSpan? delay = null, TimeSpan? period = null);
+    public static IHealthChecksBuilder AddCheck(this IHealthChecksBuilder builder, string name, Func<HealthCheckResult> check, IEnumerable<string>? tags = null, TimeSpan? timeout = null, TimeSpan? delay = null, TimeSpan? period = null);
}