.NET'te günlük örnekleme

.NET, önemli bilgileri kaybetmeden uygulamanızın yaydığı günlüklerin hacmini denetlemenize olanak sağlayan günlük örnekleme özellikleri sağlar. Aşağıdaki örnekleme stratejileri kullanılabilir:

  • İzleme tabanlı örnekleme: Geçerli izlemenin örnekleme kararını temel alan örnek günlükler.
  • Rastgele olasılık örneklemesi: Yapılandırılmış olasılık kurallarına göre örnek günlükler.
  • Özel örnekleme: Kendi özel örnekleme stratejinizi uygulayın. Daha fazla bilgi için bkz. Özel örnekleme uygulama.

Uyarı

Aynı anda yalnızca bir örnekleyici kullanılabilir. Birden çok örnekleyici kaydederseniz, sonuncusu kullanılır.

Günlük örneklemesi, uygulamanız tarafından hangi günlüklerin yayıldığı üzerinde daha ayrıntılı denetim sağlayarak filtreleme özelliklerini genişletir. Yalnızca günlükleri etkinleştirmek veya devre dışı bırakmak yerine örneklemeyi bunların yalnızca bir bölümünü yayacak şekilde yapılandırabilirsiniz.

Örneğin, filtreleme genellikle 0 (hiçbir günlük göndermeme) veya 1 (tüm günlükleri gönderme) gibi olasılıkları kullanırken, örnekleme 0.1 gibi veya 0.25 gibi aradaki herhangi bir değeri seçmenize olanak tanır, örneğin %10 günlük göndermek veya %25 günlük göndermek gibi.

Get started

Başlamak için Microsoft.Extensions.Telemetry NuGet paketini yükleyin📦:

dotnet add package Microsoft.Extensions.Telemetry

Daha fazla bilgi için bkz. dotnet add package veya Manage package dependencies in .NET applications.

İzleme tabanlı örneklemeyi yapılandırma

İzleme tabanlı örnekleme, günlüklerin temel alınan Activityile tutarlı bir şekilde örneklenmiş olmasını sağlar. bu, izlemeler ve günlükler arasındaki bağıntıyı korumak istediğinizde kullanışlıdır. İzleme örneklemeyi etkinleştirebilir ( kılavuzda açıklandığı gibi) ve ardından izleme tabanlı günlük örneklemesini uygun şekilde yapılandırabilirsiniz:

builder.Logging.AddTraceBasedSampler();

İzleme tabanlı örnekleme etkinleştirildiğinde, günlükler yalnızca temel alınan Activity örneklenmişse gönderilir. Örnekleme kararı, mevcut Recorded değerinden gelir.

Rastgele olasılığa dayalı örneklemeyi yapılandırma

Rastgele olasılık örneklemesi, günlükleri yapılandırılmış olasılık kurallarına göre örneklemenize olanak tanır. Aşağıdakilere özgü kurallar tanımlayabilirsiniz:

  • Günlük kategorisi
  • Kayıt seviyesi
  • Olay Kimliği

Rastgele olasılıksal örneklemeyi kurallarıyla yapılandırmanın birkaç yolu vardır:

Dosya tabanlı yapılandırma

appsettings.jsonbir yapılandırma bölümü oluşturun, örneğin:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  },

  "RandomProbabilisticSampler": {
    "Rules": [
      {
        "CategoryName": "Microsoft.AspNetCore.*",
        "Probability": 0.25,
        "LogLevel": "Information"
      },
      {
        "CategoryName": "System.*",
        "Probability": 0.1
      },
      {
        "EventId": 1001,
        "Probability": 0.05
      }
    ]
  }
}

Önceki yapılandırma:

  • System. ile başlayan kategorilerden tüm seviyelerdeki günlüklerin %10'unu örnekler.
  • ile başlayan Microsoft.AspNetCore.LogLevel.Informationkategorilerden 25% günlük örneği.
  • Tüm kategori ve düzeylerden olay kimliği 1001 olan günlüklerin %5'ini örnekler.
  • %100 diğer tüm günlüklerden örnekler.

Önemli

değeri, Probability 0 ile 1 aralığındaki değerlerle olasılığı temsil eder. Örneğin, 0,25, günlüklerin %25'inin örneklemesi alınacağı anlamına gelir. 0, hiçbir günlük örneği alınmayacak, 1 ise tüm günlüklerin örneklanacağı anlamına gelir. 0 ve 1 içeren bu durumlar, belirli bir kural için tüm günlükleri etkin bir şekilde devre dışı bırakmak veya etkinleştirmek için kullanılabilir. Olasılık 0'dan küçük veya 1'den büyük olamaz ve bu uygulamada oluşursa bir özel durum oluşturulur.

Örnekleyiciyi yapılandırmayla kaydetmek için aşağıdaki kodu kullanın:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Çalışan bir uygulamada örnekleme kurallarını değiştirme

Rastgele olasılık örneklemesi, arabirim aracılığıyla IOptionsMonitor<TOptions> çalışma zamanı yapılandırma güncelleştirmelerini destekler. Dosya Yapılandırma Sağlayıcısı gibi yeniden yüklemeleri destekleyen bir yapılandırma sağlayıcısı kullanıyorsanız, uygulamayı yeniden başlatmadan örnekleme kurallarını çalışma zamanında güncelleştirebilirsiniz.

Örneğin, uygulamanızı aşağıdaki appsettings.jsonile başlatabilirsiniz ve bu da etkili bir şekilde no-opişlevi görür:

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 1
        }
      ]
    }
  }
}

Uygulama çalışırken ,appsettings.json aşağıdaki yapılandırmayla güncelleştirebilirsiniz:

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 0.01,
          "LogLevel": "Information"
        }
      ]
    }
  }
}

