Aracılığıyla paylaş


ASP.NET Core'da sistem durumu denetimleri

Tarafından Glenn Condron ve Juergen Gutsch

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

ASP.NET Core, uygulama altyapısı bileşenlerinin sistem durumunu raporlamak için Sistem Durumu Denetimleri Ara Yazılımı ve kitaplıklar sunar.

Sistem durumu denetimleri bir uygulama tarafından HTTP uç noktaları olarak kullanıma sunulur. Sistem durumu denetimi uç noktaları çeşitli gerçek zamanlı izleme senaryoları için yapılandırılabilir:

  • Sistem durumu yoklamaları, bir uygulamanın durumunu denetlemek için kapsayıcı düzenleyicileri ve yük dengeleyiciler tarafından kullanılabilir. Örneğin, kapsayıcı düzenleyici sıralı dağıtımı durdurarak veya kapsayıcıyı yeniden başlatarak başarısız olan sistem durumu denetimine yanıt verebilir. Yük dengeleyici, trafiği hatalı örnekten iyi durumdaki bir örneğe yönlendirerek iyi durumda olmayan bir uygulamaya tepki verebilir.
  • İyi durumda bellek, disk ve diğer fiziksel sunucu kaynaklarının kullanımı izlenebilir.
  • Sistem durumu denetimleri, kullanılabilirliği ve normal çalışma durumunu onaylamak için bir uygulamanın veritabanları ve dış hizmet uç noktaları gibi bağımlılıklarını test edebilir.

Sistem durumu denetimleri genellikle bir uygulamanın durumunu denetlemek için bir dış izleme hizmeti veya kapsayıcı düzenleyici ile birlikte kullanılır. Bir uygulamaya sistem durumu denetimleri eklemeden önce hangi izleme sisteminin kullanılacağına karar verin. İzleme sistemi, hangi tür sistem durumu denetimlerinin oluşturulacağını ve uç noktalarının nasıl yapılandıracağını belirler.

Temel sistem durumu yoklaması

Birçok uygulama için, uygulamanın istekleri işlemek için kullanılabilirliğini (canlılık) bildiren temel bir sistem durumu yoklaması yapılandırması, uygulamanın durumunu keşfetmek için yeterlidir.

Temel yapılandırma, sistem durumu denetimi hizmetlerini kaydeder ve sistem durumu yanıtıyla BIR URL uç noktasında yanıt vermek için Sistem Durumu Denetimleri Ara Yazılımını çağırır. Varsayılan olarak, belirli bir bağımlılığı veya alt sistemi test etmek için belirli bir sistem durumu denetimi kaydedilmez. Uygulama, sistem durumu uç noktası URL'sinde yanıt verebiliyorsa iyi durumda kabul edilir. Varsayılan yanıt yazarı istemciye düz metin yanıtı olarak yazar HealthStatus . HealthStatus, veya HealthStatus.UnhealthyşeklindedirHealthStatus.HealthyHealthStatus.Degraded.

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Program.cskaydedin. çağrısı MapHealthChecksyaparak bir sistem durumu denetimi uç noktası oluşturun.

Aşağıdaki örnek konumunda /healthzbir sistem durumu denetimi uç noktası oluşturur:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker karşılaştırması hakkında daha fazla bilgi edininHEALTHCHECK

Docker , temel sistem durumu denetimi yapılandırmasını kullanan bir uygulamanın durumunu denetlemek için kullanılabilecek yerleşik HEALTHCHECK bir yönerge sunar:

HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit

Yukarıdaki örnek, konumundaki /healthzsistem durumu denetimi uç noktasına http isteğinde bulunmak için kullanırcurl. curl .NET Linux kapsayıcı görüntülerine dahil değildir, ancak gerekli paketi Dockerfile dosyasına yükleyerek eklenebilir. Alpine Linux tabanlı görüntüleri kullanan kapsayıcılar, yerine dahil wget edilen öğesini curlkullanabilir.

Sistem durumu denetimleri oluşturma

Sistem durumu denetimleri arabirimi uygulanarak IHealthCheck oluşturulur. yöntemi, CheckHealthAsync sistem durumunu , Degradedveya Unhealthyolarak Healthygösteren bir HealthCheckResult döndürür. Sonuç, yapılandırılabilir durum koduyla düz metin yanıtı olarak yazılır. Yapılandırma, Sistem durumu denetimi seçenekleri bölümünde açıklanmıştır. HealthCheckResult isteğe bağlı anahtar-değer çiftleri de döndürebilir.

Aşağıdaki örnekte sistem durumu denetiminin düzeni gösterilmektedir:

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."));
    }
}

Sistem durumu denetiminin mantığı yöntemine CheckHealthAsync yerleştirilir. Yukarıdaki örnek, isHealthytrueolarak bir kukla değişkeni ayarlar. değeri isHealthy olarak ayarlanırsafalseHealthCheckRegistration.FailureStatus, durum döndürülür.

Denetim sırasında bir özel durum oluşturursaCheckHealthAsync, değerine ayarlanmış FailureStatusyeni bir döndürülür HealthReportEntry HealthReportEntry.Status. Bu durum tarafından AddCheck tanımlanır (sistem durumu denetimi hizmetlerini kaydetme bölümüne bakın) ve denetim hatasına neden olan iç özel durumu içerir. Description, özel durumun iletisine ayarlanır.

Sistem durumu denetimi hizmetlerini kaydetme

Sistem durumu denetimi hizmetini kaydetmek için öğesini Program.csarayınAddCheck:

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>("Sample");

AddCheck Aşağıdaki örnekte gösterilen aşırı yükleme, sistem durumu denetimi hata bildirdiğinde hata durumunu (HealthStatus) bildirecek şekilde ayarlar. Hata durumu (varsayılan) HealthStatus.Unhealthy olarak ayarlanırsa null raporlanır. Bu aşırı yükleme, kitaplık yazarları için yararlı bir senaryodur ve sistem durumu denetimi uygulaması ayarı kabul ederse sistem durumu denetimi hatası oluştuğunda kitaplık tarafından belirtilen hata durumunun uygulama tarafından zorlandığı bir senaryodur.

Etiketler , sistem durumu denetimlerini filtrelemek için kullanılabilir. Etiketler, Sistem durumu denetimlerini filtrele bölümünde açıklanmıştır.

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" });

AddCheck bir lambda işlevini de yürütebilir. Aşağıdaki örnekte, sistem durumu denetimi her zaman iyi durumda bir sonuç döndürür:

builder.Services.AddHealthChecks()
    .AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));

Bir sistem durumu denetimi uygulamasına bağımsız değişkenleri geçirmek için çağrısı AddTypeActivatedCheck . Aşağıdaki örnekte, tür etkinleştirilmiş sistem durumu denetimi, oluşturucusunda bir tamsayı ve dize kabul eder:

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."));
    }
}

Önceki sistem durumu denetimini kaydetmek için, bağımsız değişken olarak geçirilen tamsayı ve dizeyle çağrısı AddTypeActivatedCheck yapın:

builder.Services.AddHealthChecks()
    .AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" },
        args: new object[] { 1, "Arg" });

Sistem Durumu Denetimleri Yönlendirmeyi Kullanma

içinde uç nokta URL'si Program.csveya göreli yolu ile uç nokta oluşturucusunu çağırın MapHealthChecks :

app.MapHealthChecks("/healthz");

Konağı gerektir

Sistem durumu denetimi uç noktası için bir veya daha fazla izin verilen konak belirtmek için çağrısı RequireHost yapın. Konaklar punycode yerine Unicode olmalıdır ve bir bağlantı noktası içerebilir. Koleksiyon sağlanmazsa, herhangi bir konak kabul edilir:

app.MapHealthChecks("/healthz")
    .RequireHost("www.contoso.com:5001");

Sistem durumu denetimi uç noktasını yalnızca belirli bir bağlantı noktasında yanıt verecek şekilde kısıtlamak için RequireHostçağrısında bir bağlantı noktası belirtin. Bu yaklaşım genellikle izleme hizmetleri için bir bağlantı noktasını kullanıma sunma amacıyla kapsayıcı ortamında kullanılır:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001");

Uyarı

ve RequireHostgibi HttpRequest.Host Konak üst bilgisini kullanan API, istemciler tarafından olası kimlik sahtekarlığına tabidir.

Konak ve bağlantı noktası kimlik sahtekarlığına engel olmak için aşağıdaki yaklaşımlardan birini kullanın:

Yetkisiz istemcilerin bağlantı noktası sahtekarlığına uğramasını önlemek için öğesini çağırın RequireAuthorization:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001")
    .RequireAuthorization();

Daha fazla bilgi için bkz . RequireHost ile yollarda konak eşleştirme.

Yetkilendirme gerektir

Durum denetimi isteği uç noktasında Yetkilendirme Ara Yazılımını çalıştırmak için çağırın RequireAuthorization . Aşırı RequireAuthorization yükleme bir veya daha fazla yetkilendirme ilkesi kabul eder. İlke sağlanmazsa, varsayılan yetkilendirme ilkesi kullanılır:

app.MapHealthChecks("/healthz")
    .RequireAuthorization();

Kaynaklar Arası İstekleri (CORS) etkinleştirme

Sistem durumu denetimlerini tarayıcıda el ile çalıştırmak yaygın bir senaryo olmasa da, CORS Ara Yazılımı sistem durumu denetimleri uç noktalarına çağrılarak RequireCors etkinleştirilebilir. Aşırı RequireCors yükleme bir CORS ilke oluşturucusu temsilcisini (CorsPolicyBuilder) veya bir ilke adını kabul eder. Daha fazla bilgi için bkz . ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) Etkinleştirme.

Sistem durumu denetimi seçenekleri

HealthCheckOptions sistem durumu denetimi davranışını özelleştirme fırsatı sağlar:

Sistem durumu denetimlerini filtrele

Varsayılan olarak, Sistem Durumu Denetimleri Ara Yazılımı tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için seçeneğine Predicate boole döndüren bir işlev sağlayın.

Aşağıdaki örnek, sistem durumu denetimlerini yalnızca çalıştır ile etiketlenenlerin çalışması için sample filtreler:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});

HTTP durum kodunu özelleştirme

Durum durumunu HTTP durum kodlarıyla eşlemeyi özelleştirmek için kullanın ResultStatusCodes . Aşağıdaki StatusCodes atamalar ara yazılım tarafından kullanılan varsayılan değerlerdir. Durum kodu değerlerini gereksinimlerinizi karşılayacak şekilde değiştirin:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Önbellek üst bilgilerini gizleme

AllowCachingResponses Durum Denetimleri Ara Yazılımının yanıt önbelleğe almayı önlemek için yoklama yanıtına HTTP üst bilgileri ekleyip eklemediğini denetler. Değer (varsayılan) ise false , ara yazılım yanıt önbelleğe almayı önlemek için , Expiresve Pragma üst bilgilerini ayarlar veya geçersiz kılarCache-Control. değeri ise trueara yazılım yanıtın önbellek üst bilgilerini değiştirmez:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    AllowCachingResponses = true
});

Çıktıyı özelleştirme

Sistem durumu denetimleri raporunun çıkışını özelleştirmek için, özelliğini yanıtı yazan bir temsilci olarak ayarlayın HealthCheckOptions.ResponseWriter :

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResponseWriter = WriteResponse
});

Varsayılan temsilci, dize değeriyle en düşük düz metin yanıtını HealthReport.Statusyazar. Aşağıdaki özel temsilci kullanarak System.Text.Jsonözel bir JSON yanıtı verir:

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()));
}

Sistem durumu denetimleri API'si, karmaşık JSON dönüş biçimleri için yerleşik destek sağlamaz çünkü biçim, seçtiğiniz izleme sistemine özgüdür. Yukarıdaki örneklerde verilen yanıtı gerektiği gibi özelleştirin. ile System.Text.JsonJSON serileştirmesi hakkında daha fazla bilgi için bkz . .NET'te JSON'ı seri hale getirme ve seri durumdan çıkarma.

Veritabanı yoklaması

Sistem durumu denetimi, veritabanının normal yanıt verdiğini belirtmek için boole testi olarak çalıştırılacak bir veritabanı sorgusu belirtebilir.

AspNetCore.Diagnostics.HealthChecks, ASP.NET Core uygulamaları için bir sistem durumu denetimi kitaplığı, SQL Server veritabanında çalışan bir sistem durumu denetimi içerir. AspNetCore.Diagnostics.HealthChecks veritabanı bağlantısının iyi durumda olduğunu onaylamak için veritabanına karşı bir SELECT 1 sorgu yürütür.

Uyarı

Bir sorguyla veritabanı bağlantısını denetlerken, hızlı bir şekilde döndüren bir sorgu seçin. Sorgu yaklaşımı veritabanını aşırı yükleme ve performansını düşürme riskini çalıştırır. Çoğu durumda test sorgusu çalıştırmak gerekli değildir. Yalnızca veritabanıyla başarılı bir bağlantı oluşturmak yeterlidir. Sorgu çalıştırmayı gerekli bulursanız, gibi SELECT 1basit bir SELECT sorgusu seçin.

Bu SQL Server sistem durumu denetimini kullanmak için NuGet paketine AspNetCore.HealthChecks.SqlServer bir paket başvurusu ekleyin. Aşağıdaki örnek SQL Server sistem durumu denetimini kaydeder:

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);

Not

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Entity Framework Core DbContext araştırması

Denetim, DbContext uygulamanın için EF CoreDbContextyapılandırılan veritabanıyla iletişim kurabildiğini onaylar. Denetim DbContext , aşağıdaki uygulamalarda desteklenir:

AddDbContextCheck için bir sistem durumu denetimi DbContextkaydeder. DbContext yöntemine olarak TContextsağlanır. Hata durumunu, etiketleri ve özel test sorgusunu yapılandırmak için bir aşırı yükleme kullanılabilir.

Varsayılan olarak:

  • 'DbContextHealthChecknin CanConnectAsync yöntemini çağırırEF Core. Yöntem aşırı yüklemelerini kullanarak AddDbContextCheck sistem durumu denetlenirken çalıştırılacak işlemi özelleştirebilirsiniz.
  • Sistem durumu denetiminin adı türün TContext adıdır.

Aşağıdaki örnek ve DbContext ilişkili DbContextHealthCheckbir kaydeder:

builder.Services.AddDbContext<SampleDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddHealthChecks()
    .AddDbContextCheck<SampleDbContext>();

Ayrı hazırlık ve canlılık yoklamaları

