How to Set Up Production-Ready Monitoring With ASP.NET Core Health Checks

Deploying an application to production is only the beginning. You need to know whether your application is healthy and whether your database, cache, and message queue are reachable.

Without proper monitoring, you will only find out about issues when your users start complaining.

I have spent years building and maintaining high-load .NET systems, and health checks have always been my first line of defense. Today, I want to show you how to set up a production-ready monitoring system that gives you complete visibility into your application's health.

In this post, we will explore:

• Why health checks matter for production applications
• Adding health checks for Postgres, Redis, MongoDB, and RabbitMQ
• Building custom health checkers
• Building a custom JSON response formatter
• Implementing a custom health check publisher
• Setting up a professional Health Checks UI

Let's dive in.

When you run an application in a modern environment like Kubernetes or Azure, the platform needs to know if your app is ready to handle traffic. This is where health checks come in.

A health check is a simple endpoint that returns the status of your application. If the database or message queue is down, the health check should report that the service is "Unhealthy".

Without health checks:

• Load balancers might send traffic to a broken instance.
• You won't know about database connection issues until users report errors.
• Background tasks might stop running without anyone noticing.

ASP.NET Core provides a built-in framework for health checks. It allows you to check everything from database connections to external APIs and system resources.

To add health checks to your services, you need to install the following NuGet package:

bash
1dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks

Then you need to install the appropriate health-check packages for the external services you use.

I have built two services: ShippingService and OrderTrackingService. Each has different dependencies.

The ShippingService uses PostgreSQL and Entity Framework Core. We want to make sure the database is alive and that our DbContext is correctly configured.

You need to install the following NuGet packages:

bash
1dotnet add package AspNetCore.HealthChecks.NpgSql
2dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

In the HealthExtensions.cs file, we register our health checks:

csharp
1public static IServiceCollection AddHealth(this IServiceCollection services,
2    IConfiguration configuration)
3{
4    var postgresConnectionString = configuration.GetConnectionString("Postgres")!;
5
6    services.AddHealthChecks()
7        .AddDbContextCheck<ShippingDbContext>(
8            name: "database",
9            failureStatus: HealthStatus.Unhealthy,
10            tags: ["database"])
11
12        .AddNpgSql(
13            connectionString: postgresConnectionString,
14            name: "postgres",
15            failureStatus: HealthStatus.Unhealthy,
16            tags: ["database"]);
17
18    return services;
19}

• AddNpgSql: This check connects directly to the database using the connection string. It verifies that the PostgreSQL server is live and accepting connections.
• AddDbContextCheck: This check verifies that the Entity Framework Core DbContext can be created and can talk to the database. The database can be live, but your EF Core configuration can be broken. This check catches that.

To make your /health endpoint accessible, you need to map it in Program.cs:

csharp
1app.MapHealthChecks("/health");

You can customize the health check for DbContext by providing a custom test query. In this test query, you can access any entity and perform any operation:

csharp
1public static IServiceCollection AddHealth(this IServiceCollection services,
2    IConfiguration configuration)
3{
4    var postgresConnectionString = configuration.GetConnectionString("Postgres")!;
5
6    services.AddHealthChecks()
7        .AddDbContextCheck<ShippingDbContext>("Shipping database",
8            customTestQuery: CustomTestQueryAsync<ShippingDbContext, Shipment>)
9
10        .AddNpgSql(
11            connectionString: postgresConnectionString,
12            name: "postgres",
13            failureStatus: HealthStatus.Unhealthy,
14            tags: ["database"]);
15
16    return services;
17}
18
19private static async Task<bool> CustomTestQueryAsync<TDbContext, TEntity>(
20    TDbContext dbContext, CancellationToken token)
21    where TDbContext : DbContext
22    where TEntity : class
23{
24    var count = await dbContext.Set<TEntity>().CountAsync(token);
25    return count > 0;
26}

The OrderTrackingService uses MongoDB and Redis.

You need to install the following NuGet packages:

bash
1dotnet add package AspNetCore.HealthChecks.MongoDb
2dotnet add package AspNetCore.HealthChecks.Redis

