Redesign HealthStatus (again) (#520)

* Redesign HealthStatus (again)

This change brings back the ability to return Healthy/Degraded/Unhealthy
in a HealthCheckResult. We tried making this pass/fail in 2.2.0-preview3
and folks writing health checks for their own use pointed out (rightly
so) that it was too limited.

It's still possible for the app developer to configure the failure
status of a health check, but it requires the health check author to
cooperate.

I also got rid of HealthStatus.Failed since it raises more questions
than it answers. It's really not clear that it's valuable for a health
check for behave different when throwing an unhandled exception.

We would still recommend that a health check library handle exceptions
that they know about and return `context.Registration.FailureStatus`.

Author: rynowak

samples/HealthChecksSample/DbConnectionHealthCheck.cs

@@ -51,11 +51,11 @@ protected DbConnectionHealthCheck(string connectionString, string testQuery)
                 }
                 catch (DbException ex)
                 {
-                    return HealthCheckResult.Failed(exception: ex);
+                    return new HealthCheckResult(status: context.Registration.FailureStatus, exception: ex);
                 }
             }
 
-            return HealthCheckResult.Passed();
+            return HealthCheckResult.Healthy();
         }
     }
 }

samples/HealthChecksSample/GCInfoHealthCheck.cs

@@ -65,13 +65,15 @@ public GCInfoHealthCheck(IOptionsMonitor<GCInfoOptions> options)
                 { "Gen2Collections", GC.CollectionCount(2) },
             };
 
-            // Report failure if the allocated memory is >= the threshold. Negated because true == success
-            var result = !(allocated >= options.Threshold);
+            // Report failure if the allocated memory is >= the threshold.
+            //
+            // Using context.Registration.FailureStatus means that the application developer can configure
+            // how they want failures to appear.
+            var result = allocated >= options.Threshold ? context.Registration.FailureStatus : HealthStatus.Healthy;
 
             return Task.FromResult(new HealthCheckResult(
                 result,
                 description: "reports degraded status if allocated bytes >= 1gb",
-                exception: null,
                 data: data));
         }
     }

samples/HealthChecksSample/SlowDependencyHealthCheck.cs

@@ -21,10 +21,12 @@ public SlowDependencyHealthCheck()
         {
             if (_task.IsCompleted)
             {
-                return Task.FromResult(HealthCheckResult.Passed("Dependency is ready"));
+                return Task.FromResult(HealthCheckResult.Healthy("Dependency is ready"));
             }
 
-            return Task.FromResult(HealthCheckResult.Failed("Dependency is still initializing"));
+            return Task.FromResult(new HealthCheckResult(
+                status: context.Registration.FailureStatus, 
+                description: "Dependency is still initializing"));
         }
     }
 }

src/Microsoft.AspNetCore.Diagnostics.HealthChecks/HealthCheckOptions.cs

@@ -33,9 +33,6 @@ public class HealthCheckOptions
             { HealthStatus.Healthy, StatusCodes.Status200OK },
             { HealthStatus.Degraded, StatusCodes.Status200OK },
             { HealthStatus.Unhealthy, StatusCodes.Status503ServiceUnavailable },
-
-            // This means that a health check failed, so 500 is appropriate. This is an error.
-            { HealthStatus.Failed, StatusCodes.Status500InternalServerError },
         };
 
         /// <summary>

src/Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions/HealthCheckResult.cs

@@ -14,16 +14,16 @@ public struct HealthCheckResult
         private static readonly IReadOnlyDictionary<string, object> _emptyReadOnlyDictionary = new Dictionary<string, object>();
 
         /// <summary>
-        /// Creates a new <see cref="HealthCheckResult"/> with the specified values for <paramref name="result"/>, <paramref name="exception"/>,
-        /// <paramref name="description"/>, and <paramref name="data"/>.
+        /// Creates a new <see cref="HealthCheckResult"/> with the specified values for <paramref name="status"/>, 
+        /// <paramref name="exception"/>, <paramref name="description"/>, and <paramref name="data"/>.
         /// </summary>