Bazı barındırma senaryolarında, iki uygulama durumunu ayırt etmek için bir çift sistem durumu denetimi kullanılır:

  • Hazır olma, uygulamanın normal çalışıp çalışmadığını ancak istekleri almaya hazır olmadığını gösterir.
  • Canlılık , bir uygulamanın kilitlenip kilitlenmediğini ve yeniden başlatılması gerektiğini belirtir.

Aşağıdaki örneği göz önünde bulundurun: Bir uygulamanın istekleri işlemeye hazır olması için büyük bir yapılandırma dosyasını indirmesi gerekir. İlk indirme başarısız olursa uygulamanın yeniden başlatılmasını istemiyoruz çünkü uygulama dosyayı birkaç kez indirmeyi yeniden deneyebilir. İşlemin canlılığını açıklamak için canlılık araştırması kullanırız, başka hiçbir denetim çalıştırılır. Yapılandırma dosyası indirme başarılı olmadan önce isteklerin uygulamaya gönderilmesini de engellemek istiyoruz. İndirme başarılı olana ve uygulama istekleri almaya hazır olana kadar "hazır değil" durumunu belirtmek için hazır olma araştırması kullanırız.

Aşağıdaki arka plan görevi, yaklaşık 15 saniye süren bir başlangıç işleminin benzetimini yapar. İşlem tamamlandıktan sonra görev özelliği true olarak ayarlar StartupHealthCheck.StartupCompleted :

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;
    }
}

uzun StartupHealthCheck süre çalışan başlangıç görevinin tamamlandığını bildirir ve arka plan hizmeti tarafından ayarlanan özelliği kullanıma sunar StartupCompleted :

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."));
    }
}

Sistem durumu denetimi ile birlikte barındırılan hizmetle AddCheck Program.cs birlikte kaydedilir. Barındırılan hizmetin sistem durumu denetiminde özelliğini ayarlaması gerektiğinden, sistem durumu denetimi de hizmet kapsayıcısında tekil olarak kaydedilir:

builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();

builder.Services.AddHealthChecks()
    .AddCheck<StartupHealthCheck>(
        "Startup",
        tags: new[] { "ready" });

İki farklı sistem durumu denetimi uç noktası oluşturmak için iki kez çağrısında MapHealthChecks bulunur:

app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("ready")
});

app.MapHealthChecks("/healthz/live", new HealthCheckOptions
{
    Predicate = _ => false
});

Yukarıdaki örnek aşağıdaki sistem durumu denetimi uç noktalarını oluşturur:

  • /healthz/ready hazır olma denetimi için. Hazır olma denetimi, ile readyetiketlenenlere sistem durumu denetimlerini filtreler.
  • /healthz/live canlılık kontrolü için. Canlılık denetimi, temsilciyi geri döndürerek false HealthCheckOptions.Predicate tüm sistem durumu denetimlerini filtreler. Sistem durumu denetimlerini filtreleme hakkında daha fazla bilgi için bu makaledeki Sistem durumu denetimlerini filtreleme bölümüne bakın.

Başlangıç görevi tamamlanmadan önce uç /healthz/ready nokta bir Unhealthy durum bildirir. Başlangıç görevi tamamlandıktan sonra bu uç nokta bir Healthy durum bildirir. Uç /healthz/live nokta tüm denetimleri dışlar ve tüm çağrılar için bir Healthy durum bildirir.

Kubernetes örneği

Ayrı hazır olma ve canlılık denetimleri kullanmak Kubernetes gibi bir ortamda kullanışlıdır. Kubernetes'te, temel alınan veritabanı kullanılabilirliği testi gibi istekleri kabul etmeden önce zaman alan başlangıç çalışmalarını çalıştırmak için bir uygulama gerekebilir. Ayrı denetimler kullanmak, düzenleyicinin uygulamanın çalışıp çalışmadığını ancak henüz hazır olup olmadığını veya uygulamanın başlatılamadığını ayırt etmesini sağlar. Kubernetes'teki hazır olma ve canlılık yoklamaları hakkında daha fazla bilgi için Kubernetes belgelerindeki Canlılık ve Hazırlık Yoklamalarını Yapılandırma bölümüne bakın.

Aşağıdaki örnekte Kubernetes hazır olma yoklaması yapılandırması gösterilmektedir:

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

Sistem durumu denetimi kitaplığı dağıtma

Sistem durumu denetimini kitaplık olarak dağıtmak için:

  1. Arabirimi tek başına sınıf olarak uygulayan IHealthCheck bir sistem durumu denetimi yazın. sınıfı, yapılandırma verilerine erişmek için bağımlılık ekleme (DI), tür etkinleştirme ve adlandırılmış seçenekleri kullanabilir.

  2. Kullanan uygulamanın yönteminde Program.cs çağıran parametrelerle bir uzantı yöntemi yazın. Ve'yi oluşturucu parametreleri olarak kabul arg1 arg2 eden aşağıdaki örnek sistem durumu denetimini göz önünde bulundurun:

    public SampleHealthCheckWithArgs(int arg1, string arg2)
        => (_arg1, _arg2) = (arg1, arg2);
    

    Yukarıdaki imza, sistem durumu denetiminin sistem durumu denetimi yoklama mantığını işlemek için özel veriler gerektirdiğini gösterir. Veriler, durum denetimi bir uzantı yöntemiyle kaydedildiğinde sistem durumu denetimi örneğini oluşturmak için kullanılan temsilciye sağlanır. Aşağıdaki örnekte, çağıran şunları belirtir:

    • arg1: Sistem durumu denetimi için bir tamsayı veri noktası.
    • arg2: Sistem durumu denetimi için bir dize bağımsız değişkeni.
    • name: İsteğe bağlı bir sistem durumu denetimi adı. ise null, varsayılan bir değer kullanılır.
    • failureStatus: Hata durumu için bildirilen isteğe bağlı HealthStatusbir . HealthStatus.Unhealthy ise nullkullanılır.
    • tags: İsteğe bağlı IEnumerable<string> bir etiket koleksiyonu.
    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));
        }
    }
    

Sistem Durumu Denetimi Yayımcısı

hizmet kapsayıcısına bir IHealthCheckPublisher eklendiğinde sistem durumu denetimi sistemi, sistem durumu denetimlerinizi düzenli aralıklarla yürütür ve sonuçla birlikte çağrılar PublishAsync gerçekleştirir. Bu işlem, her işlemin sistem durumunu belirlemek için izleme sistemini düzenli aralıklarla çağırmasını bekleyen, anında iletme tabanlı sistem durumu izleme sistemi senaryosunda kullanışlıdır.

HealthCheckPublisherOptions şunları ayarlamanıza izin verir:

  • Delay: Örnekleri yürütmeden IHealthCheckPublisher önce uygulama başlatıldıktan sonra uygulanan ilk gecikme. Gecikme başlangıçta bir kez uygulanır ve sonraki yinelemeler için geçerli değildir. Varsayılan değer beş saniyedir.
  • Period: Yürütme süresi IHealthCheckPublisher . Varsayılan değer 30 saniyedir.
  • Predicate: (varsayılan) ise Predicate null , sistem durumu denetimi yayımcı hizmeti tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için denetim kümesini filtreleyen bir işlev sağlayın. Koşul her dönem değerlendirilir.
  • Timeout: Tüm IHealthCheckPublisher örnekler için sistem durumu denetimlerini yürütmek için zaman aşımı. Zaman aşımı olmadan yürütmek için kullanın InfiniteTimeSpan . Varsayılan değer 30 saniyedir.

Aşağıdaki örnekte sistem durumu yayımcısının düzeni gösterilmektedir:

public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
    public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            // ...
        }
        else
        {
            // ...
        }

        return Task.CompletedTask;
    }
}

sınıfı, HealthCheckPublisherOptions sistem durumu denetimi yayımcısının davranışını yapılandırmaya yönelik özellikler sağlar.

Aşağıdaki örnek, bir sistem durumu denetimi yayımcısını tekil olarak kaydeder ve yapılandırılır 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:

Bireysel Sistem Durumu Denetimleri

Delay ve Period her HealthCheckRegistration birinde ayrı ayrı ayarlanabilir. Bazı sistem durumu denetimlerini içinde HealthCheckPublisherOptionsayarlanan süreden farklı bir hızda çalıştırmak istediğinizde bu yararlı olur.

Aşağıdaki kod, için ve'yi Period SampleHealthCheck1ayarlarDelay:

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();

Bağımlılık Ekleme ve Sistem Durumu Denetimleri

Bir Sistem Durumu Denetimi sınıfı içindeki belirli Type bir örneğini kullanmak için bağımlılık ekleme özelliğini kullanmak mümkündür. Bağımlılık ekleme, sistem durumu denetimine seçenekler veya genel yapılandırma eklemek için yararlı olabilir. Bağımlılık eklemenin kullanılması, Sistem Durumu Denetimlerini yapılandırmak için yaygın bir senaryo değildir. Genellikle, her Sistem Durumu Denetimi gerçek teste oldukça özeldir ve uzantı yöntemleri kullanılarak IHealthChecksBuilder yapılandırılır.

Aşağıdaki örnekte, bağımlılık ekleme yoluyla bir yapılandırma nesnesi alan örnek bir Sistem Durumu Denetimi gösterilmektedir:

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 ve Sistem Durumu denetiminin hizmet kapsayıcısına eklenmesi gerekir:

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 ile MapHealthChecks karşılaştırması

Sistem durumu denetimlerini arayanlar için erişilebilir hale getirmenin iki yolu vardır:

  • UseHealthChecks ara yazılım işlem hattında sistem durumu denetimleri isteklerini işlemek için ara yazılımı kaydeder.
  • MapHealthChecks sistem durumu denetimleri uç noktasını kaydeder. Uç nokta, uygulamadaki diğer uç noktalarla birlikte eşleştirilir ve yürütülür.

Over UseHealthChecks kullanmanın MapHealthChecks avantajı, yetkilendirme gibi uç nokta kullanan ara yazılımları kullanabilmek ve eşleşen ilke üzerinde daha ayrıntılı denetime sahip olmaktır. over MapHealthChecks kullanmanın UseHealthChecks birincil avantajı, sistem durumu denetimlerinin ara yazılım işlem hattında tam olarak nerede çalıştığını denetlemektir.

UseHealthChecks:

  • bir istek sistem durumu denetimi uç noktasıyla eşleştiğinde işlem hattını sonlandırır. Kısa devre, günlüğe kaydetme ve diğer ara yazılım gibi gereksiz işleri önlediğinden genellikle tercih edilir.
  • Öncelikle işlem hattında sistem durumu denetimi ara yazılımını yapılandırmak için kullanılır.
  • veya boş PathStringolan bir bağlantı noktasındaki herhangi bir null yolu eşleştirebilir. Belirtilen bağlantı noktasına yapılan isteklerde sistem durumu denetimi gerçekleştirmeye izin verir.
  • Kaynak kod

MapHealthChecks Sağ -lar:

  • bir istek sistem durumu denetimi uç noktasıyla eşleştiğinde çağrısı yaparak ShortCircuitişlem hattını sonlandırma. Örneğin, app.MapHealthChecks("/healthz").ShortCircuit();. Daha fazla bilgi için bkz . Yönlendirmeden sonra kısa devre ara yazılımı.
  • Sistem durumu denetimleri için belirli yolları veya uç noktaları eşleme.
  • Sistem durumu denetimi uç noktasının erişilebilir olduğu URL'nin veya yolun özelleştirilmesi.
  • Farklı yollar veya yapılandırmalarla birden çok sistem durumu denetimi uç noktasını eşleme. Birden çok uç nokta desteği:
    • Farklı sistem durumu denetimleri veya bileşenleri için ayrı uç noktaları etkinleştirir.
    • Uygulamanın sistem durumunun farklı yönlerini ayırt etmek veya sistem durumu denetimlerinin alt kümelerine belirli yapılandırmalar uygulamak için kullanılır.
  • Kaynak kod

Ek kaynaklar

Not

Bu makale, kısmen yapay zeka yardımıyla oluşturulmuştur. Yayımlanmadan önce içerik bir yazar tarafından gözden geçirilmiş ve gereken şekilde düzeltilmiştir. Microsoft Learn'de yapay zeka tarafından oluşturulan içerik kullanma ilkelerimize bakın.

ASP.NET Core, uygulama altyapısı bileşenlerinin sistem durumunu raporlamak için Sistem Durumu Denetimleri Ara Yazılımı ve kitaplıklar sunar.

Sistem durumu denetimleri bir uygulama tarafından HTTP uç noktaları olarak kullanıma sunulur. Sistem durumu denetimi uç noktaları çeşitli gerçek zamanlı izleme senaryoları için yapılandırılabilir:

  • Sistem durumu yoklamaları, bir uygulamanın durumunu denetlemek için kapsayıcı düzenleyicileri ve yük dengeleyiciler tarafından kullanılabilir. Örneğin, kapsayıcı düzenleyici sıralı dağıtımı durdurarak veya kapsayıcıyı yeniden başlatarak başarısız olan sistem durumu denetimine yanıt verebilir. Yük dengeleyici, trafiği hatalı örnekten iyi durumdaki bir örneğe yönlendirerek iyi durumda olmayan bir uygulamaya tepki verebilir.
  • İyi durumda bellek, disk ve diğer fiziksel sunucu kaynaklarının kullanımı izlenebilir.
  • Sistem durumu denetimleri, kullanılabilirliği ve normal çalışma durumunu onaylamak için bir uygulamanın veritabanları ve dış hizmet uç noktaları gibi bağımlılıklarını test edebilir.

Örnek kodu görüntüleme veya indirme (indirme)

Örnek uygulama, bu makalede açıklanan senaryoların örneklerini içerir. Belirli bir senaryo için örnek uygulamayı çalıştırmak için, projenin bir komut kabuğundaki klasöründeki dotnet run komutunu kullanın. Örnek uygulamanın nasıl kullanılacağı hakkında ayrıntılı bilgi için bu makaledeki örnek uygulamanın README.md dosyasına ve senaryo açıklamalarına bakın.

Önkoşullar

Sistem durumu denetimleri genellikle bir uygulamanın durumunu denetlemek için bir dış izleme hizmeti veya kapsayıcı düzenleyici ile birlikte kullanılır. Bir uygulamaya sistem durumu denetimleri eklemeden önce hangi izleme sisteminin kullanılacağına karar verin. İzleme sistemi, hangi tür sistem durumu denetimlerinin oluşturulacağını ve uç noktalarının nasıl yapılandıracağını belirler.