This is how you can configure health checks for MongoDB and Redis:

csharp
1public static IServiceCollection AddHealth(this IServiceCollection services, IConfiguration configuration)
2{
3    var mongoDbConnectionString = configuration.GetConnectionString("MongoDb")!;
4    var redisConnectionString = configuration.GetConnectionString("Redis")!;
5
6    services.AddHealthChecks()
7        .AddMongoDb(
8            mongoDbConnectionString,
9            name: "mongodb",
10            failureStatus: HealthStatus.Unhealthy,
11            tags: ["database"])
12
13        .AddRedis(
14            name: "redis",
15            redisConnectionString: redisConnectionString);
16
17    return services;
18}

Both our services talk to each other via events over a message queue (RabbitMQ). We want to make sure the message queue is alive and that our consumers are running correctly.

The first option is to install the following NuGet package:

bash
1dotnet add package AspNetCore.HealthChecks.Rabbitmq

Or, if you use MassTransit in your project, it automatically registers its own health checks into the ASP.NET Core health check system. You don't need to add anything manually. MassTransit will report whether the message bus (e.g., RabbitMQ) is healthy and whether the consumers are running correctly.

It is registered automatically when you register MassTransit in your DI container.

csharp
1private static IServiceCollection AddMessageQueue(this IServiceCollection services,
2    IConfiguration configuration)
3{
4    var rabbitMqConfiguration = configuration
5        .GetSection(nameof(RabbitMQConfiguration))
6        .Get<RabbitMQConfiguration>()!;
7
8    services.AddMassTransit(busConfig =>
9    {
10        busConfig.SetKebabCaseEndpointNameFormatter();
11
12        busConfig.UsingRabbitMq((context, cfg) =>
13        {
14            cfg.Host(new Uri(rabbitMqConfiguration.Host), h =>
15            {
16                h.Username(rabbitMqConfiguration.Username);
17                h.Password(rabbitMqConfiguration.Password);
18            });
19
20            cfg.ConfigureEndpoints(context);
21        });
22    });
23
24    return services;
25}

When adding health checks to your project, I recommend starting by looking for a ready-made NuGet package. If you can't find one, you can create a custom health checker.

For example, you should track the free disk space on your server. System resources are just as important as external services. If your server runs out of disk space, your application will crash.

We can create a custom health checker by implementing the IHealthCheck interface. Here is a DiskSpaceHealthCheck that monitors free space on a drive:

csharp
1public sealed class DiskSpaceHealthCheck : IHealthCheck
2{
3    private readonly string _path;
4    private readonly long _minFreeBytes;
5
6    public DiskSpaceHealthCheck(string path, long minFreeBytes)
7    {
8        _path = path;
9        _minFreeBytes = minFreeBytes;
10    }
11
12    public Task<HealthCheckResult> CheckHealthAsync(
13        HealthCheckContext context,
14        CancellationToken cancellationToken = default)
15    {
16        var drive = new DriveInfo(_path);
17
18        if (!drive.IsReady)
19        {
20            return Task.FromResult(HealthCheckResult.Unhealthy("Disk is not ready."));
21        }
22
23        var free = drive.AvailableFreeSpace;
24
25        if (free < _minFreeBytes)
26        {
27            return Task.FromResult(
28                HealthCheckResult.Degraded($"Low disk space. Free bytes: {free}."));
29        }
30
31        return Task.FromResult(
32            HealthCheckResult.Healthy($"Disk space OK. Free bytes: {free}."));
33    }
34}

Then we register it in our AddHealth method:

csharp
1services.AddHealthChecks()
2    .AddCheck(name: "disk-space",
3        instance: new DiskSpaceHealthCheck(path: "C:/", minFreeBytes: 500_000_000));

By default, the /health endpoint returns a simple "Healthy" or "Unhealthy" string. In a production environment, you need more details. You want to see which specific check failed and why.

We can create a HealthCheckJsonResponseWriter to return a structured JSON response:

csharp
1public static class HealthCheckJsonResponseWriter
2{
3    private static readonly JsonSerializerOptions JsonSerializerOptions
4        = new JsonSerializerOptions
5    {
6        WriteIndented = false,
7        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
8        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
9    };
10
11    public static Task WriteResponse(HttpContext context, HealthReport report)
12    {
13        var json = JsonSerializer.Serialize(
14            new
15            {
16                Status = report.Status.ToString(),
17                Duration = report.TotalDuration,
18                Info = report.Entries
19                    .Select(e => new
20                    {
21                        Key = e.Key,
22                        Description = e.Value.Description,
23                        Duration = e.Value.Duration,
24                        Status = Enum.GetName(e.Value.Status),
25                        Error = e.Value.Exception?.Message,
26                        Data = e.Value.Data,
27                        Tags = e.Value.Tags
28                    })
29                    .ToList()
30            },
31            JsonSerializerOptions);
32
33        context.Response.ContentType = MediaTypeNames.Application.Json;
34        return context.Response.WriteAsync(json);
35    }
36}

Now, when you map your health checks in Program.cs, you use this writer:

csharp
1app.MapHealthChecks("/health", new HealthCheckOptions
2{
3    Predicate = _ => true,
4    ResponseWriter = HealthCheckJsonResponseWriter.WriteResponse
5});

Let's run our service and test our health endpoints:

ShippingService:

json
1{
2  "status": "Healthy",
3  "totalDuration": "00:00:00.0415370",
4  "entries": {
5    "masstransit-bus": {
6      "data": {
7        "Endpoints": {
8          "rabbitmq://127.0.0.1/PC_ShippingService_bus?temporary=true": {
9            "status": "Healthy",
10            "description": "ready (not started)"
11          }
12        }
13      },
14      "description": "Ready",
15      "duration": "00:00:00.0000459",
16      "status": "Healthy",
17      "tags": [
18        "ready",
19        "masstransit"
20      ]
21    },
22    "database": {
23      "data": {
24
25      },
26      "duration": "00:00:00.0413031",
27      "status": "Healthy",
28      "tags": [
29        "database"
30      ]
31    },
32    "postgres": {
33      "data": {
34
35      },
36      "duration": "00:00:00.0011592",
37      "status": "Healthy",
38      "tags": [
39        "database"
40      ]
41    },
42    "disk-space": {
43      "data": {
44
45      },
46      "description": "Disk space OK. Free bytes: 179225227264.",
47      "duration": "00:00:00.0001174",
48      "status": "Healthy",
49      "tags": []
50    }
51  }
52}

OrderTrackingService:

json
1{
2  "status": "Healthy",
3  "totalDuration": "00:00:00.0019189",
4  "entries": {
5    "masstransit-bus": {
6      "data": {
7        "Endpoints": {
8          "rabbitmq://127.0.0.1/shipment-created-order-tracking-service": {
9            "status": "Healthy",
10            "description": "ready"
11          },
12          "rabbitmq://127.0.0.1/shipment-status-updated-order-tracking-service": {
13            "status": "Healthy",
14            "description": "ready"
15          },
16          "rabbitmq://127.0.0.1/PC_OrderTrackingService_bus?temporary=true": {
17            "status": "Healthy",
18            "description": "ready (not started)"
19          }
20        }
21      },
22      "description": "Ready",
23      "duration": "00:00:00.0000527",
24      "status": "Healthy",
25      "tags": [
26        "ready",
27        "masstransit"
28      ]
29    },
30    "mongodb": {
31      "data": {
32
33      },
34      "duration": "00:00:00.0011671",
35      "status": "Healthy",
36      "tags": [
37        "database"
38      ]
39    },
40    "redis": {
41      "data": {
42
43      },
44      "duration": "00:00:00.0018187",
45      "status": "Healthy",
46      "tags": []
47    }
48  }
49}

If your application becomes unhealthy, you want to know about it immediately. While you can monitor the endpoint, it can be useful to check your health status in your application itself.

We can implement IHealthCheckPublisher. This publisher runs in the background at regular intervals.

This is a simple implementation that logs changes in health reports:

csharp
1public class MonitoringHealthCheckPublisher(
2    ILogger<MonitoringHealthCheckPublisher> logger) : IHealthCheckPublisher
3{
4 private readonly JsonSerializerOptions _jsonSerializerOptions = new()
5    {
6     WriteIndented = true,
7     Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
8     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
9     Converters =
10     {
11      new JsonStringEnumConverter()
12     }
13    };
14
15    private HealthReport? _lastReport;
16
17    public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
18    {
19        // Log only changes in health reports
20        if (_lastReport is null || !HealthReportsAreEqual(report, _lastReport))
21        {
22            logger.LogInformation("Health report has changed. Status: {Status}, Duration: {Duration}, Report: {Report}", report.Status, report.TotalDuration,
23                JsonSerializer.Serialize(report, _jsonSerializerOptions));
24        }
25
26        _lastReport = report;
27
28        return Task.CompletedTask;
29    }
30}

Register the publisher and configure how often it should run:

csharp
1services.AddSingleton<IHealthCheckPublisher, MonitoringHealthCheckPublisher>();
2
3services.Configure<HealthCheckPublisherOptions>(options =>
4{
5    options.Period = TimeSpan.FromSeconds(60);
6});

You can also inject the HealthCheckService into any of your classes and check the Health status on demand:

csharp
1public async Task<HealthStatus> GetCurrentHealthStatusAsync()
2{
3    var report = await _healthCheckService.CheckHealthAsync(CancellationToken.None);
4
5    if (report.Status == HealthStatus.Unhealthy)
6    {
7        logger.LogInformation("Application is unhealthy!");
8        
9        foreach (var entry in report.Entries)
10        {
11            logger.LogInformation("Entry is unhealthy: {@Entry}", entry);
12        }
13    }
14
15    return report.Status;
16}

Visualizing health checks makes it much easier to monitor your system. The AspNetCore.HealthChecks.UI package provides a web dashboard that aggregates health data from all your services.

You can explore the Health Checks UI GitHub repository for more information.

First, add the following NuGet packages:

bash
1dotnet add package AspNetCore.HealthChecks.UI
2dotnet add package AspNetCore.HealthChecks.UI.Client
3dotnet add package AspNetCore.HealthChecks.UI.InMemory.Storage

Then, register the UI services:

csharp
1services
2    .AddHealthChecksUI(options =>
3    {
4        options.AddHealthCheckEndpoint("Shipping Service API", "/health");
5    })
6    .AddInMemoryStorage();

Here, we use an in-memory storage provider for storing health reports while the application is running.

In production, depending on your needs, you may need to persist these results into the database. Explore more persistence options for your Health Checks UI in the GitHub repository.

Then, map the UI endpoints in Program.cs:

csharp
1app.MapHealthChecks("/health", new HealthCheckOptions
2{
3    Predicate = _ => true,
4    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
5});
6
7app.MapHealthChecksUI(options =>
8{
9    options.UIPath = "/health-ui";
10    options.ApiPath = "/health-ui-api";
11});

Note: for health-ui to be able to parse the health check responses, you need to use the UIResponseWriter.WriteHealthCheckUIResponse type. This type comes from the AspNetCore.HealthChecks.UI.Client NuGet package.

Now you can visit /health-ui to see a professional dashboard showing the health of all your services and their dependencies:

Shippingservice:

OrderTrackingService:

Important note: In production you should not make Health endpoint and UI visible in public. You need to secure access to these endpoints with authentication and authorization. You can configure this with a RequireAuthorization method:

csharp
1app.MapHealthChecks("/health", new HealthCheckOptions
2{
3    Predicate = _ => true,
4    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
5}).RequireAuthorization(RoleConsts.RoleAdmin);

You can find more information about authorization for the UI in the GitHub repository.

Setting up health checks is one of the most important things you can do for your production application. It provides visibility and enables your infrastructure to automatically respond to failures.

If you want to increase your application's visibility, I recommend adding OpenTelemetry.

Health checks show what components of your application are working correctly. OpenTelemetry, on the other hand, provides a complete view of your application's performance, your request flows and what data is being processed.

To get started with OpenTelemetry, you can follow my article.

Hope you find this newsletter useful. See you next time.