Yeni kurallar, örneğin önceki yapılandırma ile otomatik olarak uygulanır; bu durumda, günlüklerin %1'i LogLevel.Information ile örneklenir.

Örnekleme kuralları nasıl uygulanır?

Algoritma , günlük filtrelemeye çok benzer, ancak bazı farklılıklar vardır.

Her bir günlük kaydında günlük örnekleme kurallarının değerlendirilmesi yapılır, ancak önbelleğe alma gibi performans iyileştirmeleri de bulunmaktadır. Aşağıdaki algoritma, belirli bir kategoriye ilişkin her günlük kaydı için kullanılır:

  • Logger'ın günlük düzeyine eşit veya ondan yüksek olan kuralları LogLevel seçin.
  • Tanımlanmayan veya tanımlanan ve günlük olay kimliğine eşit olan kuralları EventId seçin.
  • En uzun eşleşen kategori ön eki olan kuralları seçin. Eşleşme bulunamazsa bir kategori belirtmeyen tüm kuralları seçin.
  • Birden çok kural seçildiyse, sonuncusunu alın.
  • Hiçbir kural seçilmezse örnekleme uygulanmaz, örneğin günlük kaydı her zamanki gibi yayılır.

Satır içi kod yapılandırması

builder.Logging.AddRandomProbabilisticSampler(options =>
{
    options.Rules.Add(
        new RandomProbabilisticSamplerFilterRule(
            probability: 0.05d,
            eventId : 1001));
});

Önceki yapılandırma:

  • Tüm kategori ve düzeylerden olay kimliği 1001 olan günlüklerin %5'ini örnekler.
  • %100 diğer tüm günlüklerden örnekler.

Basit olasılık yapılandırması

Temel senaryolar için, belirtilen düzeydeki veya altındaki tüm günlüklere uygulanan tek bir olasılık değeri yapılandırabilirsiniz:

builder.Logging.AddRandomProbabilisticSampler(0.01, LogLevel.Information);
builder.Logging.AddRandomProbabilisticSampler(0.1, LogLevel.Warning);

Yukarıdaki kod, %10 Warning loglarını ve Information (ve altı) loglarının %1'ini örnekleyecek örnekleyiciyi kaydeder. Yapılandırma için Information kuralı olmasaydı, yüzde 10 Warning logu ve aşağıdaki tüm düzeyler, Information dâhil olmak üzere, örneklenirdi.

Özel örnekleme uygulamak

Soyut sınıftan LoggingSampler türeterek ve soyut üyelerini geçersiz kılarak özel bir örnekleme stratejisi oluşturabilirsiniz. Bu, örnekleme davranışını özel gereksinimlerinize göre uyarlamanıza olanak tanır. Örneğin, özel bir örnekleyici şunları yapabilir:

  • Belirli anahtar/değer çiftlerinin günlük durumundaki varlığına ve değerine bağlı olarak örnekleme kararları alın.
  • Yalnızca önceden tanımlanmış bir zaman aralığındaki günlük sayısı belirli bir eşiğin altında kalırsa günlükleri yayma gibi hız sınırlama mantığı uygulayın.

Özel örnekleyici uygulamak için şu adımları izleyin:

  1. öğesinden LoggingSamplerdevralan bir sınıf oluşturun.
  2. LoggingSampler.ShouldSample Özel örnekleme mantığınızı tanımlamak için yöntemini geçersiz kılın.
  3. Uzantı yöntemini kullanarak özel örnekleyicinizi günlüğe kaydetme işlem hattına AddSampler kaydedin.

Filtrelenmemiş her günlük kaydı için LoggingSampler.ShouldSample yöntemi tam olarak bir kez çağrılır. Dönüş değeri, günlük kaydının yayımlanıp yayımlanmayacağını belirler.

Performansla ilgili dikkat edilmesi gerekenler

Günlük örnekleme, depolama maliyetlerini azaltmak için tasarlanmıştır ve bunun karşılığında CPU kullanımının biraz artmasıyla sonuçlanır. Uygulamanız depolaması pahalı olan yüksek hacimli günlükler oluşturuyorsa örnekleme bu hacmi azaltmaya yardımcı olabilir. Uygun şekilde yapılandırıldığında, örnekleme olayları tanılamak için kritik olan bilgileri kaybetmeden depolama maliyetlerini düşürebilir.

Yerleşik örnekleme için bkz . Karşılaştırmalar.

Örneklemenin ne zaman kullanılacağına ilişkin günlük düzeyi kılavuzu

Kayıt seviyesi Tavsiye
Trace Normalde bu günlükleri üretimde devre dışı bırakdığınızdan örnekleme uygulamayın
Debug Normalde bu günlükleri üretimde devre dışı bırakdığınızdan örnekleme uygulamayın
Information Örnekleme uygula
Warning Örneklemeyi uygulamayı göz önünde bulundurun
Error Örnekleme uygulama yapma
Critical Örnekleme uygulama yapma

En iyi yöntemler

  • Daha yüksek örnekleme oranlarıyla başlayın ve gerektiğinde bunları aşağı doğru ayarlayın.
  • Belirli bileşenleri hedeflemek için kategori tabanlı kuralları kullanın.
  • Dağıtılmış izleme kullanıyorsanız izleme tabanlı örnekleme uygulamayı göz önünde bulundurun.
  • Örnekleme kurallarınızın etkinliğini toplu olarak izleyin.
  • Uygulamanız için doğru dengeyi bulun; çok düşük örnekleme oranı gözlemlenebilirliği azaltabilirken, çok yüksek bir oran maliyetleri artırabilir.

Ayrıca bakınız

  • Last updated on