Pakete Microsoft.AspNetCore.Diagnostics.HealthChecks ASP.NET Core uygulamaları için örtük olarak başvurulur. Entity Framework Core kullanarak sistem durumu denetimlerini çalıştırmak için pakete Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore bir başvuru ekleyin.

Örnek uygulama, çeşitli senaryolara yönelik sistem durumu denetimlerini göstermek için başlangıç kodu sağlar. Veritabanı yoklama senaryosu, kullanarak AspNetCore.Diagnostics.HealthChecksveritabanı bağlantısının durumunu denetler. DbContext araştırma senaryosu kullanarak EF CoreDbContextveritabanını denetler. Veritabanı senaryolarını keşfetmek için örnek uygulama:

Not

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Başka bir sistem durumu denetimi senaryosu, sistem durumu denetimlerini bir yönetim bağlantı noktasına filtrelemeyi gösterir. Örnek uygulama, yönetim URL'sini ve yönetim bağlantı noktasını içeren bir Properties/launchSettings.json dosya oluşturmanızı gerektirir. Daha fazla bilgi için Bağlantı noktasına göre filtreleme bölümüne bakın.

Temel sistem durumu yoklaması

Birçok uygulama için, uygulamanın istekleri işlemek için kullanılabilirliğini (canlılık) bildiren temel bir sistem durumu yoklaması yapılandırması, uygulamanın durumunu keşfetmek için yeterlidir.

Temel yapılandırma, sistem durumu denetimi hizmetlerini kaydeder ve sistem durumu yanıtıyla BIR URL uç noktasında yanıt vermek için Sistem Durumu Denetimleri Ara Yazılımını çağırır. Varsayılan olarak, belirli bir bağımlılığı veya alt sistemi test etmek için belirli bir sistem durumu denetimi kaydedilmez. Uygulama, sistem durumu uç noktası URL'sinde yanıt verebiliyorsa iyi durumda kabul edilir. Varsayılan yanıt yazarı, durumu (HealthStatus) istemciye düz metin yanıtı olarak yazar ve bir , HealthStatus.Degradedveya HealthStatus.Unhealthy durumunu belirtirHealthStatus.Healthy.

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. içinde Startup.Configurearayarak MapHealthChecks bir sistem durumu denetimi uç noktası oluşturun.

Örnek uygulamada, sistem durumu denetimi uç noktası şu konumda /health oluşturulur: (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");
        });
    }
}

Örnek uygulamayı kullanarak temel yapılandırma senaryosunu çalıştırmak için, projenin klasöründeki komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario basic

Docker örneği

Docker , temel sistem durumu denetimi yapılandırmasını kullanan bir uygulamanın durumunu denetlemek için kullanılabilecek yerleşik HEALTHCHECK bir yönerge sunar:

HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit

Sistem durumu denetimleri oluşturma

Sistem durumu denetimleri arabirimi uygulanarak IHealthCheck oluşturulur. yöntemi, CheckHealthAsync sistem durumunu , Degradedveya Unhealthyolarak Healthygösteren bir HealthCheckResult döndürür. Sonuç, yapılandırılabilir durum koduyla düz metin yanıtı olarak yazılır (yapılandırma, Sistem durumu denetimi seçenekleri bölümünde açıklanmıştır). HealthCheckResult isteğe bağlı anahtar-değer çiftleri de döndürebilir.

Aşağıdaki ExampleHealthCheck sınıf, sistem durumu denetiminin düzenini gösterir. Sistem durumu denetimleri mantığı yöntemine CheckHealthAsync yerleştirilir. Aşağıdaki örnek, healthCheckResultHealthytrueolarak bir manken değişkeni ayarlar. değeri healthCheckResultHealthy olarak ayarlanırsafalseHealthCheckRegistration.FailureStatus, durum döndürülür.

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."));
    }
}

Denetim sırasında bir özel durum oluşturursaCheckHealthAsync, tarafından tanımlanan AddCheck (sistem durumu denetimi hizmetlerini kaydetme bölümüne bakın) ve başlangıçta denetim hatasına neden olan iç özel durumu içeren bir yeni HealthReportEntry döndürülür HealthReportEntry.Status FailureStatus. Description, özel durumun iletisine ayarlanır.

Sistem durumu denetimi hizmetlerini kaydetme

türü ExampleHealthCheck ile sistem durumu denetimi hizmetlerine AddCheck Startup.ConfigureServiceseklenir:

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

AddCheck Aşağıdaki örnekte gösterilen aşırı yükleme, sistem durumu denetimi hata bildirdiğinde hata durumunu (HealthStatus) bildirecek şekilde ayarlar. Hata durumu (varsayılan) HealthStatus.Unhealthy olarak ayarlanırsa null raporlanır. Bu aşırı yükleme, kitaplık yazarları için yararlı bir senaryodur ve sistem durumu denetimi uygulaması ayarı kabul ederse sistem durumu denetimi hatası oluştuğunda kitaplık tarafından belirtilen hata durumunun uygulama tarafından zorlandığı bir senaryodur.

Etiketler, sistem durumu denetimlerini filtrelemek için kullanılabilir (Sistem durumu denetimlerini filtrele bölümünde daha ayrıntılı olarak açıklanmıştır).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck bir lambda işlevini de yürütebilir. Aşağıdaki örnekte, sistem durumu denetimi adı olarak Example belirtilir ve denetim her zaman iyi durumda bir durum döndürür:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Bir sistem durumu denetimi uygulamasına bağımsız değişkenleri geçirmek için çağrısı AddTypeActivatedCheck . Aşağıdaki örnekte, TestHealthCheckWithArgs çağrıldığında CheckHealthAsync kullanılmak üzere bir tamsayı ve dize kabul eder:

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 , uygulamaya geçirilen tamsayı ve dize ile çağrılarak AddTypeActivatedCheck kaydedilir:

services.AddHealthChecks()
    .AddTypeActivatedCheck<TestHealthCheckWithArgs>(
        "test", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "example" }, 
        args: new object[] { 5, "string" });

Sistem Durumu Denetimleri Yönlendirmeyi Kullanma

içinde uç nokta URL'si Startup.Configureveya göreli yolu ile uç nokta oluşturucusunu çağırın MapHealthChecks :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Konağı gerektir

Sistem durumu denetimi uç noktası için bir veya daha fazla izin verilen konak belirtmek için çağrısı RequireHost yapın. Konaklar punycode yerine Unicode olmalıdır ve bir bağlantı noktası içerebilir. Koleksiyon sağlanmazsa, herhangi bir konak kabul edilir.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});

Daha fazla bilgi için Bağlantı noktasına göre filtreleme bölümüne bakın.

Yetkilendirme gerektir

Durum denetimi isteği uç noktasında Yetkilendirme Ara Yazılımını çalıştırmak için çağırın RequireAuthorization . Aşırı RequireAuthorization yükleme bir veya daha fazla yetkilendirme ilkesi kabul eder. İlke sağlanmazsa, varsayılan yetkilendirme ilkesi kullanılır.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireAuthorization();
});

Kaynaklar Arası İstekleri (CORS) etkinleştirme

Sistem durumu denetimlerini tarayıcıda el ile çalıştırmak yaygın bir kullanım senaryosu olmasa da, CORS Ara Yazılımı sistem durumu denetimleri uç noktalarına çağrılarak RequireCors etkinleştirilebilir. Aşırı RequireCors yükleme, CORS ilke oluşturucu temsilcisini (CorsPolicyBuilder) veya ilke adını kabul eder. İlke sağlanmazsa, varsayılan CORS ilkesi kullanılır. Daha fazla bilgi için bkz . ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) Etkinleştirme.

Sistem durumu denetimi seçenekleri

HealthCheckOptions sistem durumu denetimi davranışını özelleştirme fırsatı sağlar:

Sistem durumu denetimlerini filtrele

Varsayılan olarak, Sistem Durumu Denetimleri Ara Yazılımı tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için seçeneğine Predicate boole döndüren bir işlev sağlayın. Aşağıdaki örnekte, sistem durumu denetimi işlevin Bar koşullu deyiminde etiketine (bar_tag) göre filtrelenmiştir; burada true yalnızca sistem durumu denetiminin Tags özelliği veya baz_tagile eşleşirse foo_tag döndürülür:

Startup.ConfigureServices içinde:

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" });

içinde Startup.Configure, Predicate 'Çubuk' sistem durumu denetimini filtreler. Yalnızca Foo ve Baz yürütülür:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
});

HTTP durum kodunu özelleştirme

Durum durumunu HTTP durum kodlarıyla eşlemeyi özelleştirmek için kullanın ResultStatusCodes . Aşağıdaki StatusCodes atamalar ara yazılım tarafından kullanılan varsayılan değerlerdir. Durum kodu değerlerini gereksinimlerinizi karşılayacak şekilde değiştirin.

Startup.Configure içinde:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResultStatusCodes =
        {
            [HealthStatus.Healthy] = StatusCodes.Status200OK,
            [HealthStatus.Degraded] = StatusCodes.Status200OK,
            [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
        }
    });
});

Önbellek üst bilgilerini gizleme

AllowCachingResponses Durum Denetimleri Ara Yazılımının yanıt önbelleğe almayı önlemek için yoklama yanıtına HTTP üst bilgileri ekleyip eklemediğini denetler. Değer (varsayılan) ise false , ara yazılım yanıt önbelleğe almayı önlemek için , Expiresve Pragma üst bilgilerini ayarlar veya geçersiz kılarCache-Control. Değeri ise trueara yazılım yanıtın önbellek üst bilgilerini değiştirmez.

Startup.Configure içinde:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        AllowCachingResponses = true
    });
});

Çıktıyı özelleştirme

içinde Startup.Configure, yanıtı yazmak için seçeneğini bir temsilci olarak ayarlayın HealthCheckOptions.ResponseWriter :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
});

Varsayılan temsilci, dize değeriyle en düşük düz metin yanıtını HealthReport.Statusyazar. Aşağıdaki özel temsilciler özel bir JSON yanıtı verir.

Örnek uygulamadaki ilk örnekte nasıl kullanılacağı System.Text.Jsongösterilmektedir:

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);
    }
}

İkinci örnekte nasıl kullanılacağı Newtonsoft.Jsongösterilmektedir:

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));
}

Örnek uygulamada, SYSTEM_TEXT_JSON sürümünü etkinleştirmek Newtonsoft.Json için önişlemci CustomWriterStartup.cs yönergesini açıklama satırı yapınWriteResponse.

Sistem durumu denetimleri API'si, karmaşık JSON dönüş biçimleri için yerleşik destek sağlamaz çünkü biçim, seçtiğiniz izleme sistemine özgüdür. Yukarıdaki örneklerde verilen yanıtı gerektiği gibi özelleştirin. ile System.Text.JsonJSON serileştirmesi hakkında daha fazla bilgi için bkz . .NET'te JSON'ı seri hale getirme ve seri durumdan çıkarma.

Veritabanı yoklaması

Sistem durumu denetimi, veritabanının normal yanıt verdiğini belirtmek için boole testi olarak çalıştırılacak bir veritabanı sorgusu belirtebilir.

Örnek uygulama, SQL Server veritabanında sistem durumu denetimi çalıştırmak için ASP.NET Core uygulamaları için bir sistem durumu denetimi kitaplığı kullanır AspNetCore.Diagnostics.HealthChecks. AspNetCore.Diagnostics.HealthChecks veritabanı bağlantısının iyi durumda olduğunu onaylamak için veritabanına karşı bir SELECT 1 sorgu yürütür.

Uyarı

Bir sorguyla veritabanı bağlantısını denetlerken, hızlı bir şekilde döndüren bir sorgu seçin. Sorgu yaklaşımı veritabanını aşırı yükleme ve performansını düşürme riskini çalıştırır. Çoğu durumda test sorgusu çalıştırmak gerekli değildir. Yalnızca veritabanıyla başarılı bir bağlantı oluşturmak yeterlidir. Sorgu çalıştırmayı gerekli bulursanız, gibi SELECT 1basit bir SELECT sorgusu seçin.

için bir paket başvurusu AspNetCore.HealthChecks.SqlServerekleyin.

Örnek uygulamanın dosyasında geçerli bir veritabanı bağlantı dizesi appsettings.json sağlayın. Uygulama adlı HealthCheckSamplebir SQL Server veritabanı kullanır:

{
  "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": "*"
}

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. Örnek uygulama, veritabanının AddSqlServer bağlantı dizesi (DbHealthStartup.cs):

services.AddHealthChecks()
    .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Örnek uygulamayı kullanarak veritabanı yoklaması senaryosunu çalıştırmak için, projenin klasöründeki komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario db

Not

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Entity Framework Core DbContext araştırması

Denetim, DbContext uygulamanın için EF CoreDbContextyapılandırılan veritabanıyla iletişim kurabildiğini onaylar. Denetim DbContext , aşağıdaki uygulamalarda desteklenir:

AddDbContextCheck<TContext> için bir sistem durumu denetimi DbContextkaydeder. DbContext yöntemine olarak TContext sağlanır. Hata durumunu, etiketleri ve özel test sorgusunu yapılandırmak için bir aşırı yükleme kullanılabilir.

Varsayılan olarak:

  • 'DbContextHealthChecknin CanConnectAsync yöntemini çağırırEF Core. Yöntem aşırı yüklemelerini kullanarak AddDbContextCheck sistem durumu denetlenirken çalıştırılacak işlemi özelleştirebilirsiniz.
  • Sistem durumu denetiminin adı türün TContext adıdır.

Örnek uygulamada, AppDbContext hizmetine sağlanır AddDbContextCheck ve (DbContextHealthStartup.cs içinde Startup.ConfigureServices bir hizmet olarak kaydedilir):

services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        Configuration["ConnectionStrings:DefaultConnection"]);
});

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Örnek uygulamayı kullanarak araştırma senaryosunu DbContext çalıştırmak için, bağlantı dizesi tarafından belirtilen veritabanının SQL Server örneğinde mevcut olmadığını onaylayın. Veritabanı varsa silin.

Aşağıdaki komutu projenin klasöründen bir komut kabuğunda yürütür:

dotnet run --scenario dbcontext

Uygulama çalıştırıldıktan sonra tarayıcıda uç noktaya istekte /health bulunarak sistem durumunu denetleyin. Veritabanı AppDbContext mevcut olmadığından, uygulama aşağıdaki yanıtı sağlar:

Unhealthy

Veritabanını oluşturmak için örnek uygulamayı tetikleyin. adresine bir istekte bulun./createdatabase Uygulama yanıt verir:

Creating the database...
Done!
Navigate to /health to see the health status.

Uç noktaya bir istekte bulunın /health . Veritabanı ve bağlam mevcut olduğundan uygulama şunları yanıtlar:

Healthy

Veritabanını silmek için örnek uygulamayı tetikleyin. adresine bir istekte bulun./deletedatabase Uygulama yanıt verir:

Deleting the database...
Done!
Navigate to /health to see the health status.

Uç noktaya bir istekte bulunın /health . Uygulama iyi durumda olmayan bir yanıt sağlar:

Unhealthy

Ayrı hazırlık ve canlılık yoklamaları

Bazı barındırma senaryolarında, iki uygulama durumunu ayırt etmek için bir çift sistem durumu denetimi kullanılır:

  • Hazır olma, uygulamanın normal çalışıp çalışmadığını ancak istekleri almaya hazır olmadığını gösterir.
  • Canlılık , bir uygulamanın kilitlenip kilitlenmediğini ve yeniden başlatılması gerektiğini belirtir.

Aşağıdaki örneği göz önünde bulundurun: Bir uygulamanın istekleri işlemeye hazır olması için büyük bir yapılandırma dosyasını indirmesi gerekir. İlk indirme başarısız olursa uygulamanın yeniden başlatılmasını istemiyoruz çünkü uygulama dosyayı birkaç kez indirmeyi yeniden deneyebilir. İşlemin canlılığını açıklamak için canlılık araştırması kullanırız, başka hiçbir denetim çalıştırılır. Yapılandırma dosyası indirme başarılı olmadan önce isteklerin uygulamaya gönderilmesini de engellemek istiyoruz. İndirme başarılı olana ve uygulama istekleri almaya hazır olana kadar "hazır değil" durumunu belirtmek için hazır olma araştırması kullanırız.

Örnek uygulama, Barındırılan Hizmette uzun süre çalışan başlangıç görevinin tamamlanmasını raporlamak için bir sistem durumu denetimi içerir. , StartupHostedServiceHealthCheck barındırılan hizmetin uzun süre çalışan görevi tamamlandığında ayarlayabildiği true bir özelliğini StartupTaskCompletedkullanıma sunar (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."));
    }
}

Uzun süre çalışan arka plan görevi, Barındırılan Hizmet (Services/StartupHostedService ) tarafından başlatılır. Görevin sonunda olarak StartupHostedServiceHealthCheck.StartupTaskCompleted ayarlanır 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()
    {
    }
}

Sistem durumu denetimi ile birlikte barındırılan hizmetle AddCheck Startup.ConfigureServices birlikte kaydedilir. Barındırılan hizmetin sistem durumu denetiminde özelliğini ayarlaması gerektiğinden, sistem durumu denetimi de hizmet kapsayıcısında (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>();

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur. Örnek uygulamada sistem durumu denetimi uç noktaları şu konumda oluşturulur:

  • /health/ready hazır olma denetimi için. Hazır olma denetimi, durum denetimlerini etiketle birlikte sistem durumu denetimine ready filtreler.
  • /health/live canlılık kontrolü için. Canlılık denetimi, içinde döndürerek filtrelerini filtreler StartupHostedServiceHealthCheck (daha fazla bilgi için bkz. Sistem durumu denetimlerini filtreleme)false HealthCheckOptions.Predicate

Aşağıdaki örnek kodda:

  • Hazır olma denetimi , 'hazır' etiketiyle tüm kayıtlı denetimleri kullanır.
  • tüm Predicate denetimleri dışlar ve 200-Tamam döndürür.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

Hazırlık/canlılık yapılandırma senaryosunu örnek uygulamayı kullanarak çalıştırmak için, projenin klasöründeki komut kabuğunda aşağıdaki komutu yürütür:

dotnet run --scenario liveness

Tarayıcıda, 15 saniye geçene kadar birkaç kez ziyaret edin /health/ready . Sistem durumu denetimi ilk 15 saniye için raporlar Unhealthy . 15 saniye sonra uç nokta, barındırılan hizmet tarafından uzun süre çalışan görevin tamamlanmasını yansıtan değerini raporlar Healthy.

Bu örnek ayrıca iki saniyelik bir gecikmeyle ilk hazırlık denetimini çalıştıran bir Sistem Durumu Denetimi Yayımcısı (IHealthCheckPublisher uygulama) oluşturur. Daha fazla bilgi için Sistem Durumu Denetimi Yayımcısı bölümüne bakın.

Kubernetes örneği

Ayrı hazır olma ve canlılık denetimleri kullanmak Kubernetes gibi bir ortamda kullanışlıdır. Kubernetes'te, temel alınan veritabanı kullanılabilirliği testi gibi istekleri kabul etmeden önce zaman alan başlangıç çalışmalarını çalıştırmak için bir uygulama gerekebilir. Ayrı denetimler kullanmak, düzenleyicinin uygulamanın çalışıp çalışmadığını ancak henüz hazır olup olmadığını veya uygulamanın başlatılamadığını ayırt etmesini sağlar. Kubernetes'teki hazır olma ve canlılık yoklamaları hakkında daha fazla bilgi için Kubernetes belgelerindeki Canlılık ve Hazırlık Yoklamalarını Yapılandırma bölümüne bakın.

Aşağıdaki örnekte Kubernetes hazır olma yoklaması yapılandırması gösterilmektedir:

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

Özel yanıt yazıcısı ile ölçüm tabanlı yoklama

Örnek uygulama, özel yanıt yazıcısı ile bir bellek durumu denetimi gösterir.

MemoryHealthCheck uygulama belirli bir bellek eşiğinden (örnek uygulamada 1 GB) daha fazla kullanıyorsa düzeyi düşürülmüş durumu bildirir. , HealthCheckResult uygulama için Çöp Toplayıcı (GC) bilgilerini içerir (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));
    }
}

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. sistem durumu denetimini'ne AddCheckgeçirerek etkinleştirmek yerine, MemoryHealthCheck hizmet olarak kaydedilir. Tüm IHealthCheck kayıtlı hizmetler sistem durumu denetimi hizmetleri ve ara yazılım tarafından kullanılabilir. Sistem durumu denetimi hizmetlerini Tekli hizmetler olarak kaydetmenizi öneririz.

Örnek uygulamanın içinde CustomWriterStartup.cs :

services.AddHealthChecks()
    .AddMemoryHealthCheck("memory");

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur. WriteResponse Sistem durumu denetimi yürütürken özel bir JSON yanıtı çıkarmak için özelliğine bir temsilci sağlanırResponseWriter:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
}

Temsilci, WriteResponse öğesini CompositeHealthCheckResult bir JSON nesnesine biçimlendirip sistem durumu denetimi yanıtı için JSON çıkışı verir. Daha fazla bilgi için Çıkışı özelleştirme bölümüne bakın.

Örnek uygulamayı kullanarak ölçüm tabanlı araştırmayı özel yanıt yazıcı çıkışıyla çalıştırmak için, projenin klasöründen bir komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario writer

Not

AspNetCore.Diagnostics.HealthChecks disk depolama ve maksimum değer canlılık denetimleri dahil olmak üzere ölçüm tabanlı sistem durumu denetimi senaryolarını içerir.

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Bağlantı noktasına göre filtrele

MapHealthChecks Sistem durumu denetimi isteklerini belirtilen bağlantı noktasıyla kısıtlamak için bir bağlantı noktası belirten bir URL deseniyle çağrısında RequireHost bulun. Bu yaklaşım genellikle izleme hizmetleri için bir bağlantı noktasını kullanıma sunma amacıyla kapsayıcı ortamında kullanılır.

Örnek uygulama, Ortam Değişkeni Yapılandırma Sağlayıcısı'nı kullanarak bağlantı noktasını yapılandırıyor. Bağlantı noktası dosyasında ayarlanır launchSettings.json ve bir ortam değişkeni aracılığıyla yapılandırma sağlayıcısına geçirilir. Ayrıca sunucuyu yönetim bağlantı noktasındaki istekleri dinleyecek şekilde yapılandırmanız gerekir.

Yönetim bağlantı noktası yapılandırmasını göstermek üzere örnek uygulamayı kullanmak için dosyayı bir Properties klasörde oluşturunlaunchSettings.json.

Örnek uygulamadaki aşağıdaki Properties/launchSettings.json dosya, örnek uygulamanın proje dosyalarına dahil değildir ve el ile oluşturulmalıdır:

{
  "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/"
    }
  }
}

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. içinde Startup.Configurearayarak MapHealthChecks bir sistem durumu denetimi uç noktası oluşturun.

Örnek uygulamada, RequireHost içindeki uç noktasında Startup.Configure çağrısı, yapılandırmadan yönetim bağlantı noktasını belirtir:

endpoints.MapHealthChecks("/health")
    .RequireHost($"*:{Configuration["ManagementPort"]}");

Uç noktalar içindeki örnek uygulamada Startup.Configureoluşturulur. Aşağıdaki örnek kodda:

  • Hazır olma denetimi , 'hazır' etiketiyle tüm kayıtlı denetimleri kullanır.
  • tüm Predicate denetimleri dışlar ve 200-Tamam döndürür.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

Not

Yönetim bağlantı noktasını kodda açıkça ayarlayarak örnek uygulamada dosya oluşturmaktan launchSettings.json kaçınabilirsiniz. Program.cs öğesinin oluşturulduğu yerde HostBuilder öğesine bir çağrı ListenAnyIP ekleyin ve uygulamanın yönetim bağlantı noktası uç noktasını sağlayın. içinde Configure ManagementPortStartup.cs, ile RequireHostyönetim bağlantı noktasını belirtin:

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");
});

Örnek uygulamayı kullanarak yönetim bağlantı noktası yapılandırma senaryosunu çalıştırmak için, projenin klasöründen bir komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario port

Sistem durumu denetimi kitaplığı dağıtma

Sistem durumu denetimini kitaplık olarak dağıtmak için:

  1. Arabirimi tek başına sınıf olarak uygulayan IHealthCheck bir sistem durumu denetimi yazın. sınıfı, yapılandırma verilerine erişmek için bağımlılık ekleme (DI), tür etkinleştirme ve adlandırılmış seçenekleri kullanabilir.

    sistem durumu denetimlerinin mantığında CheckHealthAsync:

    • data1 ve data2 yönteminde yoklamanın sistem durumu denetimi mantığını çalıştırmak için kullanılır.
    • AccessViolationException işlenir.

    AccessViolationException bir oluştuğunda, FailureStatus ile birlikte HealthCheckResult döndürülür ve kullanıcıların sistem durumu denetimleri hata durumunu yapılandırmasına izin verir.

    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);
                }
            }
        }
    }
    
  2. Kullanan uygulamanın yönteminde Startup.Configure çağıran parametrelerle bir uzantı yöntemi yazın. Aşağıdaki örnekte, aşağıdaki sistem durumu denetimi yöntemi imzasını varsayın:

    ExampleHealthCheck(string, string, int )
    

    Yukarıdaki imza, sistem durumu denetimi yoklama mantığını işlemek için öğesinin ek veri gerektirdiğini gösterir ExampleHealthCheck . Veriler, durum denetimi bir uzantı yöntemiyle kaydedildiğinde sistem durumu denetimi örneğini oluşturmak için kullanılan temsilciye sağlanır. Aşağıdaki örnekte, çağıran isteğe bağlı belirtir:

    • sistem durumu denetimi adı (name ). example_health_check ise nullkullanılır.
    • sistem durumu denetimidata1 () için dize veri noktası.
    • sistem durumu denetimidata2 () için tamsayı veri noktası. 1 ise nullkullanılır.
    • hata durumu (HealthStatus). Varsayılan değer: null. HealthStatus.Unhealthy hata durumu için bildirilir.null
    • etiketlerini () seçinIEnumerable<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));
        }
    }
    

Sistem Durumu Denetimi Yayımcısı

hizmet kapsayıcısına bir IHealthCheckPublisher eklendiğinde sistem durumu denetimi sistemi, sistem durumu denetimlerinizi düzenli aralıklarla yürütür ve sonuçla birlikte çağrılar PublishAsync gerçekleştirir. Bu, her işlemin sistem durumunu belirlemek için izleme sistemini düzenli aralıklarla çağırmasını bekleyen, anında iletme tabanlı sistem durumu izleme sistemi senaryosunda kullanışlıdır.

Arabirimin IHealthCheckPublisher tek bir yöntemi vardır:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions şunları ayarlamanıza izin verir:

  • Delay: Örnekleri yürütmeden IHealthCheckPublisher önce uygulama başlatıldıktan sonra uygulanan ilk gecikme. Gecikme başlangıçta bir kez uygulanır ve sonraki yinelemeler için geçerli değildir. Varsayılan değer beş saniyedir.
  • Period: Yürütme süresi IHealthCheckPublisher . Varsayılan değer 30 saniyedir.
  • Predicate: (varsayılan) ise Predicate null , sistem durumu denetimi yayımcı hizmeti tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için denetim kümesini filtreleyen bir işlev sağlayın. Koşul her dönem değerlendirilir.
  • Timeout: Tüm IHealthCheckPublisher örnekler için sistem durumu denetimlerini yürütmek için zaman aşımı. Zaman aşımı olmadan yürütmek için kullanın InfiniteTimeSpan . Varsayılan değer 30 saniyedir.

Örnek uygulamada ReadinessPublisher bir IHealthCheckPublisher uygulamadır. Sistem durumu denetimi durumu, her denetim için şu günlük düzeyinde günlüğe kaydedilir:

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;
    }
}

Örnek uygulamanın LivenessProbeStartup örneğinde, hazırlık denetiminin StartupHostedService iki saniyelik başlatma gecikmesi vardır ve denetimi 30 saniyede bir çalıştırır. Uygulamayı etkinleştirmek IHealthCheckPublisher için örnek, bağımlılık ekleme (DI) kapsayıcısında tek bir hizmet olarak kaydederReadinessPublisher:

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>();

Not

AspNetCore.Diagnostics.HealthChecks Application Insights dahil olmak üzere çeşitli sistemler için yayımcılar içerir.

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

MapWhen ile sistem durumu denetimlerini kısıtlama

Durum denetimi uç noktaları için istek işlem hattını koşullu olarak dallara ayırmak için kullanın MapWhen .

