HealthChecks Instrumentation for OpenTelemetry .NET

This is an Instrumentation Library, which instruments Microsoft.Extensions.Diagnostics.HealthChecks and collect metrics about the application health checks.

Caution

This component is based on the v1.25 OpenTelemetry semantic conventions for metrics. These conventions are Mixed, and hence, this package is a pre-release. Until a stable version is released, there can be breaking changes. You can track the progress from milestones.

Supported .NET Versions

This package targets netstandard2.0 and hence can be used in any .NET versions implementing netstandard2.0.

Steps to enable HealthChecks.OpenTelemetry.Instrumentation

Step 1: Install package

Add a reference to the HealthChecks.OpenTelemetry.Instrumentation package:

dotnet add package HealthChecks.OpenTelemetry.Instrumentation

Step 2: Enable HealthChecks Instrumentation

HealthChecks instrumentation should be enabled at application startup using the AddHealthChecksInstrumentation extension on MeterProviderBuilder. The following example demonstrates adding HealthChecks instrumentation to a console application. This example also sets up the OpenTelemetry Console exporter, which requires adding the package OpenTelemetry.Exporter.Console to the application:

using OpenTelemetry;
using OpenTelemetry.Metrics;

public class Program
{
    public static void Main(string[] args)
    {
        using var meterProvider = Sdk.CreateMeterProviderBuilder()
            .AddHealthChecksInstrumentation()
            .AddConsoleExporter()
            .Build();
    }
}

For an ASP.NET Core application, adding instrumentation is typically done in the ConfigureServices of your Startup class. Refer to documentation for OpenTelemetry.Instrumentation.AspNetCore.

Refer to Program.cs for a complete demo.

Advanced configuration

This instrumentation can be configured to change the default behavior by using HealthChecksInstrumentationOptions:

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddHealthChecksInstrumentation(options =>
    {
        options.StatusGaugeName = "myapp.health";
        options.DurationGaugeName = "myapp.health.duration";
        options.IncludeHealthCheckMetadata = true;
    })
    .AddConsoleExporter()
    .Build();

When used with OpenTelemetry.Extensions.Hosting, all configurations to HealthChecksInstrumentationOptions can be done in the ConfigureServices method of you applications Startup class as shown below:

services.Configure<HealthChecksInstrumentationOptions>(options =>
{
    options.StatusGaugeName = "myapp.health";
    options.DurationGaugeName = "myapp.health.duration";
    options.IncludeHealthCheckMetadata = true;
});

services.AddOpenTelemetry()
    .WithMetrics(builder => builder
        .AddHealthChecksInstrumentation()
        .AddConsoleExporter());

Metrics

aspnetcore.healthcheck

Gets the health status of the component that was checked, converted to double value (0 == Unhealthy, 0.5 == Degraded, 1 == Healthy).

Units	Instrument Type	Value Type	Attribute Key(s)	Attribute Values
`status`	ObservableGauge	`Double`	name	name of each executed health check

The API used to retrieve the value is:

HealthReportEntry.Status: Gets the health status of the component that was checked.

aspnetcore.healthcheck.duration

Gets the health check execution duration.

Units	Instrument Type	Value Type	Attribute Key(s)	Attribute Values
`seconds`	ObservableGauge	`Double`	name	name of each executed health check