-        /// <param name="result">A value indicating the pass/fail status of the component that was checked.</param>
+        /// <param name="status">A value indicating the status of the component that was checked.</param>
         /// <param name="description">A human-readable description of the status of the component that was checked.</param>
         /// <param name="exception">An <see cref="Exception"/> representing the exception that was thrown when checking for status (if any).</param>
         /// <param name="data">Additional key-value pairs describing the health of the component.</param>
-        public HealthCheckResult(bool result, string description, Exception exception, IReadOnlyDictionary<string, object> data)
+        public HealthCheckResult(HealthStatus status, string description = null, Exception exception = null, IReadOnlyDictionary<string, object> data = null)
         {
-            Result = result;
+            Status = status;
             Description = description;
             Exception = exception;
             Data = data ?? _emptyReadOnlyDictionary;
@@ -45,33 +45,44 @@ public HealthCheckResult(bool result, string description, Exception exception, I
         public Exception Exception { get; }
 
         /// <summary>
-        /// Gets a value indicating the pass/fail status of the component that was checked. If <c>true</c>, then the component 
-        /// is considered to have passed health validation. A <c>false</c> value will be mapped to the configured 
-        /// <see cref="HealthStatus"/> by  the health check system.
+        /// Gets a value indicating the status of the component that was checked.
         /// </summary>
-        public bool Result { get; }
+        public HealthStatus Status { get; }
 
         /// <summary>
-        /// Creates a <see cref="HealthCheckResult"/> representing a passing component.
+        /// Creates a <see cref="HealthCheckResult"/> representing a healthy component.
         /// </summary>
-        /// <returns>A <see cref="HealthCheckResult"/> representing a passing component.</returns>
         /// <param name="description">A human-readable description of the status of the component that was checked. Optional.</param>
         /// <param name="data">Additional key-value pairs describing the health of the component. Optional.</param>
-        public static HealthCheckResult Passed(string description = null, IReadOnlyDictionary<string, object> data = null)
+        /// <returns>A <see cref="HealthCheckResult"/> representing a healthy component.</returns>
+        public static HealthCheckResult Healthy(string description = null, IReadOnlyDictionary<string, object> data = null)
         {
-            return new HealthCheckResult(result: true, description, exception: null, data);
+            return new HealthCheckResult(status: HealthStatus.Healthy, description, exception: null, data);
+        }
+
+
+        /// <summary>
+        /// Creates a <see cref="HealthCheckResult"/> representing a degraded component.
+        /// </summary>
+        /// <param name="description">A human-readable description of the status of the component that was checked. Optional.</param>
+        /// <param name="exception">An <see cref="Exception"/> representing the exception that was thrown when checking for status. Optional.</param>
+        /// <param name="data">Additional key-value pairs describing the health of the component. Optional.</param>
+        /// <returns>A <see cref="HealthCheckResult"/> representing a degraged component.</returns>
+        public static HealthCheckResult Degraded(string description = null, Exception exception = null, IReadOnlyDictionary<string, object> data = null)
+        {
+            return new HealthCheckResult(status: HealthStatus.Degraded, description, exception: null, data);
         }
 
         /// <summary>
-        /// Creates a <see cref="HealthCheckResult"/> representing an failing component.
+        /// Creates a <see cref="HealthCheckResult"/> representing an unhealthy component.
         /// </summary>
         /// <param name="description">A human-readable description of the status of the component that was checked. Optional.</param>
         /// <param name="exception">An <see cref="Exception"/> representing the exception that was thrown when checking for status. Optional.</param>
         /// <param name="data">Additional key-value pairs describing the health of the component. Optional.</param>
-        /// <returns>A <see cref="HealthCheckResult"/> representing an failing component.</returns>
-        public static HealthCheckResult Failed(string description = null, Exception exception = null, IReadOnlyDictionary<string, object> data = null)
+        /// <returns>A <see cref="HealthCheckResult"/> representing an unhealthy component.</returns>
+        public static HealthCheckResult Unhealthy(string description = null, Exception exception = null, IReadOnlyDictionary<string, object> data = null)
         {
-            return new HealthCheckResult(result: false, description, exception, data);
+            return new HealthCheckResult(status: HealthStatus.Unhealthy, description, exception, data);
         }
     }
 }

src/Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions/HealthReport.cs

@@ -54,7 +54,7 @@ private HealthStatus CalculateAggregateStatus(IEnumerable<HealthReportEntry> ent
                     currentValue = entry.Status;
                 }
 