Aşağıdaki örnekte, MapWhen uç nokta için bir GET isteği alındığında Sistem Durumu Denetimleri Ara Yazılımını etkinleştirmek üzere istek işlem hattını dallar api/HealthCheck :

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

Daha fazla bilgi için, bkz. ASP.NET Core Ara Yazılımı.

ASP.NET Core, uygulama altyapısı bileşenlerinin sistem durumunu raporlamak için Sistem Durumu Denetimleri Ara Yazılımı ve kitaplıklar sunar.

Sistem durumu denetimleri bir uygulama tarafından HTTP uç noktaları olarak kullanıma sunulur. Sistem durumu denetimi uç noktaları çeşitli gerçek zamanlı izleme senaryoları için yapılandırılabilir:

  • Sistem durumu yoklamaları, bir uygulamanın durumunu denetlemek için kapsayıcı düzenleyicileri ve yük dengeleyiciler tarafından kullanılabilir. Örneğin, kapsayıcı düzenleyici sıralı dağıtımı durdurarak veya kapsayıcıyı yeniden başlatarak başarısız olan sistem durumu denetimine yanıt verebilir. Yük dengeleyici, trafiği hatalı örnekten iyi durumdaki bir örneğe yönlendirerek iyi durumda olmayan bir uygulamaya tepki verebilir.
  • İyi durumda bellek, disk ve diğer fiziksel sunucu kaynaklarının kullanımı izlenebilir.
  • Sistem durumu denetimleri, kullanılabilirliği ve normal çalışma durumunu onaylamak için bir uygulamanın veritabanları ve dış hizmet uç noktaları gibi bağımlılıklarını test edebilir.

Örnek kodu görüntüleme veya indirme (indirme)

Örnek uygulama, bu makalede açıklanan senaryoların örneklerini içerir. Belirli bir senaryo için örnek uygulamayı çalıştırmak için, projenin bir komut kabuğundaki klasöründeki dotnet run komutunu kullanın. Örnek uygulamanın nasıl kullanılacağı hakkında ayrıntılı bilgi için bu makaledeki örnek uygulamanın README.md dosyasına ve senaryo açıklamalarına bakın.

Önkoşullar

Sistem durumu denetimleri genellikle bir uygulamanın durumunu denetlemek için bir dış izleme hizmeti veya kapsayıcı düzenleyici ile birlikte kullanılır. Bir uygulamaya sistem durumu denetimleri eklemeden önce hangi izleme sisteminin kullanılacağına karar verin. İzleme sistemi, hangi tür sistem durumu denetimlerinin oluşturulacağını ve uç noktalarının nasıl yapılandıracağını belirler.

Pakete Microsoft.AspNetCore.Diagnostics.HealthChecks ASP.NET Core uygulamaları için örtük olarak başvurulur. Entity Framework Core kullanarak sistem durumu denetimlerini çalıştırmak için pakete Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore bir paket başvurusu ekleyin.

Örnek uygulama, çeşitli senaryolara yönelik sistem durumu denetimlerini göstermek için başlangıç kodu sağlar. Veritabanı yoklama senaryosu, kullanarak AspNetCore.Diagnostics.HealthChecksveritabanı bağlantısının durumunu denetler. DbContext araştırma senaryosu kullanarak EF CoreDbContextveritabanını denetler. Veritabanı senaryolarını keşfetmek için örnek uygulama:

Not

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Başka bir sistem durumu denetimi senaryosu, sistem durumu denetimlerini bir yönetim bağlantı noktasına filtrelemeyi gösterir. Örnek uygulama, yönetim URL'sini ve yönetim bağlantı noktasını içeren bir Properties/launchSettings.json dosya oluşturmanızı gerektirir. Daha fazla bilgi için Bağlantı noktasına göre filtreleme bölümüne bakın.

Temel sistem durumu yoklaması

Birçok uygulama için, uygulamanın istekleri işlemek için kullanılabilirliğini (canlılık) bildiren temel bir sistem durumu yoklaması yapılandırması, uygulamanın durumunu keşfetmek için yeterlidir.

Temel yapılandırma, sistem durumu denetimi hizmetlerini kaydeder ve sistem durumu yanıtıyla BIR URL uç noktasında yanıt vermek için Sistem Durumu Denetimleri Ara Yazılımını çağırır. Varsayılan olarak, belirli bir bağımlılığı veya alt sistemi test etmek için belirli bir sistem durumu denetimi kaydedilmez. Uygulama, sistem durumu uç noktası URL'sinde yanıt verebiliyorsa iyi durumda kabul edilir. Varsayılan yanıt yazarı, durumu (HealthStatus) istemciye düz metin yanıtı olarak yazar ve bir , HealthStatus.Degradedveya HealthStatus.Unhealthy durumunu belirtirHealthStatus.Healthy.

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. içinde Startup.Configurearayarak MapHealthChecks bir sistem durumu denetimi uç noktası oluşturun.

Örnek uygulamada, sistem durumu denetimi uç noktası şu konumda /health oluşturulur: (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");
        });
    }
}

Örnek uygulamayı kullanarak temel yapılandırma senaryosunu çalıştırmak için, projenin klasöründeki komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario basic

Docker örneği

Docker , temel sistem durumu denetimi yapılandırmasını kullanan bir uygulamanın durumunu denetlemek için kullanılabilecek yerleşik HEALTHCHECK bir yönerge sunar:

HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit

Sistem durumu denetimleri oluşturma

Sistem durumu denetimleri arabirimi uygulanarak IHealthCheck oluşturulur. yöntemi, CheckHealthAsync sistem durumunu , Degradedveya Unhealthyolarak Healthygösteren bir HealthCheckResult döndürür. Sonuç, yapılandırılabilir durum koduyla düz metin yanıtı olarak yazılır (yapılandırma, Sistem durumu denetimi seçenekleri bölümünde açıklanmıştır). HealthCheckResult isteğe bağlı anahtar-değer çiftleri de döndürebilir.

Aşağıdaki ExampleHealthCheck sınıf, sistem durumu denetiminin düzenini gösterir. Sistem durumu denetimleri mantığı yöntemine CheckHealthAsync yerleştirilir. Aşağıdaki örnek, healthCheckResultHealthytrueolarak bir manken değişkeni ayarlar. değeri healthCheckResultHealthy olarak ayarlanırsafalseHealthCheckResult.Unhealthy, durum döndürülür.

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."));
    }
}

Sistem durumu denetimi hizmetlerini kaydetme

türü ExampleHealthCheck ile sistem durumu denetimi hizmetlerine AddCheck Startup.ConfigureServiceseklenir:

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

AddCheck Aşağıdaki örnekte gösterilen aşırı yükleme, sistem durumu denetimi hata bildirdiğinde hata durumunu (HealthStatus) bildirecek şekilde ayarlar. Hata durumu (varsayılan) HealthStatus.Unhealthy olarak ayarlanırsa null raporlanır. Bu aşırı yükleme, kitaplık yazarları için yararlı bir senaryodur ve sistem durumu denetimi uygulaması ayarı kabul ederse sistem durumu denetimi hatası oluştuğunda kitaplık tarafından belirtilen hata durumunun uygulama tarafından zorlandığı bir senaryodur.

Etiketler, sistem durumu denetimlerini filtrelemek için kullanılabilir (Sistem durumu denetimlerini filtrele bölümünde daha ayrıntılı olarak açıklanmıştır).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck bir lambda işlevini de yürütebilir. Aşağıdaki örnekte, sistem durumu denetimi adı olarak Example belirtilir ve denetim her zaman iyi durumda bir durum döndürür:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Bir sistem durumu denetimi uygulamasına bağımsız değişkenleri geçirmek için çağrısı AddTypeActivatedCheck . Aşağıdaki örnekte, TestHealthCheckWithArgs çağrıldığında CheckHealthAsync kullanılmak üzere bir tamsayı ve dize kabul eder:

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 , uygulamaya geçirilen tamsayı ve dize ile çağrılarak AddTypeActivatedCheck kaydedilir:

services.AddHealthChecks()
    .AddTypeActivatedCheck<TestHealthCheckWithArgs>(
        "test", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "example" }, 
        args: new object[] { 5, "string" });

Sistem Durumu Denetimleri Yönlendirmeyi Kullanma

içinde uç nokta URL'si Startup.Configureveya göreli yolu ile uç nokta oluşturucusunu çağırın MapHealthChecks :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Konağı gerektir

Sistem durumu denetimi uç noktası için bir veya daha fazla izin verilen konak belirtmek için çağrısı RequireHost yapın. Konaklar punycode yerine Unicode olmalıdır ve bir bağlantı noktası içerebilir. Koleksiyon sağlanmazsa, herhangi bir konak kabul edilir.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});

Daha fazla bilgi için Bağlantı noktasına göre filtreleme bölümüne bakın.

Yetkilendirme gerektir

Durum denetimi isteği uç noktasında Yetkilendirme Ara Yazılımını çalıştırmak için çağırın RequireAuthorization . Aşırı RequireAuthorization yükleme bir veya daha fazla yetkilendirme ilkesi kabul eder. İlke sağlanmazsa, varsayılan yetkilendirme ilkesi kullanılır.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireAuthorization();
});

Kaynaklar Arası İstekleri (CORS) etkinleştirme

Sistem durumu denetimlerini tarayıcıda el ile çalıştırmak yaygın bir kullanım senaryosu olmasa da, CORS Ara Yazılımı sistem durumu denetimleri uç noktalarına çağrılarak RequireCors etkinleştirilebilir. Aşırı RequireCors yükleme, CORS ilke oluşturucu temsilcisini (CorsPolicyBuilder) veya ilke adını kabul eder. İlke sağlanmazsa, varsayılan CORS ilkesi kullanılır. Daha fazla bilgi için bkz . ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) Etkinleştirme.

Sistem durumu denetimi seçenekleri

HealthCheckOptions sistem durumu denetimi davranışını özelleştirme fırsatı sağlar:

Sistem durumu denetimlerini filtrele

Varsayılan olarak, Sistem Durumu Denetimleri Ara Yazılımı tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için seçeneğine Predicate boole döndüren bir işlev sağlayın. Aşağıdaki örnekte, sistem durumu denetimi işlevin Bar koşullu deyiminde etiketine (bar_tag) göre filtrelenmiştir; burada true yalnızca sistem durumu denetiminin Tags özelliği veya baz_tagile eşleşirse foo_tag döndürülür:

Startup.ConfigureServices içinde:

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" });

içinde Startup.Configure, Predicate 'Çubuk' sistem durumu denetimini filtreler. Yalnızca Foo ve Baz yürütülür:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
});

HTTP durum kodunu özelleştirme

Durum durumunu HTTP durum kodlarıyla eşlemeyi özelleştirmek için kullanın ResultStatusCodes . Aşağıdaki StatusCodes atamalar ara yazılım tarafından kullanılan varsayılan değerlerdir. Durum kodu değerlerini gereksinimlerinizi karşılayacak şekilde değiştirin.

Startup.Configure içinde:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResultStatusCodes =
        {
            [HealthStatus.Healthy] = StatusCodes.Status200OK,
            [HealthStatus.Degraded] = StatusCodes.Status200OK,
            [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
        }
    });
});

Önbellek üst bilgilerini gizleme

AllowCachingResponses Durum Denetimleri Ara Yazılımının yanıt önbelleğe almayı önlemek için yoklama yanıtına HTTP üst bilgileri ekleyip eklemediğini denetler. Değer (varsayılan) ise false , ara yazılım yanıt önbelleğe almayı önlemek için , Expiresve Pragma üst bilgilerini ayarlar veya geçersiz kılarCache-Control. Değeri ise trueara yazılım yanıtın önbellek üst bilgilerini değiştirmez.

Startup.Configure içinde:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        AllowCachingResponses = true
    });
});

Çıktıyı özelleştirme

içinde Startup.Configure, yanıtı yazmak için seçeneğini bir temsilci olarak ayarlayın HealthCheckOptions.ResponseWriter :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
});

Varsayılan temsilci, dize değeriyle en düşük düz metin yanıtını HealthReport.Statusyazar. Aşağıdaki özel temsilciler özel bir JSON yanıtı verir.

Örnek uygulamadaki ilk örnekte nasıl kullanılacağı System.Text.Jsongösterilmektedir:

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);
    }
}

İkinci örnekte Newtonsoft.Json dosyasının nasıl kullanılacağı gösterilmektedir:

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));
}

Örnek uygulamada, SYSTEM_TEXT_JSON sürümünü etkinleştirmek Newtonsoft.Json için önişlemci CustomWriterStartup.cs yönergesini açıklama satırı yapınWriteResponse.

Sistem durumu denetimleri API'si, karmaşık JSON dönüş biçimleri için yerleşik destek sağlamaz çünkü biçim, seçtiğiniz izleme sistemine özgüdür. Yukarıdaki örneklerde verilen yanıtı gerektiği gibi özelleştirin. ile System.Text.JsonJSON serileştirmesi hakkında daha fazla bilgi için bkz . .NET'te JSON'ı seri hale getirme ve seri durumdan çıkarma.

Veritabanı yoklaması

Sistem durumu denetimi, veritabanının normal yanıt verdiğini belirtmek için boole testi olarak çalıştırılacak bir veritabanı sorgusu belirtebilir.

Örnek uygulama, SQL Server veritabanında sistem durumu denetimi çalıştırmak için ASP.NET Core uygulamaları için bir sistem durumu denetimi kitaplığı kullanır AspNetCore.Diagnostics.HealthChecks. AspNetCore.Diagnostics.HealthChecks veritabanı bağlantısının iyi durumda olduğunu onaylamak için veritabanına karşı bir SELECT 1 sorgu yürütür.

Uyarı

Bir sorguyla veritabanı bağlantısını denetlerken, hızlı bir şekilde döndüren bir sorgu seçin. Sorgu yaklaşımı veritabanını aşırı yükleme ve performansını düşürme riskini çalıştırır. Çoğu durumda test sorgusu çalıştırmak gerekli değildir. Yalnızca veritabanıyla başarılı bir bağlantı oluşturmak yeterlidir. Sorgu çalıştırmayı gerekli bulursanız, gibi SELECT 1basit bir SELECT sorgusu seçin.

için bir paket başvurusu AspNetCore.HealthChecks.SqlServerekleyin.

Örnek uygulamanın dosyasında geçerli bir veritabanı bağlantı dizesi appsettings.json sağlayın. Uygulama adlı HealthCheckSamplebir SQL Server veritabanı kullanır:

{
  "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": "*"
}

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. Örnek uygulama, veritabanının AddSqlServer bağlantı dizesi (DbHealthStartup.cs):

services.AddHealthChecks()
    .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Örnek uygulamayı kullanarak veritabanı yoklaması senaryosunu çalıştırmak için, projenin klasöründeki komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario db

Not

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Entity Framework Core DbContext araştırması

Denetim, DbContext uygulamanın için EF CoreDbContextyapılandırılan veritabanıyla iletişim kurabildiğini onaylar. Denetim DbContext , aşağıdaki uygulamalarda desteklenir:

AddDbContextCheck<TContext> için bir sistem durumu denetimi DbContextkaydeder. DbContext yöntemine olarak TContext sağlanır. Hata durumunu, etiketleri ve özel test sorgusunu yapılandırmak için bir aşırı yükleme kullanılabilir.

Varsayılan olarak:

  • 'DbContextHealthChecknin CanConnectAsync yöntemini çağırırEF Core. Yöntem aşırı yüklemelerini kullanarak AddDbContextCheck sistem durumu denetlenirken çalıştırılacak işlemi özelleştirebilirsiniz.
  • Sistem durumu denetiminin adı türün TContext adıdır.

Örnek uygulamada, AppDbContext hizmetine sağlanır AddDbContextCheck ve (DbContextHealthStartup.cs içinde Startup.ConfigureServices bir hizmet olarak kaydedilir):

services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        Configuration["ConnectionStrings:DefaultConnection"]);
});

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Örnek uygulamayı kullanarak araştırma senaryosunu DbContext çalıştırmak için, bağlantı dizesi tarafından belirtilen veritabanının SQL Server örneğinde mevcut olmadığını onaylayın. Veritabanı varsa silin.

Aşağıdaki komutu projenin klasöründen bir komut kabuğunda yürütür:

dotnet run --scenario dbcontext

Uygulama çalıştırıldıktan sonra tarayıcıda uç noktaya istekte /health bulunarak sistem durumunu denetleyin. Veritabanı AppDbContext mevcut olmadığından, uygulama aşağıdaki yanıtı sağlar:

Unhealthy

Veritabanını oluşturmak için örnek uygulamayı tetikleyin. adresine bir istekte bulun./createdatabase Uygulama yanıt verir:

Creating the database...
Done!
Navigate to /health to see the health status.

Uç noktaya bir istekte bulunın /health . Veritabanı ve bağlam mevcut olduğundan uygulama şunları yanıtlar:

Healthy

Veritabanını silmek için örnek uygulamayı tetikleyin. adresine bir istekte bulun./deletedatabase Uygulama yanıt verir:

Deleting the database...
Done!
Navigate to /health to see the health status.

Uç noktaya bir istekte bulunın /health . Uygulama iyi durumda olmayan bir yanıt sağlar:

Unhealthy

Ayrı hazırlık ve canlılık yoklamaları

Bazı barındırma senaryolarında, iki uygulama durumunu ayırt etmek için bir çift sistem durumu denetimi kullanılır:

  • Hazır olma, uygulamanın normal çalışıp çalışmadığını ancak istekleri almaya hazır olmadığını gösterir.
  • Canlılık , bir uygulamanın kilitlenip kilitlenmediğini ve yeniden başlatılması gerektiğini belirtir.

Aşağıdaki örneği göz önünde bulundurun: Bir uygulamanın istekleri işlemeye hazır olması için büyük bir yapılandırma dosyasını indirmesi gerekir. İlk indirme başarısız olursa uygulamanın yeniden başlatılmasını istemiyoruz çünkü uygulama dosyayı birkaç kez indirmeyi yeniden deneyebilir. İşlemin canlılığını açıklamak için canlılık araştırması kullanırız, başka hiçbir denetim çalıştırılır. Yapılandırma dosyası indirme başarılı olmadan önce isteklerin uygulamaya gönderilmesini de engellemek istiyoruz. İndirme başarılı olana ve uygulama istekleri almaya hazır olana kadar "hazır değil" durumunu belirtmek için hazır olma araştırması kullanırız.

Örnek uygulama, Barındırılan Hizmette uzun süre çalışan başlangıç görevinin tamamlanmasını raporlamak için bir sistem durumu denetimi içerir. , StartupHostedServiceHealthCheck barındırılan hizmetin uzun süre çalışan görevi tamamlandığında ayarlayabildiği true bir özelliğini StartupTaskCompletedkullanıma sunar (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."));
    }
}

Uzun süre çalışan arka plan görevi, Barındırılan Hizmet (Services/StartupHostedService ) tarafından başlatılır. Görevin sonunda olarak StartupHostedServiceHealthCheck.StartupTaskCompleted ayarlanır 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()
    {
    }
}

Sistem durumu denetimi ile birlikte barındırılan hizmetle AddCheck Startup.ConfigureServices birlikte kaydedilir. Barındırılan hizmetin sistem durumu denetiminde özelliğini ayarlaması gerektiğinden, sistem durumu denetimi de hizmet kapsayıcısında (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>();

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur. Örnek uygulamada sistem durumu denetimi uç noktaları şu konumda oluşturulur:

  • /health/ready hazır olma denetimi için. Hazır olma denetimi, durum denetimlerini etiketle birlikte sistem durumu denetimine ready filtreler.
  • /health/live canlılık kontrolü için. Canlılık denetimi, içinde döndürerek filtrelerini filtreler StartupHostedServiceHealthCheck (daha fazla bilgi için bkz. Sistem durumu denetimlerini filtreleme)false HealthCheckOptions.Predicate

Aşağıdaki örnek kodda:

  • Hazır olma denetimi , 'hazır' etiketiyle tüm kayıtlı denetimleri kullanır.
  • tüm Predicate denetimleri dışlar ve 200-Tamam döndürür.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

Hazırlık/canlılık yapılandırma senaryosunu örnek uygulamayı kullanarak çalıştırmak için, projenin klasöründeki komut kabuğunda aşağıdaki komutu yürütür:

dotnet run --scenario liveness

Tarayıcıda, 15 saniye geçene kadar birkaç kez ziyaret edin /health/ready . Sistem durumu denetimi ilk 15 saniye için raporlar Unhealthy . 15 saniye sonra uç nokta, barındırılan hizmet tarafından uzun süre çalışan görevin tamamlanmasını yansıtan değerini raporlar Healthy.

Bu örnek ayrıca iki saniyelik bir gecikmeyle ilk hazırlık denetimini çalıştıran bir Sistem Durumu Denetimi Yayımcısı (IHealthCheckPublisher uygulama) oluşturur. Daha fazla bilgi için Sistem Durumu Denetimi Yayımcısı bölümüne bakın.

Kubernetes örneği

Ayrı hazır olma ve canlılık denetimleri kullanmak Kubernetes gibi bir ortamda kullanışlıdır. Kubernetes'te, temel alınan veritabanı kullanılabilirliği testi gibi istekleri kabul etmeden önce zaman alan başlangıç çalışmalarını çalıştırmak için bir uygulama gerekebilir. Ayrı denetimler kullanmak, düzenleyicinin uygulamanın çalışıp çalışmadığını ancak henüz hazır olup olmadığını veya uygulamanın başlatılamadığını ayırt etmesini sağlar. Kubernetes'teki hazır olma ve canlılık yoklamaları hakkında daha fazla bilgi için Kubernetes belgelerindeki Canlılık ve Hazırlık Yoklamalarını Yapılandırma bölümüne bakın.

Aşağıdaki örnekte Kubernetes hazır olma yoklaması yapılandırması gösterilmektedir:

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

Özel yanıt yazıcısı ile ölçüm tabanlı yoklama

Örnek uygulama, özel yanıt yazıcısı ile bir bellek durumu denetimi gösterir.

MemoryHealthCheck uygulama belirli bir bellek eşiğinden (örnek uygulamada 1 GB) daha fazla kullanıyorsa düzeyi düşürülmüş durumu bildirir. , HealthCheckResult uygulama için Çöp Toplayıcı (GC) bilgilerini içerir (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));
    }
}

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. sistem durumu denetimini'ne AddCheckgeçirerek etkinleştirmek yerine, MemoryHealthCheck hizmet olarak kaydedilir. Tüm IHealthCheck kayıtlı hizmetler sistem durumu denetimi hizmetleri ve ara yazılım tarafından kullanılabilir. Sistem durumu denetimi hizmetlerini Tekli hizmetler olarak kaydetmenizi öneririz.

Örnek uygulamanın içinde CustomWriterStartup.cs :

services.AddHealthChecks()
    .AddMemoryHealthCheck("memory");

içinde çağrılarak MapHealthChecks Startup.Configurebir sistem durumu denetimi uç noktası oluşturulur. WriteResponse Sistem durumu denetimi yürütürken özel bir JSON yanıtı çıkarmak için özelliğine bir temsilci sağlanırResponseWriter:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
}

Temsilci, WriteResponse öğesini CompositeHealthCheckResult bir JSON nesnesine biçimlendirip sistem durumu denetimi yanıtı için JSON çıkışı verir. Daha fazla bilgi için Çıkışı özelleştirme bölümüne bakın.

Örnek uygulamayı kullanarak ölçüm tabanlı araştırmayı özel yanıt yazıcı çıkışıyla çalıştırmak için, projenin klasöründen bir komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario writer

Not

AspNetCore.Diagnostics.HealthChecks disk depolama ve maksimum değer canlılık denetimleri dahil olmak üzere ölçüm tabanlı sistem durumu denetimi senaryolarını içerir.

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Bağlantı noktasına göre filtrele

MapHealthChecks Sistem durumu denetimi isteklerini belirtilen bağlantı noktasıyla kısıtlamak için bir bağlantı noktası belirten bir URL deseniyle çağrısında RequireHost bulun. Bu yaklaşım genellikle izleme hizmetleri için bir bağlantı noktasını kullanıma sunma amacıyla kapsayıcı ortamında kullanılır.

Örnek uygulama, Ortam Değişkeni Yapılandırma Sağlayıcısı'nı kullanarak bağlantı noktasını yapılandırıyor. Bağlantı noktası dosyasında ayarlanır launchSettings.json ve bir ortam değişkeni aracılığıyla yapılandırma sağlayıcısına geçirilir. Ayrıca sunucuyu yönetim bağlantı noktasındaki istekleri dinleyecek şekilde yapılandırmanız gerekir.

Yönetim bağlantı noktası yapılandırmasını göstermek üzere örnek uygulamayı kullanmak için dosyayı bir Properties klasörde oluşturunlaunchSettings.json.

Örnek uygulamadaki aşağıdaki Properties/launchSettings.json dosya, örnek uygulamanın proje dosyalarına dahil değildir ve el ile oluşturulmalıdır:

{
  "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/"
    }
  }
}

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Startup.ConfigureServiceskaydedin. içinde Startup.Configurearayarak MapHealthChecks bir sistem durumu denetimi uç noktası oluşturun.

Örnek uygulamada, RequireHost içindeki uç noktasında Startup.Configure çağrısı, yapılandırmadan yönetim bağlantı noktasını belirtir:

endpoints.MapHealthChecks("/health")
    .RequireHost($"*:{Configuration["ManagementPort"]}");

Uç noktalar içindeki örnek uygulamada Startup.Configureoluşturulur. Aşağıdaki örnek kodda:

  • Hazır olma denetimi , 'hazır' etiketiyle tüm kayıtlı denetimleri kullanır.
  • tüm Predicate denetimleri dışlar ve 200-Tamam döndürür.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

Not

Yönetim bağlantı noktasını kodda açıkça ayarlayarak örnek uygulamada dosya oluşturmaktan launchSettings.json kaçınabilirsiniz. Program.cs öğesinin oluşturulduğu yerde HostBuilder öğesine bir çağrı ListenAnyIP ekleyin ve uygulamanın yönetim bağlantı noktası uç noktasını sağlayın. içinde Configure ManagementPortStartup.cs, ile RequireHostyönetim bağlantı noktasını belirtin:

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");
});

Örnek uygulamayı kullanarak yönetim bağlantı noktası yapılandırma senaryosunu çalıştırmak için, projenin klasöründen bir komut kabuğunda aşağıdaki komutu yürütebilirsiniz:

dotnet run --scenario port

Sistem durumu denetimi kitaplığı dağıtma

Sistem durumu denetimini kitaplık olarak dağıtmak için:

  1. Arabirimi tek başına sınıf olarak uygulayan IHealthCheck bir sistem durumu denetimi yazın. sınıfı, yapılandırma verilerine erişmek için bağımlılık ekleme (DI), tür etkinleştirme ve adlandırılmış seçenekleri kullanabilir.

    sistem durumu denetimlerinin mantığında CheckHealthAsync:

    • data1 ve data2 yönteminde yoklamanın sistem durumu denetimi mantığını çalıştırmak için kullanılır.
    • AccessViolationException işlenir.

    AccessViolationException bir oluştuğunda, FailureStatus ile birlikte HealthCheckResult döndürülür ve kullanıcıların sistem durumu denetimleri hata durumunu yapılandırmasına izin verir.

    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);
                }
            }
        }
    }
    
  2. Kullanan uygulamanın yönteminde Startup.Configure çağıran parametrelerle bir uzantı yöntemi yazın. Aşağıdaki örnekte, aşağıdaki sistem durumu denetimi yöntemi imzasını varsayın:

    ExampleHealthCheck(string, string, int )
    

    Yukarıdaki imza, sistem durumu denetimi yoklama mantığını işlemek için öğesinin ek veri gerektirdiğini gösterir ExampleHealthCheck . Veriler, durum denetimi bir uzantı yöntemiyle kaydedildiğinde sistem durumu denetimi örneğini oluşturmak için kullanılan temsilciye sağlanır. Aşağıdaki örnekte, çağıran isteğe bağlı belirtir:

    • sistem durumu denetimi adı (name ). example_health_check ise nullkullanılır.
    • sistem durumu denetimidata1 () için dize veri noktası.
    • sistem durumu denetimidata2 () için tamsayı veri noktası. 1 ise nullkullanılır.
    • hata durumu (HealthStatus). Varsayılan değer: null. HealthStatus.Unhealthy hata durumu için bildirilir.null
    • etiketlerini () seçinIEnumerable<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));
        }
    }
    

Sistem Durumu Denetimi Yayımcısı

