Pemeriksaan kesehatan di ASP.NET Core
Oleh Glenn Condron dan Juergen Gutsch
Catatan
Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.
Peringatan
Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.
Penting
Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.
Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.
ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.
Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:
- Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
- Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
- Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.
Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.
Pemeriksaan kesehatan dasar
Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.
Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis HealthStatus sebagai respons teks biasa terhadap klien. adalah HealthStatus
HealthStatus.Healthy, HealthStatus.Degraded, atau HealthStatus.Unhealthy.
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Program.cs
. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks.
Contoh berikut membuat titik akhir pemeriksaan kesehatan di /healthz
:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();
var app = builder.Build();
app.MapHealthChecks("/healthz");
app.Run();
Buruh kapal HEALTHCHECK
Docker menawarkan arahan bawaan HEALTHCHECK
yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:
HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit
Contoh sebelumnya menggunakan curl
untuk membuat permintaan HTTP ke titik akhir pemeriksaan kesehatan di /healthz
. curl
tidak disertakan dalam gambar kontainer Linux .NET, tetapi dapat ditambahkan dengan menginstal paket yang diperlukan di Dockerfile. Kontainer yang menggunakan gambar berdasarkan Alpine Linux dapat menggunakan yang disertakan wget
sebagai pengganti curl
.
Membuat pemeriksaan kesehatan
Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy
, , Degraded
atau Unhealthy
. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi. Konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan. HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.
Contoh berikut menunjukkan tata letak pemeriksaan kesehatan:
public class SampleHealthCheck : IHealthCheck
{
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
var isHealthy = true;
// ...
if (isHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("A healthy result."));
}
return Task.FromResult(
new HealthCheckResult(
context.Registration.FailureStatus, "An unhealthy result."));
}
}
Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync metode . Contoh sebelumnya menetapkan variabel dummy, , isHealthy
ke true
. Jika nilai isHealthy
diatur ke false
, HealthCheckRegistration.FailureStatus status dikembalikan.
Jika CheckHealthAsync melempar pengecualian selama pemeriksaan, yang baru HealthReportEntry dikembalikan dengan HealthReportEntry.Status diatur ke FailureStatus. Status ini ditentukan oleh AddCheck (lihat bagian Daftarkan layanan pemeriksaan kesehatan) dan menyertakan pengecualian dalam yang menyebabkan kegagalan pemeriksaan. Description diatur ke pesan pengecualian.
Mendaftarkan layanan pemeriksaan kesehatan
Untuk mendaftarkan layanan pemeriksaan kesehatan, hubungi AddCheck di Program.cs
:
builder.Services.AddHealthChecks()
.AddCheck<SampleHealthCheck>("Sample");
Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null
(default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.
Tag dapat digunakan untuk memfilter pemeriksaan kesehatan. Tag dijelaskan di bagian Filter pemeriksaan kesehatan.
builder.Services.AddHealthChecks()
.AddCheck<SampleHealthCheck>(
"Sample",
failureStatus: HealthStatus.Degraded,
tags: new[] { "sample" });
AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, pemeriksaan kesehatan selalu mengembalikan hasil yang sehat:
builder.Services.AddHealthChecks()
.AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));
Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, pemeriksaan kesehatan yang diaktifkan jenis menerima bilangan bulat dan string dalam konstruktornya:
public class SampleHealthCheckWithArgs : IHealthCheck
{
private readonly int _arg1;
private readonly string _arg2;
public SampleHealthCheckWithArgs(int arg1, string arg2)
=> (_arg1, _arg2) = (arg1, arg2);
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
// ...
return Task.FromResult(HealthCheckResult.Healthy("A healthy result."));
}
}
Untuk mendaftarkan pemeriksaan kesehatan sebelumnya, panggil AddTypeActivatedCheck
dengan bilangan bulat dan string yang diteruskan sebagai argumen:
builder.Services.AddHealthChecks()
.AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
"Sample",
failureStatus: HealthStatus.Degraded,
tags: new[] { "sample" },
args: new object[] { 1, "Arg" });
Gunakan Perutean Pemeriksaan Kesehatan
Di Program.cs
, panggil MapHealthChecks
pembangun titik akhir dengan URL titik akhir atau jalur relatif:
app.MapHealthChecks("/healthz");
Memerlukan host
Panggil RequireHost
untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima:
app.MapHealthChecks("/healthz")
.RequireHost("www.contoso.com:5001");
Untuk membatasi titik akhir pemeriksaan kesehatan untuk merespons hanya pada port tertentu, tentukan port dalam panggilan ke RequireHost
. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan:
app.MapHealthChecks("/healthz")
.RequireHost("*:5001");
Peringatan
API yang bergantung pada header Host, seperti HttpRequest.Host dan RequireHost, tunduk pada potensi spoofing oleh klien.
Untuk mencegah spoofing host dan port, gunakan salah satu pendekatan berikut:
- Gunakan HttpContext.Connection (ConnectionInfo.LocalPort) tempat port diperiksa.
- Menggunakan pemfilteran Host.
Untuk mencegah klien yang tidak sah melakukan spoofing port, panggil RequireAuthorization:
app.MapHealthChecks("/healthz")
.RequireHost("*:5001")
.RequireAuthorization();
Untuk informasi selengkapnya, lihat Pencocokan host dalam rute dengan RequireHost.
Memerlukan otorisasi
Panggil RequireAuthorization untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization
beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default akan digunakan:
app.MapHealthChecks("/healthz")
.RequireAuthorization();
Mengaktifkan Permintaan Lintas Asal (CORS)
Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors
titik akhir pemeriksaan kesehatan. Kelebihan RequireCors
beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder
) atau nama kebijakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.
Opsi pemeriksaan kesehatan
HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:
- Memfilter pemeriksaan kesehatan
- Mengkustomisasi kode status HTTP
- Menyembunyikan header cache
- Sesuaikan output
Memfilter pemeriksaan kesehatan
Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi .
Contoh berikut memfilter pemeriksaan kesehatan sehingga hanya yang ditandai dengan sample
eksekusi:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});
Mengkustomisasi kode status HTTP
Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Degraded] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});
Menyembunyikan header cache
AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false
default), middleware mengatur atau mengambil Cache-Control
alih header , , Expires
dan Pragma
untuk mencegah penembolokan respons. Jika nilainya adalah true
, middleware tidak mengubah header cache respons:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
AllowCachingResponses = true
});
Sesuaikan output
Untuk menyesuaikan output laporan pemeriksaan kesehatan, atur HealthCheckOptions.ResponseWriter properti ke delegasi yang menulis respons:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
ResponseWriter = WriteResponse
});
Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Status
string . Delegasi kustom berikut menghasilkan respons JSON kustom menggunakan System.Text.Json:
private static Task WriteResponse(HttpContext context, HealthReport healthReport)
{
context.Response.ContentType = "application/json; charset=utf-8";
var options = new JsonWriterOptions { Indented = true };
using var memoryStream = new MemoryStream();
using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
{
jsonWriter.WriteStartObject();
jsonWriter.WriteString("status", healthReport.Status.ToString());
jsonWriter.WriteStartObject("results");
foreach (var healthReportEntry in healthReport.Entries)
{
jsonWriter.WriteStartObject(healthReportEntry.Key);
jsonWriter.WriteString("status",
healthReportEntry.Value.Status.ToString());
jsonWriter.WriteString("description",
healthReportEntry.Value.Description);
jsonWriter.WriteStartObject("data");
foreach (var item in healthReportEntry.Value.Data)
{
jsonWriter.WritePropertyName(item.Key);
JsonSerializer.Serialize(jsonWriter, item.Value,
item.Value?.GetType() ?? typeof(object));
}
jsonWriter.WriteEndObject();
jsonWriter.WriteEndObject();
}
jsonWriter.WriteEndObject();
jsonWriter.WriteEndObject();
}
return context.Response.WriteAsync(
Encoding.UTF8.GetString(memoryStream.ToArray()));
}
API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json
, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.
Pemeriksaan database
Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.
AspNetCore.Diagnostics.HealthChecks
, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, menyertakan pemeriksaan kesehatan yang berjalan terhadap database SQL Server. AspNetCore.Diagnostics.HealthChecks
SELECT 1
menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.
Peringatan
Saat memeriksa koneksi database dengan kueri, pilih kueri yang kembali dengan cepat. Pendekatan kueri menjalankan risiko kelebihan beban database dan menurunkan performanya. Dalam kebanyakan kasus, menjalankan kueri pengujian tidak diperlukan. Hanya membuat koneksi yang berhasil ke database sudah cukup. Jika Anda merasa perlu menjalankan kueri, pilih kueri SELECT sederhana, seperti SELECT 1
.
Untuk menggunakan pemeriksaan kesehatan SQL Server ini, sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer
paket NuGet. Contoh berikut mendaftarkan pemeriksaan kesehatan SQL Server:
var conStr = builder.Configuration.GetConnectionString("DefaultConnection");
if (string.IsNullOrEmpty(conStr))
{
throw new InvalidOperationException(
"Could not find a connection string named 'DefaultConnection'.");
}
builder.Services.AddHealthChecks()
.AddSqlServer(conStr);
Catatan
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Pemeriksaan Entity Framework Core DbContext
Pemeriksaan DbContext
mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext
. DbContext
Pemeriksaan didukung di aplikasi yang:
- Gunakan Core Entity Framework (EF).
- Sertakan referensi paket ke
Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
paket NuGet.
AddDbContextCheck mendaftarkan pemeriksaan kesehatan untuk DbContext. DbContext
disediakan ke metode sebagai TContext
. Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.
Secara default:
- Metode
DbContextHealthCheck
panggilanEF CoreCanConnectAsync
. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakanAddDbContextCheck
kelebihan beban metode. - Nama pemeriksaan kesehatan adalah nama jenisnya
TContext
.
Contoh berikut mendaftarkan DbContext
dan terkait DbContextHealthCheck
:
builder.Services.AddDbContext<SampleDbContext>(options =>
options.UseSqlServer(
builder.Configuration.GetConnectionString("DefaultConnection")));
builder.Services.AddHealthChecks()
.AddDbContextCheck<SampleDbContext>();
Pemeriksaan kesiapan dan keaktifan terpisah
Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:
- Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
- Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.
Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.
Tugas latar belakang berikut mensimulasikan proses startup yang memakan waktu sekitar 15 detik. Setelah selesai, tugas mengatur StartupHealthCheck.StartupCompleted
properti ke true:
public class StartupBackgroundService : BackgroundService
{
private readonly StartupHealthCheck _healthCheck;
public StartupBackgroundService(StartupHealthCheck healthCheck)
=> _healthCheck = healthCheck;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// Simulate the effect of a long-running task.
await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);
_healthCheck.StartupCompleted = true;
}
}
Laporan StartupHealthCheck
penyelesaian tugas startup yang berjalan lama dan mengekspos StartupCompleted
properti yang diatur oleh layanan latar belakang:
public class StartupHealthCheck : IHealthCheck
{
private volatile bool _isReady;
public bool StartupCompleted
{
get => _isReady;
set => _isReady = value;
}
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
if (StartupCompleted)
{
return Task.FromResult(HealthCheckResult.Healthy("The startup task has completed."));
}
return Task.FromResult(HealthCheckResult.Unhealthy("That startup task is still running."));
}
}
Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Program.cs
. Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan sebagai singleton:
builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();
builder.Services.AddHealthChecks()
.AddCheck<StartupHealthCheck>(
"Startup",
tags: new[] { "ready" });
Untuk membuat dua titik akhir pemeriksaan kesehatan yang berbeda, panggil MapHealthChecks
dua kali:
app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
{
Predicate = healthCheck => healthCheck.Tags.Contains("ready")
});
app.MapHealthChecks("/healthz/live", new HealthCheckOptions
{
Predicate = _ => false
});
Contoh sebelumnya membuat titik akhir pemeriksaan kesehatan berikut:
/healthz/ready
untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke yang ditandai denganready
./healthz/live
untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilter semua pemeriksaan kesehatan dengan kembalifalse
ke HealthCheckOptions.Predicate delegasi. Untuk informasi selengkapnya tentang pemfilteran pemeriksaan kesehatan, lihat Memfilter pemeriksaan kesehatan di artikel ini.
Sebelum tugas startup selesai, /healthz/ready
titik akhir melaporkan Unhealthy
status. Setelah tugas startup selesai, titik akhir ini melaporkan Healthy
status. Titik /healthz/live
akhir mengecualikan semua pemeriksaan dan melaporkan Healthy
status untuk semua panggilan.
Contoh Kubernetes
Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.
Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:
spec:
template:
spec:
readinessProbe:
# an http probe
httpGet:
path: /healthz/ready
port: 80
# length of time to wait for a pod to initialize
# after pod startup, before applying health checking
initialDelaySeconds: 30
timeoutSeconds: 1
ports:
- containerPort: 80
Mendistribusikan pustaka pemeriksaan kesehatan
Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:
Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.
Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya
Program.cs
. Pertimbangkan contoh pemeriksaan kesehatan berikut, yang menerimaarg1
danarg2
sebagai parameter konstruktor:public SampleHealthCheckWithArgs(int arg1, string arg2) => (_arg1, _arg2) = (arg1, arg2);
Tanda tangan sebelumnya menunjukkan bahwa pemeriksaan kesehatan memerlukan data kustom untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan:
arg1
: Titik data bilangan bulat untuk pemeriksaan kesehatan.arg2
: Argumen string untuk pemeriksaan kesehatan.name
: Nama pemeriksaan kesehatan opsional. Jikanull
, nilai default digunakan.failureStatus
: Opsional HealthStatus, yang dilaporkan untuk status kegagalan. Jikanull
, HealthStatus.Unhealthy digunakan.tags
: Kumpulan tag opsionalIEnumerable<string>
.
public static class SampleHealthCheckBuilderExtensions { private const string DefaultName = "Sample"; public static IHealthChecksBuilder AddSampleHealthCheck( this IHealthChecksBuilder healthChecksBuilder, int arg1, string arg2, string? name = null, HealthStatus? failureStatus = null, IEnumerable<string>? tags = default) { return healthChecksBuilder.Add( new HealthCheckRegistration( name ?? DefaultName, _ => new SampleHealthCheckWithArgs(arg1, arg2), failureStatus, tags)); } }
Penerbit Pemeriksaan Kesehatan
IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync kesehatan Anda dengan hasilnya. Proses ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.
HealthCheckPublisherOptions memungkinkan Anda untuk mengatur:
- Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan nanti. Nilai defaultnya adalah lima detik.
- Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
- Predicate: Jika Predicate (
null
default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode. - Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default
Contoh berikut menunjukkan tata letak penerbit kesehatan:
public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
{
if (report.Status == HealthStatus.Healthy)
{
// ...
}
else
{
// ...
}
return Task.CompletedTask;
}
}
Kelas HealthCheckPublisherOptions menyediakan properti untuk mengonfigurasi perilaku penerbit pemeriksaan kesehatan.
Contoh berikut mendaftarkan penerbit pemeriksaan kesehatan sebagai singleton dan mengonfigurasi HealthCheckPublisherOptions:
builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});
builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();
AspNetCore.Diagnostics.HealthChecks
:
- Termasuk penerbit untuk beberapa sistem, termasuk Application Insights.
- Tidak dikelola atau didukung oleh Microsoft.
Pemeriksaan Kesehatan Individu
Delay
dan Period
dapat diatur pada masing-masing HealthCheckRegistration secara individual. Ini berguna ketika Anda ingin menjalankan beberapa pemeriksaan kesehatan pada tingkat yang berbeda dari periode yang ditetapkan dalam HealthCheckPublisherOptions.
Kode berikut menetapkan Delay
dan Period
untuk SampleHealthCheck1
:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks()
.Add(new HealthCheckRegistration(
name: "SampleHealthCheck1",
instance: new SampleHealthCheck(),
failureStatus: null,
tags: null,
timeout: default)
{
Delay = TimeSpan.FromSeconds(40),
Period = TimeSpan.FromSeconds(30)
});
var app = builder.Build();
app.MapHealthChecks("/healthz");
app.Run();
Injeksi Dependensi dan Pemeriksaan Kesehatan
Dimungkinkan untuk menggunakan injeksi dependensi untuk menggunakan instans tertentu Type
di dalam kelas Pemeriksaan Kesehatan. Injeksi dependensi dapat berguna untuk menyuntikkan opsi atau konfigurasi global ke Pemeriksaan Kesehatan. Menggunakan injeksi dependensi bukanlah skenario umum untuk mengonfigurasi Pemeriksaan Kesehatan. Biasanya, setiap Pemeriksaan Kesehatan cukup spesifik untuk pengujian aktual dan dikonfigurasi menggunakan IHealthChecksBuilder
metode ekstensi.
Contoh berikut menunjukkan sampel Pemeriksaan Kesehatan yang mengambil objek konfigurasi melalui injeksi dependensi:
public class SampleHealthCheckWithDI : IHealthCheck
{
private readonly SampleHealthCheckWithDiConfig _config;
public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
=> _config = config;
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
var isHealthy = true;
// use _config ...
if (isHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("A healthy result."));
}
return Task.FromResult(
new HealthCheckResult(
context.Registration.FailureStatus, "An unhealthy result."));
}
}
SampleHealthCheckWithDiConfig
Pemeriksaan kesehatan dan perlu ditambahkan ke kontainer layanan :
builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
.AddCheck<SampleHealthCheckWithDI>(
"With Dependency Injection",
tags: new[] { "inject" });
UseHealthChecks vs. MapHealthChecks
Ada dua cara untuk membuat pemeriksaan kesehatan dapat diakses oleh penelepon:
- UseHealthChecks mendaftarkan middleware untuk menangani permintaan pemeriksaan kesehatan di alur middleware.
- MapHealthChecks mendaftarkan titik akhir pemeriksaan kesehatan. Titik akhir dicocokkan dan dijalankan bersama dengan titik akhir lain di aplikasi.
Keuntungan menggunakan MapHealthChecks
lebih UseHealthChecks
dari adalah kemampuan untuk menggunakan middleware sadar titik akhir, seperti otorisasi, dan untuk memiliki kontrol terperinci yang lebih besar atas kebijakan pencocokan. Keuntungan utama menggunakan UseHealthChecks
over MapHealthChecks
adalah mengontrol persis di mana pemeriksaan kesehatan berjalan di alur middleware.
- Mengakhiri alur saat permintaan cocok dengan titik akhir pemeriksaan kesehatan. Sirkuit pendek sering diinginkan karena menghindari pekerjaan yang tidak perlu, seperti pengelogan dan middleware lainnya.
- Terutama digunakan untuk mengonfigurasi middleware pemeriksaan kesehatan dalam alur.
- Dapat mencocokkan jalur apa pun pada port dengan
null
atau kosongPathString
. Memungkinkan melakukan pemeriksaan kesehatan pada permintaan apa pun yang dibuat ke port yang ditentukan. - Kode sumber
MapHealthChecks Memungkinkan:
- Mengakhiri alur ketika permintaan cocok dengan titik akhir pemeriksaan kesehatan, dengan memanggil ShortCircuit. Contohnya,
app.MapHealthChecks("/healthz").ShortCircuit();
. Untuk informasi selengkapnya, lihat Middleware sirkuit pendek setelah perutean. - Memetakan rute atau titik akhir tertentu untuk pemeriksaan kesehatan.
- Kustomisasi URL atau jalur tempat titik akhir pemeriksaan kesehatan dapat diakses.
- Memetakan beberapa titik akhir pemeriksaan kesehatan dengan rute atau konfigurasi yang berbeda. Dukungan beberapa titik akhir:
- Mengaktifkan titik akhir terpisah untuk berbagai jenis pemeriksaan kesehatan atau komponen.
- Digunakan untuk membedakan antara berbagai aspek kesehatan aplikasi atau menerapkan konfigurasi tertentu ke subset pemeriksaan kesehatan.
- Kode sumber
Sumber Daya Tambahan:
Catatan
Artikel ini sebagian dibuat dengan bantuan kecerdasan buatan. Sebelum menerbitkan, penulis akan meninjau dan merevisi konten jika diperlukan. Lihat Prinsip kami dalam menggunakan konten yang dihasilkan AI di Microsoft Learn.
ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.
Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:
- Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
- Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
- Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.
Melihat atau mengunduh kode sampel (cara mengunduh)
Aplikasi sampel menyertakan contoh skenario yang dijelaskan dalam artikel ini. Untuk menjalankan aplikasi sampel untuk skenario tertentu, gunakan perintah jalankan dotnet dari folder proyek dalam shell perintah. Lihat contoh file aplikasi README.md
dan deskripsi skenario dalam artikel ini untuk detail tentang cara menggunakan aplikasi sampel.
Prasyarat
Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.
Paket Microsoft.AspNetCore.Diagnostics.HealthChecks
ini dirujuk secara implisit untuk aplikasi ASP.NET Core. Untuk menjalankan pemeriksaan kesehatan menggunakan Entity Framework Core, tambahkan referensi ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
paket.
Aplikasi sampel menyediakan kode startup untuk menunjukkan pemeriksaan kesehatan untuk beberapa skenario. Skenario pemeriksaan database memeriksa kesehatan koneksi database menggunakan AspNetCore.Diagnostics.HealthChecks
. Skenario pemeriksaan DbContext memeriksa database menggunakan EF CoreDbContext
. Untuk menjelajahi skenario database, aplikasi sampel:
- Membuat database dan menyediakan string koneksi dalam
appsettings.json
file. - Memiliki referensi paket berikut dalam file proyeknya:
Catatan
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Skenario pemeriksaan kesehatan lain menunjukkan cara memfilter pemeriksaan kesehatan ke port manajemen. Aplikasi sampel mengharuskan Anda membuat Properties/launchSettings.json
file yang menyertakan URL manajemen dan port manajemen. Untuk informasi selengkapnya, lihat bagian Filter menurut port .
Pemeriksaan kesehatan dasar
Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.
Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis status (HealthStatus) sebagai respons teks biasa kembali ke klien, menunjukkan HealthStatus.Healthystatus , , HealthStatus.Degradedatau HealthStatus.Unhealthy .
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks
di Startup.Configure
.
Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di /health
(BasicStartup.cs
):
public class BasicStartup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddHealthChecks();
}
public void Configure(IApplicationBuilder app)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});
}
}
Untuk menjalankan skenario konfigurasi dasar menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario basic
Contoh Docker
Docker menawarkan arahan bawaan HEALTHCHECK
yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:
HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit
Membuat pemeriksaan kesehatan
Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy
, , Degraded
atau Unhealthy
. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi (konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan). HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.
Kelas berikut ExampleHealthCheck
menunjukkan tata letak pemeriksaan kesehatan. Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync
metode . Contoh berikut menetapkan variabel dummy, healthCheckResultHealthy
, ke true
. Jika nilai healthCheckResultHealthy
diatur ke false
, HealthCheckRegistration.FailureStatus status dikembalikan.
public class ExampleHealthCheck : IHealthCheck
{
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
var healthCheckResultHealthy = true;
if (healthCheckResultHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("A healthy result."));
}
return Task.FromResult(
new HealthCheckResult(context.Registration.FailureStatus,
"An unhealthy result."));
}
}
Jika CheckHealthAsync melempar pengecualian selama pemeriksaan, yang baru HealthReportEntry dikembalikan dengan diatur ke FailureStatus, yang ditentukan oleh AddCheck (lihat bagian Daftarkan layanan pemeriksaan kesehatan) dan menyertakan pengecualian dalam yang awalnya HealthReportEntry.Status menyebabkan kegagalan pemeriksaan. Description diatur ke pesan pengecualian.
Mendaftarkan layanan pemeriksaan kesehatan
ExampleHealthCheck
Jenis ditambahkan ke layanan pemeriksaan kesehatan dengan AddCheck di Startup.ConfigureServices
:
services.AddHealthChecks()
.AddCheck<ExampleHealthCheck>("example_health_check");
Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null
(default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.
Tag dapat digunakan untuk memfilter pemeriksaan kesehatan (dijelaskan lebih lanjut di bagian Filter pemeriksaan kesehatan).
services.AddHealthChecks()
.AddCheck<ExampleHealthCheck>(
"example_health_check",
failureStatus: HealthStatus.Degraded,
tags: new[] { "example" });
AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, nama pemeriksaan kesehatan ditentukan sebagai Example
dan pemeriksaan selalu mengembalikan status sehat:
services.AddHealthChecks()
.AddCheck("Example", () =>
HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });
Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, TestHealthCheckWithArgs
menerima bilangan bulat dan string untuk digunakan saat CheckHealthAsync dipanggil:
private class TestHealthCheckWithArgs : IHealthCheck
{
public TestHealthCheckWithArgs(int i, string s)
{
I = i;
S = s;
}
public int I { get; set; }
public string S { get; set; }
public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context,
CancellationToken cancellationToken = default)
{
...
}
}
TestHealthCheckWithArgs
terdaftar dengan memanggil dengan bilangan AddTypeActivatedCheck
bulat dan string yang diteruskan ke implementasi:
services.AddHealthChecks()
.AddTypeActivatedCheck<TestHealthCheckWithArgs>(
"test",
failureStatus: HealthStatus.Degraded,
tags: new[] { "example" },
args: new object[] { 5, "string" });
Gunakan Perutean Pemeriksaan Kesehatan
Di Startup.Configure
, panggil MapHealthChecks
pembangun titik akhir dengan URL titik akhir atau jalur relatif:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});
Memerlukan host
Panggil RequireHost
untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});
Untuk informasi selengkapnya, lihat bagian Filter menurut port .
Memerlukan otorisasi
Panggil RequireAuthorization
untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization
beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default digunakan.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health").RequireAuthorization();
});
Mengaktifkan Permintaan Lintas Asal (CORS)
Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario penggunaan umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors
titik akhir pemeriksaan kesehatan. Kelebihan RequireCors
beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder
) atau nama kebijakan. Jika kebijakan tidak disediakan, kebijakan CORS default akan digunakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.
Opsi pemeriksaan kesehatan
HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:
- Memfilter pemeriksaan kesehatan
- Mengkustomisasi kode status HTTP
- Menyembunyikan header cache
- Sesuaikan output
Memfilter pemeriksaan kesehatan
Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi . Dalam contoh berikut, Bar
pemeriksaan kesehatan difilter oleh tag -nya (bar_tag
) dalam pernyataan kondisi fungsi, di mana true
hanya dikembalikan jika properti pemeriksaan Tags kesehatan cocok foo_tag
atau baz_tag
:
Di Startup.ConfigureServices
:
services.AddHealthChecks()
.AddCheck("Foo", () =>
HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
.AddCheck("Bar", () =>
HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
.AddCheck("Baz", () =>
HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });
Di Startup.Configure
, Predicate
filter pemeriksaan kesehatan 'Bar'. Hanya Foo dan Baz yang dijalankan:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("foo_tag") ||
check.Tags.Contains("baz_tag")
});
});
Mengkustomisasi kode status HTTP
Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda.
Di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Degraded] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});
});
Menyembunyikan header cache
AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false
default), middleware mengatur atau mengambil Cache-Control
alih header , , Expires
dan Pragma
untuk mencegah penembolokan respons. Jika nilainya adalah true
, middleware tidak mengubah header cache respons.
Di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
AllowCachingResponses = true
});
});
Sesuaikan output
Di Startup.Configure
, atur HealthCheckOptions.ResponseWriter opsi ke delegasi untuk menulis respons:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
ResponseWriter = WriteResponse
});
});
Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Status
string . Delegasi kustom berikut menghasilkan respons JSON kustom.
Contoh pertama dari aplikasi sampel menunjukkan cara menggunakan System.Text.Json:
private static Task WriteResponse(HttpContext context, HealthReport result)
{
context.Response.ContentType = "application/json; charset=utf-8";
var options = new JsonWriterOptions
{
Indented = true
};
using (var stream = new MemoryStream())
{
using (var writer = new Utf8JsonWriter(stream, options))
{
writer.WriteStartObject();
writer.WriteString("status", result.Status.ToString());
writer.WriteStartObject("results");
foreach (var entry in result.Entries)
{
writer.WriteStartObject(entry.Key);
writer.WriteString("status", entry.Value.Status.ToString());
writer.WriteString("description", entry.Value.Description);
writer.WriteStartObject("data");
foreach (var item in entry.Value.Data)
{
writer.WritePropertyName(item.Key);
JsonSerializer.Serialize(
writer, item.Value, item.Value?.GetType() ??
typeof(object));
}
writer.WriteEndObject();
writer.WriteEndObject();
}
writer.WriteEndObject();
writer.WriteEndObject();
}
var json = Encoding.UTF8.GetString(stream.ToArray());
return context.Response.WriteAsync(json);
}
}
Contoh kedua menunjukkan cara menggunakan Newtonsoft.Json
:
private static Task WriteResponse(HttpContext context, HealthReport result)
{
context.Response.ContentType = "application/json";
var json = new JObject(
new JProperty("status", result.Status.ToString()),
new JProperty("results", new JObject(result.Entries.Select(pair =>
new JProperty(pair.Key, new JObject(
new JProperty("status", pair.Value.Status.ToString()),
new JProperty("description", pair.Value.Description),
new JProperty("data", new JObject(pair.Value.Data.Select(
p => new JProperty(p.Key, p.Value))))))))));
return context.Response.WriteAsync(
json.ToString(Formatting.Indented));
}
Di aplikasi sampel, komentari SYSTEM_TEXT_JSON
direktif praproscesor untuk CustomWriterStartup.cs
mengaktifkan Newtonsoft.Json
versi WriteResponse
.
API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json
, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.
Pemeriksaan database
Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.
Aplikasi sampel menggunakan AspNetCore.Diagnostics.HealthChecks
, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, untuk menjalankan pemeriksaan kesehatan pada database SQL Server. AspNetCore.Diagnostics.HealthChecks
SELECT 1
menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.
Peringatan
Saat memeriksa koneksi database dengan kueri, pilih kueri yang kembali dengan cepat. Pendekatan kueri menjalankan risiko kelebihan beban database dan menurunkan performanya. Dalam kebanyakan kasus, menjalankan kueri pengujian tidak diperlukan. Hanya membuat koneksi yang berhasil ke database sudah cukup. Jika Anda merasa perlu menjalankan kueri, pilih kueri SELECT sederhana, seperti SELECT 1
.
Sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer
.
Berikan string koneksi database yang valid dalam appsettings.json
file aplikasi sampel. Aplikasi ini menggunakan database SQL Server bernama HealthCheckSample
:
{
"ConnectionStrings": {
"DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
},
"Console": {
"IncludeScopes": "true"
}
},
"AllowedHosts": "*"
}
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Aplikasi sampel memanggil AddSqlServer
metode dengan string koneksi database (DbHealthStartup.cs
):
services.AddHealthChecks()
.AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
}
Untuk menjalankan skenario pemeriksaan database menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario db
Catatan
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Pemeriksaan Entity Framework Core DbContext
Pemeriksaan DbContext
mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext
. DbContext
Pemeriksaan didukung di aplikasi yang:
- Gunakan Core Entity Framework (EF).
- Sertakan referensi paket ke
Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
.
AddDbContextCheck<TContext>
mendaftarkan pemeriksaan kesehatan untuk DbContext
. DbContext
disediakan sebagai untuk TContext
metode . Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.
Secara default:
- Metode
DbContextHealthCheck
panggilanEF CoreCanConnectAsync
. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakanAddDbContextCheck
kelebihan beban metode. - Nama pemeriksaan kesehatan adalah nama jenisnya
TContext
.
Dalam aplikasi sampel, AppDbContext
disediakan untuk AddDbContextCheck
dan didaftarkan sebagai layanan di Startup.ConfigureServices
(DbContextHealthStartup.cs
):
services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>();
services.AddDbContext<AppDbContext>(options =>
{
options.UseSqlServer(
Configuration["ConnectionStrings:DefaultConnection"]);
});
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
}
Untuk menjalankan DbContext
skenario pemeriksaan menggunakan aplikasi sampel, konfirmasikan bahwa database yang ditentukan oleh string koneksi tidak ada di instans SQL Server. Jika database ada, hapus database tersebut.
Jalankan perintah berikut dari folder proyek dalam shell perintah:
dotnet run --scenario dbcontext
Setelah aplikasi berjalan, periksa status kesehatan dengan membuat permintaan ke /health
titik akhir di browser. Database dan AppDbContext
tidak ada, sehingga aplikasi memberikan respons berikut:
Unhealthy
Picu aplikasi sampel untuk membuat database. Buat permintaan ke /createdatabase
. Aplikasi merespons:
Creating the database...
Done!
Navigate to /health to see the health status.
Buat permintaan ke /health
titik akhir. Database dan konteks ada, sehingga aplikasi merespons:
Healthy
Picu aplikasi sampel untuk menghapus database. Buat permintaan ke /deletedatabase
. Aplikasi merespons:
Deleting the database...
Done!
Navigate to /health to see the health status.
Buat permintaan ke /health
titik akhir. Aplikasi ini memberikan respons yang tidak sehat:
Unhealthy
Pemeriksaan kesiapan dan keaktifan terpisah
Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:
- Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
- Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.
Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.
Aplikasi sampel berisi pemeriksaan kesehatan untuk melaporkan penyelesaian tugas startup yang berjalan lama di Layanan yang Dihosting. Mengekspos StartupHostedServiceHealthCheck
properti, StartupTaskCompleted
, bahwa layanan yang dihosting dapat diatur ke true
ketika tugasnya yang berjalan lama selesai (StartupHostedServiceHealthCheck.cs
):
public class StartupHostedServiceHealthCheck : IHealthCheck
{
private volatile bool _startupTaskCompleted = false;
public string Name => "slow_dependency_check";
public bool StartupTaskCompleted
{
get => _startupTaskCompleted;
set => _startupTaskCompleted = value;
}
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
if (StartupTaskCompleted)
{
return Task.FromResult(
HealthCheckResult.Healthy("The startup task is finished."));
}
return Task.FromResult(
HealthCheckResult.Unhealthy("The startup task is still running."));
}
}
Tugas latar belakang yang berjalan lama dimulai oleh Layanan yang Dihosting (Services/StartupHostedService
). Pada kesimpulan tugas, StartupHostedServiceHealthCheck.StartupTaskCompleted
diatur ke true
:
public class StartupHostedService : IHostedService, IDisposable
{
private readonly int _delaySeconds = 15;
private readonly ILogger _logger;
private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;
public StartupHostedService(ILogger<StartupHostedService> logger,
StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
{
_logger = logger;
_startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_logger.LogInformation("Startup Background Service is starting.");
// Simulate the effect of a long-running startup task.
Task.Run(async () =>
{
await Task.Delay(_delaySeconds * 1000);
_startupHostedServiceHealthCheck.StartupTaskCompleted = true;
_logger.LogInformation("Startup Background Service has started.");
});
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
_logger.LogInformation("Startup Background Service is stopping.");
return Task.CompletedTask;
}
public void Dispose()
{
}
}
Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Startup.ConfigureServices
. Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan (LivenessProbeStartup.cs
):
services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();
services.AddHealthChecks()
.AddCheck<StartupHostedServiceHealthCheck>(
"hosted_service_startup",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready" });
services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = (check) => check.Tags.Contains("ready");
});
services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
. Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di:
/health/ready
untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke pemeriksaan kesehatan denganready
tag./health/live
untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilterStartupHostedServiceHealthCheck
dengan mengembalikanfalse
(HealthCheckOptions.Predicate
untuk informasi selengkapnya, lihat Memfilter pemeriksaan kesehatan)
Dalam contoh kode berikut:
- Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
- Mengecualikan
Predicate
semua pemeriksaan dan mengembalikan 200-Ok.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("ready"),
});
endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
{
Predicate = (_) => false
});
}
Untuk menjalankan skenario konfigurasi kesiapan/keaktifan menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario liveness
Di browser, kunjungi /health/ready
beberapa kali hingga 15 detik berlalu. Laporan Unhealthy
pemeriksaan kesehatan selama 15 detik pertama. Setelah 15 detik, titik akhir melaporkan Healthy
, yang mencerminkan penyelesaian tugas yang berjalan lama oleh layanan yang dihosting.
Contoh ini juga membuat Penerbit Pemeriksaan Kesehatan (IHealthCheckPublisher implementasi) yang menjalankan pemeriksaan kesiapan pertama dengan penundaan dua detik. Untuk informasi selengkapnya, lihat bagian Penerbit Pemeriksaan Kesehatan.
Contoh Kubernetes
Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.
Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:
spec:
template:
spec:
readinessProbe:
# an http probe
httpGet:
path: /health/ready
port: 80
# length of time to wait for a pod to initialize
# after pod startup, before applying health checking
initialDelaySeconds: 30
timeoutSeconds: 1
ports:
- containerPort: 80
Pemeriksaan berbasis metrik dengan penulis respons kustom
Aplikasi sampel menunjukkan pemeriksaan kesehatan memori dengan penulis respons kustom.
MemoryHealthCheck
melaporkan status terdegradasi jika aplikasi menggunakan lebih dari ambang memori tertentu (1 GB di aplikasi sampel). Termasuk HealthCheckResult informasi Pengumpul Sampah (GC) untuk aplikasi (MemoryHealthCheck.cs
):
public class MemoryHealthCheck : IHealthCheck
{
private readonly IOptionsMonitor<MemoryCheckOptions> _options;
public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
{
_options = options;
}
public string Name => "memory_check";
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
var options = _options.Get(context.Registration.Name);
// Include GC information in the reported diagnostics.
var allocated = GC.GetTotalMemory(forceFullCollection: false);
var data = new Dictionary<string, object>()
{
{ "AllocatedBytes", allocated },
{ "Gen0Collections", GC.CollectionCount(0) },
{ "Gen1Collections", GC.CollectionCount(1) },
{ "Gen2Collections", GC.CollectionCount(2) },
};
var status = (allocated < options.Threshold) ?
HealthStatus.Healthy : context.Registration.FailureStatus;
return Task.FromResult(new HealthCheckResult(
status,
description: "Reports degraded status if allocated bytes " +
$">= {options.Threshold} bytes.",
exception: null,
data: data));
}
}
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Alih-alih mengaktifkan pemeriksaan kesehatan dengan meneruskannya ke AddCheck, MemoryHealthCheck
terdaftar sebagai layanan. Semua IHealthCheck layanan terdaftar tersedia untuk layanan pemeriksaan kesehatan dan middleware. Sebaiknya daftarkan layanan pemeriksaan kesehatan sebagai layanan Singleton.
Di CustomWriterStartup.cs
aplikasi sampel:
services.AddHealthChecks()
.AddMemoryHealthCheck("memory");
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
. WriteResponse
Delegasi diberikan ke ResponseWriter properti untuk menghasilkan respons JSON kustom saat pemeriksaan kesehatan dijalankan:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
ResponseWriter = WriteResponse
});
}
Delegasi WriteResponse
memformat CompositeHealthCheckResult
ke dalam objek JSON dan menghasilkan output JSON untuk respons pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat bagian Kustomisasi output .
Untuk menjalankan pemeriksaan berbasis metrik dengan output penulis respons kustom menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario writer
Catatan
AspNetCore.Diagnostics.HealthChecks
termasuk skenario pemeriksaan kesehatan berbasis metrik, termasuk penyimpanan disk dan pemeriksaan keakuratan nilai maksimum.
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Filter menurut port
MapHealthChecks
Panggil RequireHost
dengan pola URL yang menentukan port untuk membatasi permintaan pemeriksaan kesehatan ke port yang ditentukan. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan.
Aplikasi sampel mengonfigurasi port menggunakan Penyedia Konfigurasi Variabel Lingkungan. Port diatur dalam file dan diteruskan launchSettings.json
ke penyedia konfigurasi melalui variabel lingkungan. Anda juga harus mengonfigurasi server untuk mendengarkan permintaan pada port manajemen.
Untuk menggunakan aplikasi sampel untuk menunjukkan konfigurasi port manajemen, buat launchSettings.json
file di Properties
folder.
File berikut Properties/launchSettings.json
dalam aplikasi sampel tidak disertakan dalam file proyek aplikasi sampel dan harus dibuat secara manual:
{
"profiles": {
"SampleApp": {
"commandName": "Project",
"commandLineArgs": "",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
"ASPNETCORE_MANAGEMENTPORT": "5001"
},
"applicationUrl": "http://localhost:5000/"
}
}
}
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks
di Startup.Configure
.
Di aplikasi sampel, panggilan ke RequireHost
pada titik akhir dalam Startup.Configure
menentukan port manajemen dari konfigurasi:
endpoints.MapHealthChecks("/health")
.RequireHost($"*:{Configuration["ManagementPort"]}");
Titik akhir dibuat di aplikasi sampel di Startup.Configure
. Dalam contoh kode berikut:
- Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
- Mengecualikan
Predicate
semua pemeriksaan dan mengembalikan 200-Ok.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("ready"),
});
endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
{
Predicate = (_) => false
});
}
Catatan
Anda dapat menghindari pembuatan launchSettings.json
file di aplikasi sampel dengan mengatur port manajemen secara eksplisit dalam kode. Di Program.cs
tempat HostBuilder dibuat, tambahkan panggilan ke ListenAnyIP dan berikan titik akhir port manajemen aplikasi. Di Configure
dari ManagementPortStartup.cs
, tentukan port manajemen dengan RequireHost
:
Program.cs
:
return new HostBuilder()
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseKestrel()
.ConfigureKestrel(serverOptions =>
{
serverOptions.ListenAnyIP(5001);
})
.UseStartup(startupType);
})
.Build();
ManagementPortStartup.cs
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health").RequireHost("*:5001");
});
Untuk menjalankan skenario konfigurasi port manajemen menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario port
Mendistribusikan pustaka pemeriksaan kesehatan
Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:
Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.
Dalam logika pemeriksaan kesehatan :
CheckHealthAsync
data1
dandata2
digunakan dalam metode untuk menjalankan logika pemeriksaan kesehatan probe.AccessViolationException
ditangani.
AccessViolationException Ketika terjadi, FailureStatus dikembalikan dengan HealthCheckResult untuk memungkinkan pengguna mengonfigurasi status kegagalan pemeriksaan kesehatan.
using System; using System.Threading; using System.Threading.Tasks; using Microsoft.Extensions.Diagnostics.HealthChecks; namespace SampleApp { public class ExampleHealthCheck : IHealthCheck { private readonly string _data1; private readonly int? _data2; public ExampleHealthCheck(string data1, int? data2) { _data1 = data1 ?? throw new ArgumentNullException(nameof(data1)); _data2 = data2 ?? throw new ArgumentNullException(nameof(data2)); } public async Task<HealthCheckResult> CheckHealthAsync( HealthCheckContext context, CancellationToken cancellationToken) { try { return HealthCheckResult.Healthy(); } catch (AccessViolationException ex) { return new HealthCheckResult( context.Registration.FailureStatus, description: "An access violation occurred during the check.", exception: ex, data: null); } } } }
Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya
Startup.Configure
. Dalam contoh berikut, asumsikan tanda tangan metode pemeriksaan kesehatan berikut:ExampleHealthCheck(string, string, int )
Tanda tangan sebelumnya menunjukkan bahwa
ExampleHealthCheck
memerlukan data tambahan untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan opsional:- nama pemeriksaan kesehatan (
name
). Jikanull
,example_health_check
digunakan. - titik data string untuk pemeriksaan kesehatan (
data1
). - titik data bilangan bulat untuk pemeriksaan kesehatan (
data2
). Jikanull
,1
digunakan. - status kegagalan (HealthStatus). Default adalah
null
. Jikanull
, HealthStatus.Unhealthy dilaporkan untuk status kegagalan. - tag (
IEnumerable<string>
).
using System.Collections.Generic; using Microsoft.Extensions.Diagnostics.HealthChecks; public static class ExampleHealthCheckBuilderExtensions { const string DefaultName = "example_health_check"; public static IHealthChecksBuilder AddExampleHealthCheck( this IHealthChecksBuilder builder, string name = default, string data1, int data2 = 1, HealthStatus? failureStatus = default, IEnumerable<string> tags = default) { return builder.Add(new HealthCheckRegistration( name ?? DefaultName, sp => new ExampleHealthCheck(data1, data2), failureStatus, tags)); } }
- nama pemeriksaan kesehatan (
Penerbit Pemeriksaan Kesehatan
IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync
kesehatan Anda dengan hasilnya. Ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.
Antarmuka IHealthCheckPublisher memiliki satu metode:
Task PublishAsync(HealthReport report, CancellationToken cancellationToken);
HealthCheckPublisherOptions memungkinkan Anda mengatur:
- Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan berikutnya. Nilai defaultnya adalah lima detik.
- Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
- Predicate: Jika Predicate (
null
default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode. - Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default
Dalam aplikasi sampel, ReadinessPublisher
adalah IHealthCheckPublisher implementasi. Status pemeriksaan kesehatan dicatat untuk setiap pemeriksaan pada tingkat log:
- Informasi (LogInformation) jika status pemeriksaan kesehatan adalah Healthy.
- Kesalahan (LogError) jika statusnya adalah Degraded atau Unhealthy.
public class ReadinessPublisher : IHealthCheckPublisher
{
private readonly ILogger _logger;
public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
{
_logger = logger;
}
// The following example is for demonstration purposes only. Health Checks
// Middleware already logs health checks results. A real-world readiness
// check in a production app might perform a set of more expensive or
// time-consuming checks to determine if other resources are responding
// properly.
public Task PublishAsync(HealthReport report,
CancellationToken cancellationToken)
{
if (report.Status == HealthStatus.Healthy)
{
_logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}",
DateTime.UtcNow, report.Status);
}
else
{
_logger.LogError("{Timestamp} Readiness Probe Status: {Result}",
DateTime.UtcNow, report.Status);
}
cancellationToken.ThrowIfCancellationRequested();
return Task.CompletedTask;
}
}
Dalam contoh aplikasi LivenessProbeStartup
sampel, StartupHostedService
pemeriksaan kesiapan memiliki penundaan startup dua detik dan menjalankan pemeriksaan setiap 30 detik. Untuk mengaktifkan IHealthCheckPublisher implementasi, sampel mendaftar ReadinessPublisher
sebagai layanan singleton dalam kontainer injeksi dependensi (DI):
services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();
services.AddHealthChecks()
.AddCheck<StartupHostedServiceHealthCheck>(
"hosted_service_startup",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready" });
services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = (check) => check.Tags.Contains("ready");
});
services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
Catatan
AspNetCore.Diagnostics.HealthChecks
termasuk penerbit untuk beberapa sistem, termasuk Application Insights.
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Membatasi pemeriksaan kesehatan dengan MapWhen
Gunakan MapWhen untuk mencabangkan alur permintaan untuk titik akhir pemeriksaan kesehatan secara kondisional.
Dalam contoh berikut, MapWhen
mencabangkan alur permintaan untuk mengaktifkan Middleware Pemeriksaan Kesehatan jika permintaan GET diterima untuk api/HealthCheck
titik akhir:
app.MapWhen(
context => context.Request.Method == HttpMethod.Get.Method &&
context.Request.Path.StartsWith("/api/HealthCheck"),
builder => builder.UseHealthChecks());
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.
ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.
Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:
- Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
- Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
- Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.
Melihat atau mengunduh kode sampel (cara mengunduh)
Aplikasi sampel menyertakan contoh skenario yang dijelaskan dalam artikel ini. Untuk menjalankan aplikasi sampel untuk skenario tertentu, gunakan perintah jalankan dotnet dari folder proyek dalam shell perintah. Lihat contoh file aplikasi README.md
dan deskripsi skenario dalam artikel ini untuk detail tentang cara menggunakan aplikasi sampel.
Prasyarat
Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.
Paket Microsoft.AspNetCore.Diagnostics.HealthChecks
ini dirujuk secara implisit untuk aplikasi ASP.NET Core. Untuk menjalankan pemeriksaan kesehatan menggunakan Entity Framework Core, tambahkan referensi paket ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
paket.
Aplikasi sampel menyediakan kode startup untuk menunjukkan pemeriksaan kesehatan untuk beberapa skenario. Skenario pemeriksaan database memeriksa kesehatan koneksi database menggunakan AspNetCore.Diagnostics.HealthChecks
. Skenario pemeriksaan DbContext memeriksa database menggunakan EF CoreDbContext
. Untuk menjelajahi skenario database, aplikasi sampel:
- Membuat database dan menyediakan string koneksi dalam
appsettings.json
file. - Memiliki referensi paket berikut dalam file proyeknya:
Catatan
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Skenario pemeriksaan kesehatan lain menunjukkan cara memfilter pemeriksaan kesehatan ke port manajemen. Aplikasi sampel mengharuskan Anda membuat Properties/launchSettings.json
file yang menyertakan URL manajemen dan port manajemen. Untuk informasi selengkapnya, lihat bagian Filter menurut port .
Pemeriksaan kesehatan dasar
Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.
Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis status (HealthStatus) sebagai respons teks biasa kembali ke klien, menunjukkan HealthStatus.Healthystatus , , HealthStatus.Degradedatau HealthStatus.Unhealthy .
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks
di Startup.Configure
.
Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di /health
(BasicStartup.cs
):
public class BasicStartup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddHealthChecks();
}
public void Configure(IApplicationBuilder app)
{
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});
}
}
Untuk menjalankan skenario konfigurasi dasar menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario basic
Contoh Docker
Docker menawarkan arahan bawaan HEALTHCHECK
yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:
HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit
Membuat pemeriksaan kesehatan
Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy
, , Degraded
atau Unhealthy
. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi (konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan). HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.
Kelas berikut ExampleHealthCheck
menunjukkan tata letak pemeriksaan kesehatan. Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync
metode . Contoh berikut menetapkan variabel dummy, healthCheckResultHealthy
, ke true
. Jika nilai healthCheckResultHealthy
diatur ke false
, HealthCheckResult.Unhealthy
status dikembalikan.
public class ExampleHealthCheck : IHealthCheck
{
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
var healthCheckResultHealthy = true;
if (healthCheckResultHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("A healthy result."));
}
return Task.FromResult(
HealthCheckResult.Unhealthy("An unhealthy result."));
}
}
Mendaftarkan layanan pemeriksaan kesehatan
ExampleHealthCheck
Jenis ditambahkan ke layanan pemeriksaan kesehatan dengan AddCheck di Startup.ConfigureServices
:
services.AddHealthChecks()
.AddCheck<ExampleHealthCheck>("example_health_check");
Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null
(default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.
Tag dapat digunakan untuk memfilter pemeriksaan kesehatan (dijelaskan lebih lanjut di bagian Filter pemeriksaan kesehatan).
services.AddHealthChecks()
.AddCheck<ExampleHealthCheck>(
"example_health_check",
failureStatus: HealthStatus.Degraded,
tags: new[] { "example" });
AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, nama pemeriksaan kesehatan ditentukan sebagai Example
dan pemeriksaan selalu mengembalikan status sehat:
services.AddHealthChecks()
.AddCheck("Example", () =>
HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });
Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, TestHealthCheckWithArgs
menerima bilangan bulat dan string untuk digunakan saat CheckHealthAsync dipanggil:
private class TestHealthCheckWithArgs : IHealthCheck
{
public TestHealthCheckWithArgs(int i, string s)
{
I = i;
S = s;
}
public int I { get; set; }
public string S { get; set; }
public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context,
CancellationToken cancellationToken = default)
{
...
}
}
TestHealthCheckWithArgs
terdaftar dengan memanggil dengan bilangan AddTypeActivatedCheck
bulat dan string yang diteruskan ke implementasi:
services.AddHealthChecks()
.AddTypeActivatedCheck<TestHealthCheckWithArgs>(
"test",
failureStatus: HealthStatus.Degraded,
tags: new[] { "example" },
args: new object[] { 5, "string" });
Gunakan Perutean Pemeriksaan Kesehatan
Di Startup.Configure
, panggil MapHealthChecks
pembangun titik akhir dengan URL titik akhir atau jalur relatif:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});
Memerlukan host
Panggil RequireHost
untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});
Untuk informasi selengkapnya, lihat bagian Filter menurut port .
Memerlukan otorisasi
Panggil RequireAuthorization
untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization
beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default digunakan.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health").RequireAuthorization();
});
Mengaktifkan Permintaan Lintas Asal (CORS)
Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario penggunaan umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors
titik akhir pemeriksaan kesehatan. Kelebihan RequireCors
beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder
) atau nama kebijakan. Jika kebijakan tidak disediakan, kebijakan CORS default akan digunakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.
Opsi pemeriksaan kesehatan
HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:
- Memfilter pemeriksaan kesehatan
- Mengkustomisasi kode status HTTP
- Menyembunyikan header cache
- Sesuaikan output
Memfilter pemeriksaan kesehatan
Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi . Dalam contoh berikut, Bar
pemeriksaan kesehatan difilter oleh tag -nya (bar_tag
) dalam pernyataan kondisi fungsi, di mana true
hanya dikembalikan jika properti pemeriksaan Tags kesehatan cocok foo_tag
atau baz_tag
:
Di Startup.ConfigureServices
:
services.AddHealthChecks()
.AddCheck("Foo", () =>
HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
.AddCheck("Bar", () =>
HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
.AddCheck("Baz", () =>
HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });
Di Startup.Configure
, Predicate
filter pemeriksaan kesehatan 'Bar'. Hanya Foo dan Baz yang dijalankan:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("foo_tag") ||
check.Tags.Contains("baz_tag")
});
});
Mengkustomisasi kode status HTTP
Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda.
Di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Degraded] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});
});
Menyembunyikan header cache
AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false
default), middleware mengatur atau mengambil Cache-Control
alih header , , Expires
dan Pragma
untuk mencegah penembolokan respons. Jika nilainya adalah true
, middleware tidak mengubah header cache respons.
Di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
AllowCachingResponses = true
});
});
Sesuaikan output
Di Startup.Configure
, atur HealthCheckOptions.ResponseWriter opsi ke delegasi untuk menulis respons:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
ResponseWriter = WriteResponse
});
});
Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Status
string . Delegasi kustom berikut menghasilkan respons JSON kustom.
Contoh pertama dari aplikasi sampel menunjukkan cara menggunakan System.Text.Json:
private static Task WriteResponse(HttpContext context, HealthReport result)
{
context.Response.ContentType = "application/json; charset=utf-8";
var options = new JsonWriterOptions
{
Indented = true
};
using (var stream = new MemoryStream())
{
using (var writer = new Utf8JsonWriter(stream, options))
{
writer.WriteStartObject();
writer.WriteString("status", result.Status.ToString());
writer.WriteStartObject("results");
foreach (var entry in result.Entries)
{
writer.WriteStartObject(entry.Key);
writer.WriteString("status", entry.Value.Status.ToString());
writer.WriteString("description", entry.Value.Description);
writer.WriteStartObject("data");
foreach (var item in entry.Value.Data)
{
writer.WritePropertyName(item.Key);
JsonSerializer.Serialize(
writer, item.Value, item.Value?.GetType() ??
typeof(object));
}
writer.WriteEndObject();
writer.WriteEndObject();
}
writer.WriteEndObject();
writer.WriteEndObject();
}
var json = Encoding.UTF8.GetString(stream.ToArray());
return context.Response.WriteAsync(json);
}
}
Contoh kedua menunjukkan cara menggunakan Newtonsoft.Json:
private static Task WriteResponse(HttpContext context, HealthReport result)
{
context.Response.ContentType = "application/json";
var json = new JObject(
new JProperty("status", result.Status.ToString()),
new JProperty("results", new JObject(result.Entries.Select(pair =>
new JProperty(pair.Key, new JObject(
new JProperty("status", pair.Value.Status.ToString()),
new JProperty("description", pair.Value.Description),
new JProperty("data", new JObject(pair.Value.Data.Select(
p => new JProperty(p.Key, p.Value))))))))));
return context.Response.WriteAsync(
json.ToString(Formatting.Indented));
}
Di aplikasi sampel, komentari SYSTEM_TEXT_JSON
direktif praproscesor untuk CustomWriterStartup.cs
mengaktifkan Newtonsoft.Json
versi WriteResponse
.
API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json
, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.
Pemeriksaan database
Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.
Aplikasi sampel menggunakan AspNetCore.Diagnostics.HealthChecks
, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, untuk menjalankan pemeriksaan kesehatan pada database SQL Server. AspNetCore.Diagnostics.HealthChecks
SELECT 1
menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.
Peringatan
Saat memeriksa koneksi database dengan kueri, pilih kueri yang kembali dengan cepat. Pendekatan kueri menjalankan risiko kelebihan beban database dan menurunkan performanya. Dalam kebanyakan kasus, menjalankan kueri pengujian tidak diperlukan. Hanya membuat koneksi yang berhasil ke database sudah cukup. Jika Anda merasa perlu menjalankan kueri, pilih kueri SELECT sederhana, seperti SELECT 1
.
Sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer
.
Berikan string koneksi database yang valid dalam appsettings.json
file aplikasi sampel. Aplikasi ini menggunakan database SQL Server bernama HealthCheckSample
:
{
"ConnectionStrings": {
"DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
},
"Console": {
"IncludeScopes": "true"
}
},
"AllowedHosts": "*"
}
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Aplikasi sampel memanggil AddSqlServer
metode dengan string koneksi database (DbHealthStartup.cs
):
services.AddHealthChecks()
.AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
}
Untuk menjalankan skenario pemeriksaan database menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario db
Catatan
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Pemeriksaan Entity Framework Core DbContext
Pemeriksaan DbContext
mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext
. DbContext
Pemeriksaan didukung di aplikasi yang:
- Gunakan Core Entity Framework (EF).
- Sertakan referensi paket ke
Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
.
AddDbContextCheck<TContext>
mendaftarkan pemeriksaan kesehatan untuk DbContext
. DbContext
disediakan sebagai untuk TContext
metode . Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.
Secara default:
- Metode
DbContextHealthCheck
panggilanEF CoreCanConnectAsync
. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakanAddDbContextCheck
kelebihan beban metode. - Nama pemeriksaan kesehatan adalah nama jenisnya
TContext
.
Dalam aplikasi sampel, AppDbContext
disediakan untuk AddDbContextCheck
dan didaftarkan sebagai layanan di Startup.ConfigureServices
(DbContextHealthStartup.cs
):
services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>();
services.AddDbContext<AppDbContext>(options =>
{
options.UseSqlServer(
Configuration["ConnectionStrings:DefaultConnection"]);
});
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
}
Untuk menjalankan DbContext
skenario pemeriksaan menggunakan aplikasi sampel, konfirmasikan bahwa database yang ditentukan oleh string koneksi tidak ada di instans SQL Server. Jika database ada, hapus database tersebut.
Jalankan perintah berikut dari folder proyek dalam shell perintah:
dotnet run --scenario dbcontext
Setelah aplikasi berjalan, periksa status kesehatan dengan membuat permintaan ke /health
titik akhir di browser. Database dan AppDbContext
tidak ada, sehingga aplikasi memberikan respons berikut:
Unhealthy
Picu aplikasi sampel untuk membuat database. Buat permintaan ke /createdatabase
. Aplikasi merespons:
Creating the database...
Done!
Navigate to /health to see the health status.
Buat permintaan ke /health
titik akhir. Database dan konteks ada, sehingga aplikasi merespons:
Healthy
Picu aplikasi sampel untuk menghapus database. Buat permintaan ke /deletedatabase
. Aplikasi merespons:
Deleting the database...
Done!
Navigate to /health to see the health status.
Buat permintaan ke /health
titik akhir. Aplikasi ini memberikan respons yang tidak sehat:
Unhealthy
Pemeriksaan kesiapan dan keaktifan terpisah
Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:
- Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
- Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.
Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.
Aplikasi sampel berisi pemeriksaan kesehatan untuk melaporkan penyelesaian tugas startup yang berjalan lama di Layanan yang Dihosting. Mengekspos StartupHostedServiceHealthCheck
properti, StartupTaskCompleted
, bahwa layanan yang dihosting dapat diatur ke true
ketika tugasnya yang berjalan lama selesai (StartupHostedServiceHealthCheck.cs
):
public class StartupHostedServiceHealthCheck : IHealthCheck
{
private volatile bool _startupTaskCompleted = false;
public string Name => "slow_dependency_check";
public bool StartupTaskCompleted
{
get => _startupTaskCompleted;
set => _startupTaskCompleted = value;
}
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
if (StartupTaskCompleted)
{
return Task.FromResult(
HealthCheckResult.Healthy("The startup task is finished."));
}
return Task.FromResult(
HealthCheckResult.Unhealthy("The startup task is still running."));
}
}
Tugas latar belakang yang berjalan lama dimulai oleh Layanan yang Dihosting (Services/StartupHostedService
). Pada kesimpulan tugas, StartupHostedServiceHealthCheck.StartupTaskCompleted
diatur ke true
:
public class StartupHostedService : IHostedService, IDisposable
{
private readonly int _delaySeconds = 15;
private readonly ILogger _logger;
private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;
public StartupHostedService(ILogger<StartupHostedService> logger,
StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
{
_logger = logger;
_startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_logger.LogInformation("Startup Background Service is starting.");
// Simulate the effect of a long-running startup task.
Task.Run(async () =>
{
await Task.Delay(_delaySeconds * 1000);
_startupHostedServiceHealthCheck.StartupTaskCompleted = true;
_logger.LogInformation("Startup Background Service has started.");
});
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
_logger.LogInformation("Startup Background Service is stopping.");
return Task.CompletedTask;
}
public void Dispose()
{
}
}
Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Startup.ConfigureServices
. Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan (LivenessProbeStartup.cs
):
services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();
services.AddHealthChecks()
.AddCheck<StartupHostedServiceHealthCheck>(
"hosted_service_startup",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready" });
services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = (check) => check.Tags.Contains("ready");
});
services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
. Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di:
/health/ready
untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke pemeriksaan kesehatan denganready
tag./health/live
untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilterStartupHostedServiceHealthCheck
dengan mengembalikanfalse
(HealthCheckOptions.Predicate
untuk informasi selengkapnya, lihat Memfilter pemeriksaan kesehatan)
Dalam contoh kode berikut:
- Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
- Mengecualikan
Predicate
semua pemeriksaan dan mengembalikan 200-Ok.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("ready"),
});
endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
{
Predicate = (_) => false
});
}
Untuk menjalankan skenario konfigurasi kesiapan/keaktifan menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario liveness
Di browser, kunjungi /health/ready
beberapa kali hingga 15 detik berlalu. Laporan Unhealthy
pemeriksaan kesehatan selama 15 detik pertama. Setelah 15 detik, titik akhir melaporkan Healthy
, yang mencerminkan penyelesaian tugas yang berjalan lama oleh layanan yang dihosting.
Contoh ini juga membuat Penerbit Pemeriksaan Kesehatan (IHealthCheckPublisher implementasi) yang menjalankan pemeriksaan kesiapan pertama dengan penundaan dua detik. Untuk informasi selengkapnya, lihat bagian Penerbit Pemeriksaan Kesehatan.
Contoh Kubernetes
Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.
Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:
spec:
template:
spec:
readinessProbe:
# an http probe
httpGet:
path: /health/ready
port: 80
# length of time to wait for a pod to initialize
# after pod startup, before applying health checking
initialDelaySeconds: 30
timeoutSeconds: 1
ports:
- containerPort: 80
Pemeriksaan berbasis metrik dengan penulis respons kustom
Aplikasi sampel menunjukkan pemeriksaan kesehatan memori dengan penulis respons kustom.
MemoryHealthCheck
melaporkan status terdegradasi jika aplikasi menggunakan lebih dari ambang memori tertentu (1 GB di aplikasi sampel). Termasuk HealthCheckResult informasi Pengumpul Sampah (GC) untuk aplikasi (MemoryHealthCheck.cs
):
public class MemoryHealthCheck : IHealthCheck
{
private readonly IOptionsMonitor<MemoryCheckOptions> _options;
public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
{
_options = options;
}
public string Name => "memory_check";
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context,
CancellationToken cancellationToken = default(CancellationToken))
{
var options = _options.Get(context.Registration.Name);
// Include GC information in the reported diagnostics.
var allocated = GC.GetTotalMemory(forceFullCollection: false);
var data = new Dictionary<string, object>()
{
{ "AllocatedBytes", allocated },
{ "Gen0Collections", GC.CollectionCount(0) },
{ "Gen1Collections", GC.CollectionCount(1) },
{ "Gen2Collections", GC.CollectionCount(2) },
};
var status = (allocated < options.Threshold) ?
HealthStatus.Healthy : context.Registration.FailureStatus;
return Task.FromResult(new HealthCheckResult(
status,
description: "Reports degraded status if allocated bytes " +
$">= {options.Threshold} bytes.",
exception: null,
data: data));
}
}
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Alih-alih mengaktifkan pemeriksaan kesehatan dengan meneruskannya ke AddCheck, MemoryHealthCheck
terdaftar sebagai layanan. Semua IHealthCheck layanan terdaftar tersedia untuk layanan pemeriksaan kesehatan dan middleware. Sebaiknya daftarkan layanan pemeriksaan kesehatan sebagai layanan Singleton.
Di CustomWriterStartup.cs
aplikasi sampel:
services.AddHealthChecks()
.AddMemoryHealthCheck("memory");
Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks
di Startup.Configure
. WriteResponse
Delegasi diberikan ke ResponseWriter properti untuk menghasilkan respons JSON kustom saat pemeriksaan kesehatan dijalankan:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health", new HealthCheckOptions()
{
ResponseWriter = WriteResponse
});
}
Delegasi WriteResponse
memformat CompositeHealthCheckResult
ke dalam objek JSON dan menghasilkan output JSON untuk respons pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat bagian Kustomisasi output .
Untuk menjalankan pemeriksaan berbasis metrik dengan output penulis respons kustom menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario writer
Catatan
AspNetCore.Diagnostics.HealthChecks
termasuk skenario pemeriksaan kesehatan berbasis metrik, termasuk penyimpanan disk dan pemeriksaan keakuratan nilai maksimum.
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Filter menurut port
MapHealthChecks
Panggil RequireHost
dengan pola URL yang menentukan port untuk membatasi permintaan pemeriksaan kesehatan ke port yang ditentukan. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan.
Aplikasi sampel mengonfigurasi port menggunakan Penyedia Konfigurasi Variabel Lingkungan. Port diatur dalam file dan diteruskan launchSettings.json
ke penyedia konfigurasi melalui variabel lingkungan. Anda juga harus mengonfigurasi server untuk mendengarkan permintaan pada port manajemen.
Untuk menggunakan aplikasi sampel untuk menunjukkan konfigurasi port manajemen, buat launchSettings.json
file di Properties
folder.
File berikut Properties/launchSettings.json
dalam aplikasi sampel tidak disertakan dalam file proyek aplikasi sampel dan harus dibuat secara manual:
{
"profiles": {
"SampleApp": {
"commandName": "Project",
"commandLineArgs": "",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
"ASPNETCORE_MANAGEMENTPORT": "5001"
},
"applicationUrl": "http://localhost:5000/"
}
}
}
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices
. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks
di Startup.Configure
.
Di aplikasi sampel, panggilan ke RequireHost
pada titik akhir dalam Startup.Configure
menentukan port manajemen dari konfigurasi:
endpoints.MapHealthChecks("/health")
.RequireHost($"*:{Configuration["ManagementPort"]}");
Titik akhir dibuat di aplikasi sampel di Startup.Configure
. Dalam contoh kode berikut:
- Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
- Mengecualikan
Predicate
semua pemeriksaan dan mengembalikan 200-Ok.
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
{
Predicate = (check) => check.Tags.Contains("ready"),
});
endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
{
Predicate = (_) => false
});
}
Catatan
Anda dapat menghindari pembuatan launchSettings.json
file di aplikasi sampel dengan mengatur port manajemen secara eksplisit dalam kode. Di Program.cs
tempat HostBuilder dibuat, tambahkan panggilan ke ListenAnyIP dan berikan titik akhir port manajemen aplikasi. Di Configure
dari ManagementPortStartup.cs
, tentukan port manajemen dengan RequireHost
:
Program.cs
:
return new HostBuilder()
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseKestrel()
.ConfigureKestrel(serverOptions =>
{
serverOptions.ListenAnyIP(5001);
})
.UseStartup(startupType);
})
.Build();
ManagementPortStartup.cs
:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health").RequireHost("*:5001");
});
Untuk menjalankan skenario konfigurasi port manajemen menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:
dotnet run --scenario port
Mendistribusikan pustaka pemeriksaan kesehatan
Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:
Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.
Dalam logika pemeriksaan kesehatan :
CheckHealthAsync
data1
dandata2
digunakan dalam metode untuk menjalankan logika pemeriksaan kesehatan probe.AccessViolationException
ditangani.
AccessViolationException Ketika terjadi, FailureStatus dikembalikan dengan HealthCheckResult untuk memungkinkan pengguna mengonfigurasi status kegagalan pemeriksaan kesehatan.
using System; using System.Threading; using System.Threading.Tasks; using Microsoft.Extensions.Diagnostics.HealthChecks; namespace SampleApp { public class ExampleHealthCheck : IHealthCheck { private readonly string _data1; private readonly int? _data2; public ExampleHealthCheck(string data1, int? data2) { _data1 = data1 ?? throw new ArgumentNullException(nameof(data1)); _data2 = data2 ?? throw new ArgumentNullException(nameof(data2)); } public async Task<HealthCheckResult> CheckHealthAsync( HealthCheckContext context, CancellationToken cancellationToken) { try { return HealthCheckResult.Healthy(); } catch (AccessViolationException ex) { return new HealthCheckResult( context.Registration.FailureStatus, description: "An access violation occurred during the check.", exception: ex, data: null); } } } }
Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya
Startup.Configure
. Dalam contoh berikut, asumsikan tanda tangan metode pemeriksaan kesehatan berikut:ExampleHealthCheck(string, string, int )
Tanda tangan sebelumnya menunjukkan bahwa
ExampleHealthCheck
memerlukan data tambahan untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan opsional:- nama pemeriksaan kesehatan (
name
). Jikanull
,example_health_check
digunakan. - titik data string untuk pemeriksaan kesehatan (
data1
). - titik data bilangan bulat untuk pemeriksaan kesehatan (
data2
). Jikanull
,1
digunakan. - status kegagalan (HealthStatus). Default adalah
null
. Jikanull
, HealthStatus.Unhealthy dilaporkan untuk status kegagalan. - tag (
IEnumerable<string>
).
using System.Collections.Generic; using Microsoft.Extensions.Diagnostics.HealthChecks; public static class ExampleHealthCheckBuilderExtensions { const string DefaultName = "example_health_check"; public static IHealthChecksBuilder AddExampleHealthCheck( this IHealthChecksBuilder builder, string name = default, string data1, int data2 = 1, HealthStatus? failureStatus = default, IEnumerable<string> tags = default) { return builder.Add(new HealthCheckRegistration( name ?? DefaultName, sp => new ExampleHealthCheck(data1, data2), failureStatus, tags)); } }
- nama pemeriksaan kesehatan (
Penerbit Pemeriksaan Kesehatan
IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync
kesehatan Anda dengan hasilnya. Ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.
Antarmuka IHealthCheckPublisher memiliki satu metode:
Task PublishAsync(HealthReport report, CancellationToken cancellationToken);
HealthCheckPublisherOptions memungkinkan Anda mengatur:
- Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan berikutnya. Nilai defaultnya adalah lima detik.
- Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
- Predicate: Jika Predicate (
null
default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode. - Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default
Dalam aplikasi sampel, ReadinessPublisher
adalah IHealthCheckPublisher implementasi. Status pemeriksaan kesehatan dicatat untuk setiap pemeriksaan pada tingkat log:
- Informasi (LogInformation) jika status pemeriksaan kesehatan adalah Healthy.
- Kesalahan (LogError) jika statusnya adalah Degraded atau Unhealthy.
public class ReadinessPublisher : IHealthCheckPublisher
{
private readonly ILogger _logger;
public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
{
_logger = logger;
}
// The following example is for demonstration purposes only. Health Checks
// Middleware already logs health checks results. A real-world readiness
// check in a production app might perform a set of more expensive or
// time-consuming checks to determine if other resources are responding
// properly.
public Task PublishAsync(HealthReport report,
CancellationToken cancellationToken)
{
if (report.Status == HealthStatus.Healthy)
{
_logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}",
DateTime.UtcNow, report.Status);
}
else
{
_logger.LogError("{Timestamp} Readiness Probe Status: {Result}",
DateTime.UtcNow, report.Status);
}
cancellationToken.ThrowIfCancellationRequested();
return Task.CompletedTask;
}
}
Dalam contoh aplikasi LivenessProbeStartup
sampel, StartupHostedService
pemeriksaan kesiapan memiliki penundaan startup dua detik dan menjalankan pemeriksaan setiap 30 detik. Untuk mengaktifkan IHealthCheckPublisher implementasi, sampel mendaftar ReadinessPublisher
sebagai layanan singleton dalam kontainer injeksi dependensi (DI):
services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();
services.AddHealthChecks()
.AddCheck<StartupHostedServiceHealthCheck>(
"hosted_service_startup",
failureStatus: HealthStatus.Degraded,
tags: new[] { "ready" });
services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = (check) => check.Tags.Contains("ready");
});
services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
Catatan
AspNetCore.Diagnostics.HealthChecks
termasuk penerbit untuk beberapa sistem, termasuk Application Insights.
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Membatasi pemeriksaan kesehatan dengan MapWhen
Gunakan MapWhen untuk mencabangkan alur permintaan untuk titik akhir pemeriksaan kesehatan secara kondisional.
Dalam contoh berikut, MapWhen
mencabangkan alur permintaan untuk mengaktifkan Middleware Pemeriksaan Kesehatan jika permintaan GET diterima untuk api/HealthCheck
titik akhir:
app.MapWhen(
context => context.Request.Method == HttpMethod.Get.Method &&
context.Request.Path.StartsWith("/api/HealthCheck"),
builder => builder.UseHealthChecks());
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.
ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.
Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:
- Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
- Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
- Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.
Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.
Pemeriksaan kesehatan dasar
Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.
Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis HealthStatus sebagai respons teks biasa terhadap klien. adalah HealthStatus
HealthStatus.Healthy, HealthStatus.Degraded, atau HealthStatus.Unhealthy.
Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Program.cs
. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks.
Contoh berikut membuat titik akhir pemeriksaan kesehatan di /healthz
:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();
var app = builder.Build();
app.MapHealthChecks("/healthz");
app.Run();
Buruh kapal HEALTHCHECK
Docker menawarkan arahan bawaan HEALTHCHECK
yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:
HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit
Contoh sebelumnya menggunakan curl
untuk membuat permintaan HTTP ke titik akhir pemeriksaan kesehatan di /healthz
. curl
tidak disertakan dalam gambar kontainer Linux .NET, tetapi dapat ditambahkan dengan menginstal paket yang diperlukan di Dockerfile. Kontainer yang menggunakan gambar berdasarkan Alpine Linux dapat menggunakan yang disertakan wget
sebagai pengganti curl
.
Membuat pemeriksaan kesehatan
Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy
, , Degraded
atau Unhealthy
. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi. Konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan. HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.
Contoh berikut menunjukkan tata letak pemeriksaan kesehatan:
public class SampleHealthCheck : IHealthCheck
{
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
var isHealthy = true;
// ...
if (isHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("A healthy result."));
}
return Task.FromResult(
new HealthCheckResult(
context.Registration.FailureStatus, "An unhealthy result."));
}
}
Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync metode . Contoh sebelumnya menetapkan variabel dummy, , isHealthy
ke true
. Jika nilai isHealthy
diatur ke false
, HealthCheckRegistration.FailureStatus status dikembalikan.
Jika CheckHealthAsync melempar pengecualian selama pemeriksaan, yang baru HealthReportEntry dikembalikan dengan HealthReportEntry.Status diatur ke FailureStatus. Status ini ditentukan oleh AddCheck (lihat bagian Daftarkan layanan pemeriksaan kesehatan) dan menyertakan pengecualian dalam yang menyebabkan kegagalan pemeriksaan. Description diatur ke pesan pengecualian.
Mendaftarkan layanan pemeriksaan kesehatan
Untuk mendaftarkan layanan pemeriksaan kesehatan, hubungi AddCheck di Program.cs
:
builder.Services.AddHealthChecks()
.AddCheck<SampleHealthCheck>("Sample");
Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null
(default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.
Tag dapat digunakan untuk memfilter pemeriksaan kesehatan. Tag dijelaskan di bagian Filter pemeriksaan kesehatan.
builder.Services.AddHealthChecks()
.AddCheck<SampleHealthCheck>(
"Sample",
failureStatus: HealthStatus.Degraded,
tags: new[] { "sample" });
AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, pemeriksaan kesehatan selalu mengembalikan hasil yang sehat:
builder.Services.AddHealthChecks()
.AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));
Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, pemeriksaan kesehatan yang diaktifkan jenis menerima bilangan bulat dan string dalam konstruktornya:
public class SampleHealthCheckWithArgs : IHealthCheck
{
private readonly int _arg1;
private readonly string _arg2;
public SampleHealthCheckWithArgs(int arg1, string arg2)
=> (_arg1, _arg2) = (arg1, arg2);
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
// ...
return Task.FromResult(HealthCheckResult.Healthy("A healthy result."));
}
}
Untuk mendaftarkan pemeriksaan kesehatan sebelumnya, panggil AddTypeActivatedCheck
dengan bilangan bulat dan string yang diteruskan sebagai argumen:
builder.Services.AddHealthChecks()
.AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
"Sample",
failureStatus: HealthStatus.Degraded,
tags: new[] { "sample" },
args: new object[] { 1, "Arg" });
Gunakan Perutean Pemeriksaan Kesehatan
Di Program.cs
, panggil MapHealthChecks
pembangun titik akhir dengan URL titik akhir atau jalur relatif:
app.MapHealthChecks("/healthz");
Memerlukan host
Panggil RequireHost
untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima:
app.MapHealthChecks("/healthz")
.RequireHost("www.contoso.com:5001");
Untuk membatasi titik akhir pemeriksaan kesehatan untuk merespons hanya pada port tertentu, tentukan port dalam panggilan ke RequireHost
. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan:
app.MapHealthChecks("/healthz")
.RequireHost("*:5001");
Peringatan
API yang bergantung pada header Host, seperti HttpRequest.Host dan RequireHost, tunduk pada potensi spoofing oleh klien.
Untuk mencegah spoofing host dan port, gunakan salah satu pendekatan berikut:
- Gunakan HttpContext.Connection (ConnectionInfo.LocalPort) tempat port diperiksa.
- Menggunakan pemfilteran Host.
Untuk mencegah klien yang tidak sah melakukan spoofing port, panggil RequireAuthorization:
app.MapHealthChecks("/healthz")
.RequireHost("*:5001")
.RequireAuthorization();
Untuk informasi selengkapnya, lihat Pencocokan host dalam rute dengan RequireHost.
Memerlukan otorisasi
Panggil RequireAuthorization untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization
beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default akan digunakan:
app.MapHealthChecks("/healthz")
.RequireAuthorization();
Mengaktifkan Permintaan Lintas Asal (CORS)
Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors
titik akhir pemeriksaan kesehatan. Kelebihan RequireCors
beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder
) atau nama kebijakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.
Opsi pemeriksaan kesehatan
HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:
- Memfilter pemeriksaan kesehatan
- Mengkustomisasi kode status HTTP
- Menyembunyikan header cache
- Sesuaikan output
Memfilter pemeriksaan kesehatan
Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi .
Contoh berikut memfilter pemeriksaan kesehatan sehingga hanya yang ditandai dengan sample
eksekusi:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});
Mengkustomisasi kode status HTTP
Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
ResultStatusCodes =
{
[HealthStatus.Healthy] = StatusCodes.Status200OK,
[HealthStatus.Degraded] = StatusCodes.Status200OK,
[HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
}
});
Menyembunyikan header cache
AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false
default), middleware mengatur atau mengambil Cache-Control
alih header , , Expires
dan Pragma
untuk mencegah penembolokan respons. Jika nilainya adalah true
, middleware tidak mengubah header cache respons:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
AllowCachingResponses = true
});
Sesuaikan output
Untuk menyesuaikan output laporan pemeriksaan kesehatan, atur HealthCheckOptions.ResponseWriter properti ke delegasi yang menulis respons:
app.MapHealthChecks("/healthz", new HealthCheckOptions
{
ResponseWriter = WriteResponse
});
Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Status
string . Delegasi kustom berikut menghasilkan respons JSON kustom menggunakan System.Text.Json:
private static Task WriteResponse(HttpContext context, HealthReport healthReport)
{
context.Response.ContentType = "application/json; charset=utf-8";
var options = new JsonWriterOptions { Indented = true };
using var memoryStream = new MemoryStream();
using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
{
jsonWriter.WriteStartObject();
jsonWriter.WriteString("status", healthReport.Status.ToString());
jsonWriter.WriteStartObject("results");
foreach (var healthReportEntry in healthReport.Entries)
{
jsonWriter.WriteStartObject(healthReportEntry.Key);
jsonWriter.WriteString("status",
healthReportEntry.Value.Status.ToString());
jsonWriter.WriteString("description",
healthReportEntry.Value.Description);
jsonWriter.WriteStartObject("data");
foreach (var item in healthReportEntry.Value.Data)
{
jsonWriter.WritePropertyName(item.Key);
JsonSerializer.Serialize(jsonWriter, item.Value,
item.Value?.GetType() ?? typeof(object));
}
jsonWriter.WriteEndObject();
jsonWriter.WriteEndObject();
}
jsonWriter.WriteEndObject();
jsonWriter.WriteEndObject();
}
return context.Response.WriteAsync(
Encoding.UTF8.GetString(memoryStream.ToArray()));
}
API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json
, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.
Pemeriksaan database
Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.
AspNetCore.Diagnostics.HealthChecks
, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, menyertakan pemeriksaan kesehatan yang berjalan terhadap database SQL Server. AspNetCore.Diagnostics.HealthChecks
SELECT 1
menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.
Peringatan
Saat memeriksa koneksi database dengan kueri, pilih kueri yang kembali dengan cepat. Pendekatan kueri menjalankan risiko kelebihan beban database dan menurunkan performanya. Dalam kebanyakan kasus, menjalankan kueri pengujian tidak diperlukan. Hanya membuat koneksi yang berhasil ke database sudah cukup. Jika Anda merasa perlu menjalankan kueri, pilih kueri SELECT sederhana, seperti SELECT 1
.
Untuk menggunakan pemeriksaan kesehatan SQL Server ini, sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer
paket NuGet. Contoh berikut mendaftarkan pemeriksaan kesehatan SQL Server:
builder.Services.AddHealthChecks()
.AddSqlServer(
builder.Configuration.GetConnectionString("DefaultConnection"));
Catatan
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Pemeriksaan Entity Framework Core DbContext
Pemeriksaan DbContext
mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext
. DbContext
Pemeriksaan didukung di aplikasi yang:
- Gunakan Core Entity Framework (EF).
- Sertakan referensi paket ke
Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
paket NuGet.
AddDbContextCheck mendaftarkan pemeriksaan kesehatan untuk DbContext. DbContext
disediakan ke metode sebagai TContext
. Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.
Secara default:
- Metode
DbContextHealthCheck
panggilanEF CoreCanConnectAsync
. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakanAddDbContextCheck
kelebihan beban metode. - Nama pemeriksaan kesehatan adalah nama jenisnya
TContext
.
Contoh berikut mendaftarkan DbContext
dan terkait DbContextHealthCheck
:
builder.Services.AddDbContext<SampleDbContext>(options =>
options.UseSqlServer(
builder.Configuration.GetConnectionString("DefaultConnection")));
builder.Services.AddHealthChecks()
.AddDbContextCheck<SampleDbContext>();
Pemeriksaan kesiapan dan keaktifan terpisah
Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:
- Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
- Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.
Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.
Tugas latar belakang berikut mensimulasikan proses startup yang memakan waktu sekitar 15 detik. Setelah selesai, tugas mengatur StartupHealthCheck.StartupCompleted
properti ke true:
public class StartupBackgroundService : BackgroundService
{
private readonly StartupHealthCheck _healthCheck;
public StartupBackgroundService(StartupHealthCheck healthCheck)
=> _healthCheck = healthCheck;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// Simulate the effect of a long-running task.
await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);
_healthCheck.StartupCompleted = true;
}
}
Laporan StartupHealthCheck
penyelesaian tugas startup yang berjalan lama dan mengekspos StartupCompleted
properti yang diatur oleh layanan latar belakang:
public class StartupHealthCheck : IHealthCheck
{
private volatile bool _isReady;
public bool StartupCompleted
{
get => _isReady;
set => _isReady = value;
}
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
if (StartupCompleted)
{
return Task.FromResult(HealthCheckResult.Healthy("The startup task has completed."));
}
return Task.FromResult(HealthCheckResult.Unhealthy("That startup task is still running."));
}
}
Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Program.cs
. Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan sebagai singleton:
builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();
builder.Services.AddHealthChecks()
.AddCheck<StartupHealthCheck>(
"Startup",
tags: new[] { "ready" });
Untuk membuat dua titik akhir pemeriksaan kesehatan yang berbeda, panggil MapHealthChecks
dua kali:
app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
{
Predicate = healthCheck => healthCheck.Tags.Contains("ready")
});
app.MapHealthChecks("/healthz/live", new HealthCheckOptions
{
Predicate = _ => false
});
Contoh sebelumnya membuat titik akhir pemeriksaan kesehatan berikut:
/healthz/ready
untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke yang ditandai denganready
./healthz/live
untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilter semua pemeriksaan kesehatan dengan kembalifalse
ke HealthCheckOptions.Predicate delegasi. Untuk informasi selengkapnya tentang pemfilteran pemeriksaan kesehatan, lihat Memfilter pemeriksaan kesehatan di artikel ini.
Sebelum tugas startup selesai, /healthz/ready
titik akhir melaporkan Unhealthy
status. Setelah tugas startup selesai, titik akhir ini melaporkan Healthy
status. Titik /healthz/live
akhir mengecualikan semua pemeriksaan dan melaporkan Healthy
status untuk semua panggilan.
Contoh Kubernetes
Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.
Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:
spec:
template:
spec:
readinessProbe:
# an http probe
httpGet:
path: /healthz/ready
port: 80
# length of time to wait for a pod to initialize
# after pod startup, before applying health checking
initialDelaySeconds: 30
timeoutSeconds: 1
ports:
- containerPort: 80
Mendistribusikan pustaka pemeriksaan kesehatan
Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:
Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.
Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya
Program.cs
. Pertimbangkan contoh pemeriksaan kesehatan berikut, yang menerimaarg1
danarg2
sebagai parameter konstruktor:public SampleHealthCheckWithArgs(int arg1, string arg2) => (_arg1, _arg2) = (arg1, arg2);
Tanda tangan sebelumnya menunjukkan bahwa pemeriksaan kesehatan memerlukan data kustom untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan:
arg1
: Titik data bilangan bulat untuk pemeriksaan kesehatan.arg2
: Argumen string untuk pemeriksaan kesehatan.name
: Nama pemeriksaan kesehatan opsional. Jikanull
, nilai default digunakan.failureStatus
: Opsional HealthStatus, yang dilaporkan untuk status kegagalan. Jikanull
, HealthStatus.Unhealthy digunakan.tags
: Kumpulan tag opsionalIEnumerable<string>
.
public static class SampleHealthCheckBuilderExtensions { private const string DefaultName = "Sample"; public static IHealthChecksBuilder AddSampleHealthCheck( this IHealthChecksBuilder healthChecksBuilder, int arg1, string arg2, string? name = null, HealthStatus? failureStatus = null, IEnumerable<string>? tags = default) { return healthChecksBuilder.Add( new HealthCheckRegistration( name ?? DefaultName, _ => new SampleHealthCheckWithArgs(arg1, arg2), failureStatus, tags)); } }
Penerbit Pemeriksaan Kesehatan
IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync kesehatan Anda dengan hasilnya. Proses ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.
HealthCheckPublisherOptions memungkinkan Anda untuk mengatur:
- Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan nanti. Nilai defaultnya adalah lima detik.
- Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
- Predicate: Jika Predicate (
null
default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode. - Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default
Contoh berikut menunjukkan tata letak penerbit kesehatan:
public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
{
if (report.Status == HealthStatus.Healthy)
{
// ...
}
else
{
// ...
}
return Task.CompletedTask;
}
}
Kelas HealthCheckPublisherOptions menyediakan properti untuk mengonfigurasi perilaku penerbit pemeriksaan kesehatan.
Contoh berikut mendaftarkan penerbit pemeriksaan kesehatan sebagai singleton dan mengonfigurasi HealthCheckPublisherOptions:
builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
options.Delay = TimeSpan.FromSeconds(2);
options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});
builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();
Catatan
AspNetCore.Diagnostics.HealthChecks
termasuk penerbit untuk beberapa sistem, termasuk Application Insights.
AspNetCore.Diagnostics.HealthChecks
tidak dipertahankan atau didukung oleh Microsoft.
Injeksi Dependensi dan Pemeriksaan Kesehatan
Dimungkinkan untuk menggunakan injeksi dependensi untuk menggunakan instans tertentu Type
di dalam kelas Pemeriksaan Kesehatan. Injeksi dependensi dapat berguna untuk menyuntikkan opsi atau konfigurasi global ke Pemeriksaan Kesehatan. Menggunakan injeksi dependensi bukanlah skenario umum untuk mengonfigurasi Pemeriksaan Kesehatan. Biasanya, setiap Pemeriksaan Kesehatan cukup spesifik untuk pengujian aktual dan dikonfigurasi menggunakan IHealthChecksBuilder
metode ekstensi.
Contoh berikut menunjukkan sampel Pemeriksaan Kesehatan yang mengambil objek konfigurasi melalui injeksi dependensi:
public class SampleHealthCheckWithDI : IHealthCheck
{
private readonly SampleHealthCheckWithDiConfig _config;
public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
=> _config = config;
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
var isHealthy = true;
// use _config ...
if (isHealthy)
{
return Task.FromResult(
HealthCheckResult.Healthy("A healthy result."));
}
return Task.FromResult(
new HealthCheckResult(
context.Registration.FailureStatus, "An unhealthy result."));
}
}
SampleHealthCheckWithDiConfig
Pemeriksaan kesehatan dan perlu ditambahkan ke kontainer layanan :
builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
.AddCheck<SampleHealthCheckWithDI>(
"With Dependency Injection",
tags: new[] { "inject" });
UseHealthChecks vs. MapHealthChecks
Ada dua cara untuk membuat pemeriksaan kesehatan dapat diakses oleh penelepon:
- UseHealthChecks mendaftarkan middleware untuk menangani permintaan pemeriksaan kesehatan di alur middleware.
- MapHealthChecks mendaftarkan titik akhir pemeriksaan kesehatan. Titik akhir dicocokkan dan dijalankan bersama dengan titik akhir lain di aplikasi.
Keuntungan menggunakan MapHealthChecks
lebih UseHealthChecks
dari adalah kemampuan untuk menggunakan middleware sadar titik akhir, seperti otorisasi, dan untuk memiliki kontrol terperinci yang lebih besar atas kebijakan pencocokan. Keuntungan utama menggunakan UseHealthChecks
over MapHealthChecks
adalah mengontrol persis di mana pemeriksaan kesehatan berjalan di alur middleware.
- Mengakhiri alur saat permintaan cocok dengan titik akhir pemeriksaan kesehatan. Sirkuit pendek sering diinginkan karena menghindari pekerjaan yang tidak perlu, seperti pengelogan dan middleware lainnya.
- Terutama digunakan untuk mengonfigurasi middleware pemeriksaan kesehatan dalam alur.
- Dapat mencocokkan jalur apa pun pada port dengan
null
atau kosongPathString
. Memungkinkan melakukan pemeriksaan kesehatan pada permintaan apa pun yang dibuat ke port yang ditentukan. - Kode sumber
MapHealthChecks Memungkinkan:
- Memetakan rute atau titik akhir tertentu untuk pemeriksaan kesehatan.
- Kustomisasi URL atau jalur tempat titik akhir pemeriksaan kesehatan dapat diakses.
- Memetakan beberapa titik akhir pemeriksaan kesehatan dengan rute atau konfigurasi yang berbeda. Dukungan beberapa titik akhir:
- Mengaktifkan titik akhir terpisah untuk berbagai jenis pemeriksaan kesehatan atau komponen.
- Digunakan untuk membedakan antara berbagai aspek kesehatan aplikasi atau menerapkan konfigurasi tertentu ke subset pemeriksaan kesehatan.
- Kode sumber
Sumber Daya Tambahan:
Catatan
Artikel ini sebagian dibuat dengan bantuan kecerdasan buatan. Sebelum menerbitkan, penulis akan meninjau dan merevisi konten jika diperlukan. Lihat Prinsip kami dalam menggunakan konten yang dihasilkan AI di Microsoft Learn.
ASP.NET Core