-                if (currentValue == HealthStatus.Failed)
+                if (currentValue == HealthStatus.Unhealthy)
                 {
                     // Game over, man! Game over!
                     // (We hit the worst possible status, so there's no need to keep iterating)

src/Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions/HealthReportEntry.cs

@@ -52,8 +52,7 @@ public HealthReportEntry(HealthStatus status, string description, TimeSpan durat
         public Exception Exception { get; }
 
         /// <summary>
-        /// Gets the health status of the component that was checked. The <see cref="Status"/> is based on the pass/fail value of
-        /// <see cref="HealthCheckResult.Passed"/> and the configured value of <see cref="HealthCheckRegistration.FailureStatus"/>.
+        /// Gets the health status of the component that was checked.
         /// </summary>
         public HealthStatus Status { get; }
     }

src/Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions/HealthStatus.cs

@@ -8,10 +8,6 @@ namespace Microsoft.Extensions.Diagnostics.HealthChecks
     /// </summary>
     /// <remarks>
     /// <para>
-    /// A health status is derived the pass/fail result of an <see cref="IHealthCheck"/> (<see cref="HealthCheckResult.Result"/>)
-    /// and the corresponding value of <see cref="HealthCheckRegistration.FailureStatus"/>.
-    /// </para>
-    /// <para>
     /// A status of <see cref="Unhealthy"/> should be considered the default value for a failing health check. Application
     /// developers may configure a health check to report a different status as desired.
     /// </para>
@@ -23,23 +19,19 @@ namespace Microsoft.Extensions.Diagnostics.HealthChecks
     public enum HealthStatus
     {
         /// <summary>
-        /// Indicates that an unexpected exception was thrown when running the health check.
-        /// </summary>
-        Failed = 0,
-
-        /// <summary>
-        /// Indicates that the health check determined that the component was unhealthy.
+        /// Indicates that the health check determined that the component was unhealthy, or an unhandled
+        /// exception was thrown while executing the health check.
         /// </summary>
-        Unhealthy = 1,
+        Unhealthy = 0,
 
         /// <summary>
         /// Indicates that the health check determined that the component was in a degraded state.
         /// </summary>
-        Degraded = 2,
+        Degraded = 1,
 
         /// <summary>
         /// Indicates that the health check determined that the component was healthy.
         /// </summary>
-        Healthy = 3,
+        Healthy = 2,
     }
 }

src/Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore/DbContextHealthCheck.cs

@@ -47,10 +47,10 @@ public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context
 
             if (await testQuery(_dbContext, cancellationToken))
             {
-                return HealthCheckResult.Passed();
+                return HealthCheckResult.Healthy();
             }
 
-            return HealthCheckResult.Failed();
+            return HealthCheckResult.Unhealthy();
         }
     }
 }

src/Microsoft.Extensions.Diagnostics.HealthChecks/DefaultHealthCheckService.cs

@@ -76,7 +76,7 @@ public override async Task<HealthReport> CheckHealthAsync(
                             var duration = stopwatch.GetElapsedTime();
 
                             entry = new HealthReportEntry(
-                                status: result.Result ? HealthStatus.Healthy : registration.FailureStatus,
+                                status: result.Status,
                                 description: result.Description,
                                 duration: duration,
                                 exception: result.Exception,
@@ -91,7 +91,7 @@ public override async Task<HealthReport> CheckHealthAsync(
                         {
                             var duration = stopwatch.GetElapsedTime();
                             entry = new HealthReportEntry(
-                                status: HealthStatus.Failed,
+                                status: HealthStatus.Unhealthy,
                                 description: ex.Message,
                                 duration: duration,
                                 exception: ex,
@@ -212,10 +212,6 @@ public static void HealthCheckEnd(ILogger logger, HealthCheckRegistration regist
                     case HealthStatus.Unhealthy:
                         _healthCheckEndUnhealthy(logger, registration.Name, duration.TotalMilliseconds, entry.Status, entry.Description, null);
                         break;
-
-                    case HealthStatus.Failed:
-                        _healthCheckEndFailed(logger, registration.Name, duration.TotalMilliseconds, entry.Status, entry.Description, null);
-                        break;
                 }
             }