hizmet kapsayıcısına bir IHealthCheckPublisher eklendiğinde sistem durumu denetimi sistemi, sistem durumu denetimlerinizi düzenli aralıklarla yürütür ve sonuçla birlikte çağrılar PublishAsync gerçekleştirir. Bu, her işlemin sistem durumunu belirlemek için izleme sistemini düzenli aralıklarla çağırmasını bekleyen, anında iletme tabanlı sistem durumu izleme sistemi senaryosunda kullanışlıdır.

Arabirimin IHealthCheckPublisher tek bir yöntemi vardır:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions şunları ayarlamanıza izin verir:

  • Delay: Örnekleri yürütmeden IHealthCheckPublisher önce uygulama başlatıldıktan sonra uygulanan ilk gecikme. Gecikme başlangıçta bir kez uygulanır ve sonraki yinelemeler için geçerli değildir. Varsayılan değer beş saniyedir.
  • Period: Yürütme süresi IHealthCheckPublisher . Varsayılan değer 30 saniyedir.
  • Predicate: (varsayılan) ise Predicate null , sistem durumu denetimi yayımcı hizmeti tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için denetim kümesini filtreleyen bir işlev sağlayın. Koşul her dönem değerlendirilir.
  • Timeout: Tüm IHealthCheckPublisher örnekler için sistem durumu denetimlerini yürütmek için zaman aşımı. Zaman aşımı olmadan yürütmek için kullanın InfiniteTimeSpan . Varsayılan değer 30 saniyedir.

Örnek uygulamada ReadinessPublisher bir IHealthCheckPublisher uygulamadır. Sistem durumu denetimi durumu, her denetim için şu günlük düzeyinde günlüğe kaydedilir:

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;
    }
}

Örnek uygulamanın LivenessProbeStartup örneğinde, hazırlık denetiminin StartupHostedService iki saniyelik başlatma gecikmesi vardır ve denetimi 30 saniyede bir çalıştırır. Uygulamayı etkinleştirmek IHealthCheckPublisher için örnek, bağımlılık ekleme (DI) kapsayıcısında tek bir hizmet olarak kaydederReadinessPublisher:

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>();

Not

AspNetCore.Diagnostics.HealthChecks Application Insights dahil olmak üzere çeşitli sistemler için yayımcılar içerir.

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

MapWhen ile sistem durumu denetimlerini kısıtlama

Durum denetimi uç noktaları için istek işlem hattını koşullu olarak dallara ayırmak için kullanın MapWhen .

Aşağıdaki örnekte, MapWhen uç nokta için bir GET isteği alındığında Sistem Durumu Denetimleri Ara Yazılımını etkinleştirmek üzere istek işlem hattını dallar api/HealthCheck :

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

Daha fazla bilgi için, bkz. ASP.NET Core Ara Yazılımı.

ASP.NET Core, uygulama altyapısı bileşenlerinin sistem durumunu raporlamak için Sistem Durumu Denetimleri Ara Yazılımı ve kitaplıklar sunar.

Sistem durumu denetimleri bir uygulama tarafından HTTP uç noktaları olarak kullanıma sunulur. Sistem durumu denetimi uç noktaları çeşitli gerçek zamanlı izleme senaryoları için yapılandırılabilir:

  • Sistem durumu yoklamaları, bir uygulamanın durumunu denetlemek için kapsayıcı düzenleyicileri ve yük dengeleyiciler tarafından kullanılabilir. Örneğin, kapsayıcı düzenleyici sıralı dağıtımı durdurarak veya kapsayıcıyı yeniden başlatarak başarısız olan sistem durumu denetimine yanıt verebilir. Yük dengeleyici, trafiği hatalı örnekten iyi durumdaki bir örneğe yönlendirerek iyi durumda olmayan bir uygulamaya tepki verebilir.
  • İyi durumda bellek, disk ve diğer fiziksel sunucu kaynaklarının kullanımı izlenebilir.
  • Sistem durumu denetimleri, kullanılabilirliği ve normal çalışma durumunu onaylamak için bir uygulamanın veritabanları ve dış hizmet uç noktaları gibi bağımlılıklarını test edebilir.

Sistem durumu denetimleri genellikle bir uygulamanın durumunu denetlemek için bir dış izleme hizmeti veya kapsayıcı düzenleyici ile birlikte kullanılır. Bir uygulamaya sistem durumu denetimleri eklemeden önce hangi izleme sisteminin kullanılacağına karar verin. İzleme sistemi, hangi tür sistem durumu denetimlerinin oluşturulacağını ve uç noktalarının nasıl yapılandıracağını belirler.

Temel sistem durumu yoklaması

Birçok uygulama için, uygulamanın istekleri işlemek için kullanılabilirliğini (canlılık) bildiren temel bir sistem durumu yoklaması yapılandırması, uygulamanın durumunu keşfetmek için yeterlidir.

Temel yapılandırma, sistem durumu denetimi hizmetlerini kaydeder ve sistem durumu yanıtıyla BIR URL uç noktasında yanıt vermek için Sistem Durumu Denetimleri Ara Yazılımını çağırır. Varsayılan olarak, belirli bir bağımlılığı veya alt sistemi test etmek için belirli bir sistem durumu denetimi kaydedilmez. Uygulama, sistem durumu uç noktası URL'sinde yanıt verebiliyorsa iyi durumda kabul edilir. Varsayılan yanıt yazarı istemciye düz metin yanıtı olarak yazar HealthStatus . HealthStatus, veya HealthStatus.UnhealthyşeklindedirHealthStatus.HealthyHealthStatus.Degraded.

ile sistem durumu denetimi hizmetlerini AddHealthChecks ile Program.cskaydedin. çağrısı MapHealthChecksyaparak bir sistem durumu denetimi uç noktası oluşturun.

Aşağıdaki örnek konumunda /healthzbir sistem durumu denetimi uç noktası oluşturur:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker karşılaştırması hakkında daha fazla bilgi edininHEALTHCHECK

Docker , temel sistem durumu denetimi yapılandırmasını kullanan bir uygulamanın durumunu denetlemek için kullanılabilecek yerleşik HEALTHCHECK bir yönerge sunar:

HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit

Yukarıdaki örnek, konumundaki /healthzsistem durumu denetimi uç noktasına http isteğinde bulunmak için kullanırcurl. curl .NET Linux kapsayıcı görüntülerine dahil değildir, ancak gerekli paketi Dockerfile dosyasına yükleyerek eklenebilir. Alpine Linux tabanlı görüntüleri kullanan kapsayıcılar, yerine dahil wget edilen öğesini curlkullanabilir.

Sistem durumu denetimleri oluşturma

Sistem durumu denetimleri arabirimi uygulanarak IHealthCheck oluşturulur. yöntemi, CheckHealthAsync sistem durumunu , Degradedveya Unhealthyolarak Healthygösteren bir HealthCheckResult döndürür. Sonuç, yapılandırılabilir durum koduyla düz metin yanıtı olarak yazılır. Yapılandırma, Sistem durumu denetimi seçenekleri bölümünde açıklanmıştır. HealthCheckResult isteğe bağlı anahtar-değer çiftleri de döndürebilir.

Aşağıdaki örnekte sistem durumu denetiminin düzeni gösterilmektedir:

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."));
    }
}

Sistem durumu denetiminin mantığı yöntemine CheckHealthAsync yerleştirilir. Yukarıdaki örnek, isHealthytrueolarak bir kukla değişkeni ayarlar. değeri isHealthy olarak ayarlanırsafalseHealthCheckRegistration.FailureStatus, durum döndürülür.

Denetim sırasında bir özel durum oluşturursaCheckHealthAsync, değerine ayarlanmış FailureStatusyeni bir döndürülür HealthReportEntry HealthReportEntry.Status. Bu durum tarafından AddCheck tanımlanır (sistem durumu denetimi hizmetlerini kaydetme bölümüne bakın) ve denetim hatasına neden olan iç özel durumu içerir. Description, özel durumun iletisine ayarlanır.

Sistem durumu denetimi hizmetlerini kaydetme

Sistem durumu denetimi hizmetini kaydetmek için öğesini Program.csarayınAddCheck:

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>("Sample");

AddCheck Aşağıdaki örnekte gösterilen aşırı yükleme, sistem durumu denetimi hata bildirdiğinde hata durumunu (HealthStatus) bildirecek şekilde ayarlar. Hata durumu (varsayılan) HealthStatus.Unhealthy olarak ayarlanırsa null raporlanır. Bu aşırı yükleme, kitaplık yazarları için yararlı bir senaryodur ve sistem durumu denetimi uygulaması ayarı kabul ederse sistem durumu denetimi hatası oluştuğunda kitaplık tarafından belirtilen hata durumunun uygulama tarafından zorlandığı bir senaryodur.

Etiketler , sistem durumu denetimlerini filtrelemek için kullanılabilir. Etiketler, Sistem durumu denetimlerini filtrele bölümünde açıklanmıştır.

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" });

AddCheck bir lambda işlevini de yürütebilir. Aşağıdaki örnekte, sistem durumu denetimi her zaman iyi durumda bir sonuç döndürür:

builder.Services.AddHealthChecks()
    .AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));

Bir sistem durumu denetimi uygulamasına bağımsız değişkenleri geçirmek için çağrısı AddTypeActivatedCheck . Aşağıdaki örnekte, tür etkinleştirilmiş sistem durumu denetimi, oluşturucusunda bir tamsayı ve dize kabul eder:

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."));
    }
}

Önceki sistem durumu denetimini kaydetmek için, bağımsız değişken olarak geçirilen tamsayı ve dizeyle çağrısı AddTypeActivatedCheck yapın:

builder.Services.AddHealthChecks()
    .AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" },
        args: new object[] { 1, "Arg" });

Sistem Durumu Denetimleri Yönlendirmeyi Kullanma

içinde uç nokta URL'si Program.csveya göreli yolu ile uç nokta oluşturucusunu çağırın MapHealthChecks :

app.MapHealthChecks("/healthz");

Konağı gerektir

Sistem durumu denetimi uç noktası için bir veya daha fazla izin verilen konak belirtmek için çağrısı RequireHost yapın. Konaklar punycode yerine Unicode olmalıdır ve bir bağlantı noktası içerebilir. Koleksiyon sağlanmazsa, herhangi bir konak kabul edilir:

app.MapHealthChecks("/healthz")
    .RequireHost("www.contoso.com:5001");

Sistem durumu denetimi uç noktasını yalnızca belirli bir bağlantı noktasında yanıt verecek şekilde kısıtlamak için RequireHostçağrısında bir bağlantı noktası belirtin. Bu yaklaşım genellikle izleme hizmetleri için bir bağlantı noktasını kullanıma sunma amacıyla kapsayıcı ortamında kullanılır:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001");

Uyarı

ve RequireHostgibi HttpRequest.Host Konak üst bilgisini kullanan API, istemciler tarafından olası kimlik sahtekarlığına tabidir.

Konak ve bağlantı noktası kimlik sahtekarlığına engel olmak için aşağıdaki yaklaşımlardan birini kullanın:

Yetkisiz istemcilerin bağlantı noktası sahtekarlığına uğramasını önlemek için öğesini çağırın RequireAuthorization:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001")
    .RequireAuthorization();

Daha fazla bilgi için bkz . RequireHost ile yollarda konak eşleştirme.

Yetkilendirme gerektir

Durum denetimi isteği uç noktasında Yetkilendirme Ara Yazılımını çalıştırmak için çağırın RequireAuthorization . Aşırı RequireAuthorization yükleme bir veya daha fazla yetkilendirme ilkesi kabul eder. İlke sağlanmazsa, varsayılan yetkilendirme ilkesi kullanılır:

app.MapHealthChecks("/healthz")
    .RequireAuthorization();

Kaynaklar Arası İstekleri (CORS) etkinleştirme

Sistem durumu denetimlerini tarayıcıda el ile çalıştırmak yaygın bir senaryo olmasa da, CORS Ara Yazılımı sistem durumu denetimleri uç noktalarına çağrılarak RequireCors etkinleştirilebilir. Aşırı RequireCors yükleme bir CORS ilke oluşturucusu temsilcisini (CorsPolicyBuilder) veya bir ilke adını kabul eder. Daha fazla bilgi için bkz . ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) Etkinleştirme.

Sistem durumu denetimi seçenekleri

HealthCheckOptions sistem durumu denetimi davranışını özelleştirme fırsatı sağlar:

Sistem durumu denetimlerini filtrele

Varsayılan olarak, Sistem Durumu Denetimleri Ara Yazılımı tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için seçeneğine Predicate boole döndüren bir işlev sağlayın.

Aşağıdaki örnek, sistem durumu denetimlerini yalnızca çalıştır ile etiketlenenlerin çalışması için sample filtreler:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});

HTTP durum kodunu özelleştirme

Durum durumunu HTTP durum kodlarıyla eşlemeyi özelleştirmek için kullanın ResultStatusCodes . Aşağıdaki StatusCodes atamalar ara yazılım tarafından kullanılan varsayılan değerlerdir. Durum kodu değerlerini gereksinimlerinizi karşılayacak şekilde değiştirin:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Önbellek üst bilgilerini gizleme

AllowCachingResponses Durum Denetimleri Ara Yazılımının yanıt önbelleğe almayı önlemek için yoklama yanıtına HTTP üst bilgileri ekleyip eklemediğini denetler. Değer (varsayılan) ise false , ara yazılım yanıt önbelleğe almayı önlemek için , Expiresve Pragma üst bilgilerini ayarlar veya geçersiz kılarCache-Control. değeri ise trueara yazılım yanıtın önbellek üst bilgilerini değiştirmez:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    AllowCachingResponses = true
});

Çıktıyı özelleştirme

Sistem durumu denetimleri raporunun çıkışını özelleştirmek için, özelliğini yanıtı yazan bir temsilci olarak ayarlayın HealthCheckOptions.ResponseWriter :

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResponseWriter = WriteResponse
});

Varsayılan temsilci, dize değeriyle en düşük düz metin yanıtını HealthReport.Statusyazar. Aşağıdaki özel temsilci kullanarak System.Text.Jsonözel bir JSON yanıtı verir:

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()));
}

Sistem durumu denetimleri API'si, karmaşık JSON dönüş biçimleri için yerleşik destek sağlamaz çünkü biçim, seçtiğiniz izleme sistemine özgüdür. Yukarıdaki örneklerde verilen yanıtı gerektiği gibi özelleştirin. ile System.Text.JsonJSON serileştirmesi hakkında daha fazla bilgi için bkz . .NET'te JSON'ı seri hale getirme ve seri durumdan çıkarma.

Veritabanı yoklaması

Sistem durumu denetimi, veritabanının normal yanıt verdiğini belirtmek için boole testi olarak çalıştırılacak bir veritabanı sorgusu belirtebilir.

AspNetCore.Diagnostics.HealthChecks, ASP.NET Core uygulamaları için bir sistem durumu denetimi kitaplığı, SQL Server veritabanında çalışan bir sistem durumu denetimi içerir. AspNetCore.Diagnostics.HealthChecks veritabanı bağlantısının iyi durumda olduğunu onaylamak için veritabanına karşı bir SELECT 1 sorgu yürütür.

Uyarı

Bir sorguyla veritabanı bağlantısını denetlerken, hızlı bir şekilde döndüren bir sorgu seçin. Sorgu yaklaşımı veritabanını aşırı yükleme ve performansını düşürme riskini çalıştırır. Çoğu durumda test sorgusu çalıştırmak gerekli değildir. Yalnızca veritabanıyla başarılı bir bağlantı oluşturmak yeterlidir. Sorgu çalıştırmayı gerekli bulursanız, gibi SELECT 1basit bir SELECT sorgusu seçin.

Bu SQL Server sistem durumu denetimini kullanmak için NuGet paketine AspNetCore.HealthChecks.SqlServer bir paket başvurusu ekleyin. Aşağıdaki örnek SQL Server sistem durumu denetimini kaydeder:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection"));

Not

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Entity Framework Core DbContext araştırması

Denetim, DbContext uygulamanın için EF CoreDbContextyapılandırılan veritabanıyla iletişim kurabildiğini onaylar. Denetim DbContext , aşağıdaki uygulamalarda desteklenir:

AddDbContextCheck için bir sistem durumu denetimi DbContextkaydeder. DbContext yöntemine olarak TContextsağlanır. Hata durumunu, etiketleri ve özel test sorgusunu yapılandırmak için bir aşırı yükleme kullanılabilir.

Varsayılan olarak:

  • 'DbContextHealthChecknin CanConnectAsync yöntemini çağırırEF Core. Yöntem aşırı yüklemelerini kullanarak AddDbContextCheck sistem durumu denetlenirken çalıştırılacak işlemi özelleştirebilirsiniz.
  • Sistem durumu denetiminin adı türün TContext adıdır.

Aşağıdaki örnek ve DbContext ilişkili DbContextHealthCheckbir kaydeder:

builder.Services.AddDbContext<SampleDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddHealthChecks()
    .AddDbContextCheck<SampleDbContext>();

Ayrı hazırlık ve canlılık yoklamaları

Bazı barındırma senaryolarında, iki uygulama durumunu ayırt etmek için bir çift sistem durumu denetimi kullanılır:

  • Hazır olma, uygulamanın normal çalışıp çalışmadığını ancak istekleri almaya hazır olmadığını gösterir.
  • Canlılık , bir uygulamanın kilitlenip kilitlenmediğini ve yeniden başlatılması gerektiğini belirtir.

Aşağıdaki örneği göz önünde bulundurun: Bir uygulamanın istekleri işlemeye hazır olması için büyük bir yapılandırma dosyasını indirmesi gerekir. İlk indirme başarısız olursa uygulamanın yeniden başlatılmasını istemiyoruz çünkü uygulama dosyayı birkaç kez indirmeyi yeniden deneyebilir. İşlemin canlılığını açıklamak için canlılık araştırması kullanırız, başka hiçbir denetim çalıştırılır. Yapılandırma dosyası indirme başarılı olmadan önce isteklerin uygulamaya gönderilmesini de engellemek istiyoruz. İndirme başarılı olana ve uygulama istekleri almaya hazır olana kadar "hazır değil" durumunu belirtmek için hazır olma araştırması kullanırız.

Aşağıdaki arka plan görevi, yaklaşık 15 saniye süren bir başlangıç işleminin benzetimini yapar. İşlem tamamlandıktan sonra görev özelliği true olarak ayarlar StartupHealthCheck.StartupCompleted :

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;
    }
}

uzun StartupHealthCheck süre çalışan başlangıç görevinin tamamlandığını bildirir ve arka plan hizmeti tarafından ayarlanan özelliği kullanıma sunar StartupCompleted :

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."));
    }
}

Sistem durumu denetimi ile birlikte barındırılan hizmetle AddCheck Program.cs birlikte kaydedilir. Barındırılan hizmetin sistem durumu denetiminde özelliğini ayarlaması gerektiğinden, sistem durumu denetimi de hizmet kapsayıcısında tekil olarak kaydedilir:

builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();

builder.Services.AddHealthChecks()
    .AddCheck<StartupHealthCheck>(
        "Startup",
        tags: new[] { "ready" });

İki farklı sistem durumu denetimi uç noktası oluşturmak için iki kez çağrısında MapHealthChecks bulunur:

app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("ready")
});

app.MapHealthChecks("/healthz/live", new HealthCheckOptions
{
    Predicate = _ => false
});

Yukarıdaki örnek aşağıdaki sistem durumu denetimi uç noktalarını oluşturur:

  • /healthz/ready hazır olma denetimi için. Hazır olma denetimi, ile readyetiketlenenlere sistem durumu denetimlerini filtreler.
  • /healthz/live canlılık kontrolü için. Canlılık denetimi, temsilciyi geri döndürerek false HealthCheckOptions.Predicate tüm sistem durumu denetimlerini filtreler. Sistem durumu denetimlerini filtreleme hakkında daha fazla bilgi için bu makaledeki Sistem durumu denetimlerini filtreleme bölümüne bakın.

Başlangıç görevi tamamlanmadan önce uç /healthz/ready nokta bir Unhealthy durum bildirir. Başlangıç görevi tamamlandıktan sonra bu uç nokta bir Healthy durum bildirir. Uç /healthz/live nokta tüm denetimleri dışlar ve tüm çağrılar için bir Healthy durum bildirir.

Kubernetes örneği

Ayrı hazır olma ve canlılık denetimleri kullanmak Kubernetes gibi bir ortamda kullanışlıdır. Kubernetes'te, temel alınan veritabanı kullanılabilirliği testi gibi istekleri kabul etmeden önce zaman alan başlangıç çalışmalarını çalıştırmak için bir uygulama gerekebilir. Ayrı denetimler kullanmak, düzenleyicinin uygulamanın çalışıp çalışmadığını ancak henüz hazır olup olmadığını veya uygulamanın başlatılamadığını ayırt etmesini sağlar. Kubernetes'teki hazır olma ve canlılık yoklamaları hakkında daha fazla bilgi için Kubernetes belgelerindeki Canlılık ve Hazırlık Yoklamalarını Yapılandırma bölümüne bakın.

Aşağıdaki örnekte Kubernetes hazır olma yoklaması yapılandırması gösterilmektedir:

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

Sistem durumu denetimi kitaplığı dağıtma

Sistem durumu denetimini kitaplık olarak dağıtmak için:

  1. Arabirimi tek başına sınıf olarak uygulayan IHealthCheck bir sistem durumu denetimi yazın. sınıfı, yapılandırma verilerine erişmek için bağımlılık ekleme (DI), tür etkinleştirme ve adlandırılmış seçenekleri kullanabilir.

  2. Kullanan uygulamanın yönteminde Program.cs çağıran parametrelerle bir uzantı yöntemi yazın. Ve'yi oluşturucu parametreleri olarak kabul arg1 arg2 eden aşağıdaki örnek sistem durumu denetimini göz önünde bulundurun:

    public SampleHealthCheckWithArgs(int arg1, string arg2)
        => (_arg1, _arg2) = (arg1, arg2);
    

    Yukarıdaki imza, sistem durumu denetiminin sistem durumu denetimi yoklama mantığını işlemek için özel veriler gerektirdiğini gösterir. Veriler, durum denetimi bir uzantı yöntemiyle kaydedildiğinde sistem durumu denetimi örneğini oluşturmak için kullanılan temsilciye sağlanır. Aşağıdaki örnekte, çağıran şunları belirtir:

    • arg1: Sistem durumu denetimi için bir tamsayı veri noktası.
    • arg2: Sistem durumu denetimi için bir dize bağımsız değişkeni.
    • name: İsteğe bağlı bir sistem durumu denetimi adı. ise null, varsayılan bir değer kullanılır.
    • failureStatus: Hata durumu için bildirilen isteğe bağlı HealthStatusbir . HealthStatus.Unhealthy ise nullkullanılır.
    • tags: İsteğe bağlı IEnumerable<string> bir etiket koleksiyonu.
    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));
        }
    }
    

Sistem Durumu Denetimi Yayımcısı

hizmet kapsayıcısına bir IHealthCheckPublisher eklendiğinde sistem durumu denetimi sistemi, sistem durumu denetimlerinizi düzenli aralıklarla yürütür ve sonuçla birlikte çağrılar PublishAsync gerçekleştirir. Bu işlem, her işlemin sistem durumunu belirlemek için izleme sistemini düzenli aralıklarla çağırmasını bekleyen, anında iletme tabanlı sistem durumu izleme sistemi senaryosunda kullanışlıdır.

HealthCheckPublisherOptions şunları ayarlamanıza izin verir:

  • Delay: Örnekleri yürütmeden IHealthCheckPublisher önce uygulama başlatıldıktan sonra uygulanan ilk gecikme. Gecikme başlangıçta bir kez uygulanır ve sonraki yinelemeler için geçerli değildir. Varsayılan değer beş saniyedir.
  • Period: Yürütme süresi IHealthCheckPublisher . Varsayılan değer 30 saniyedir.
  • Predicate: (varsayılan) ise Predicate null , sistem durumu denetimi yayımcı hizmeti tüm kayıtlı sistem durumu denetimlerini çalıştırır. Sistem durumu denetimlerinin bir alt kümesini çalıştırmak için denetim kümesini filtreleyen bir işlev sağlayın. Koşul her dönem değerlendirilir.
  • Timeout: Tüm IHealthCheckPublisher örnekler için sistem durumu denetimlerini yürütmek için zaman aşımı. Zaman aşımı olmadan yürütmek için kullanın InfiniteTimeSpan . Varsayılan değer 30 saniyedir.

Aşağıdaki örnekte sistem durumu yayımcısının düzeni gösterilmektedir:

public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
    public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            // ...
        }
        else
        {
            // ...
        }

        return Task.CompletedTask;
    }
}

sınıfı, HealthCheckPublisherOptions sistem durumu denetimi yayımcısının davranışını yapılandırmaya yönelik özellikler sağlar.

Aşağıdaki örnek, bir sistem durumu denetimi yayımcısını tekil olarak kaydeder ve yapılandırılır HealthCheckPublisherOptions:

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});

builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();

Not

AspNetCore.Diagnostics.HealthChecks Application Insights dahil olmak üzere çeşitli sistemler için yayımcılar içerir.

AspNetCore.Diagnostics.HealthChecks microsoft tarafından korunmuyor veya desteklenmiyor.

Bağımlılık Ekleme ve Sistem Durumu Denetimleri

Bir Sistem Durumu Denetimi sınıfı içindeki belirli Type bir örneğini kullanmak için bağımlılık ekleme özelliğini kullanmak mümkündür. Bağımlılık ekleme, sistem durumu denetimine seçenekler veya genel yapılandırma eklemek için yararlı olabilir. Bağımlılık eklemenin kullanılması, Sistem Durumu Denetimlerini yapılandırmak için yaygın bir senaryo değildir. Genellikle, her Sistem Durumu Denetimi gerçek teste oldukça özeldir ve uzantı yöntemleri kullanılarak IHealthChecksBuilder yapılandırılır.

Aşağıdaki örnekte, bağımlılık ekleme yoluyla bir yapılandırma nesnesi alan örnek bir Sistem Durumu Denetimi gösterilmektedir:

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 ve Sistem Durumu denetiminin hizmet kapsayıcısına eklenmesi gerekir:

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 ile MapHealthChecks karşılaştırması

Sistem durumu denetimlerini arayanlar için erişilebilir hale getirmenin iki yolu vardır:

  • UseHealthChecks ara yazılım işlem hattında sistem durumu denetimleri isteklerini işlemek için ara yazılımı kaydeder.
  • MapHealthChecks sistem durumu denetimleri uç noktasını kaydeder. Uç nokta, uygulamadaki diğer uç noktalarla birlikte eşleştirilir ve yürütülür.

Over UseHealthChecks kullanmanın MapHealthChecks avantajı, yetkilendirme gibi uç nokta kullanan ara yazılımları kullanabilmek ve eşleşen ilke üzerinde daha ayrıntılı denetime sahip olmaktır. over MapHealthChecks kullanmanın UseHealthChecks birincil avantajı, sistem durumu denetimlerinin ara yazılım işlem hattında tam olarak nerede çalıştığını denetlemektir.

UseHealthChecks:

  • bir istek sistem durumu denetimi uç noktasıyla eşleştiğinde işlem hattını sonlandırır. Kısa devre, günlüğe kaydetme ve diğer ara yazılım gibi gereksiz işleri önlediğinden genellikle tercih edilir.
  • Öncelikle işlem hattında sistem durumu denetimi ara yazılımını yapılandırmak için kullanılır.
  • veya boş PathStringolan bir bağlantı noktasındaki herhangi bir null yolu eşleştirebilir. Belirtilen bağlantı noktasına yapılan isteklerde sistem durumu denetimi gerçekleştirmeye izin verir.
  • Kaynak kod

MapHealthChecks Sağ -lar:

  • Sistem durumu denetimleri için belirli yolları veya uç noktaları eşleme.
  • Sistem durumu denetimi uç noktasının erişilebilir olduğu URL'nin veya yolun özelleştirilmesi.
  • Farklı yollar veya yapılandırmalarla birden çok sistem durumu denetimi uç noktasını eşleme. Birden çok uç nokta desteği:
    • Farklı sistem durumu denetimleri veya bileşenleri için ayrı uç noktaları etkinleştirir.
    • Uygulamanın sistem durumunun farklı yönlerini ayırt etmek veya sistem durumu denetimlerinin alt kümelerine belirli yapılandırmalar uygulamak için kullanılır.
  • Kaynak kod

Ek kaynaklar

Not

Bu makale, kısmen yapay zeka yardımıyla oluşturulmuştur. Yayımlanmadan önce içerik bir yazar tarafından gözden geçirilmiş ve gereken şekilde düzeltilmiştir. Microsoft Learn'de yapay zeka tarafından oluşturulan içerik kullanma ilkelerimize bakın.