Loggprovtagning i .NET

.NET tillhandahåller loggsamplingsfunktioner som gör att du kan styra mängden loggar som programmet genererar utan att förlora viktig information. Följande samplingsstrategier är tillgängliga:

  • Spårningsbaserad sampling: Exempelloggar baserat på samplingsbeslutet för den aktuella spårningen.
  • Slumpmässig probabilistisk sampling: Exempelloggar baserat på konfigurerade sannolikhetsregler.
  • Anpassad sampling: Implementera en egen anpassad samplingsstrategi. Mer information finns i Implementera anpassad sampling.

Anmärkning

Endast en provtagare kan användas i taget. Om du registrerar flera provtagare används den sista.

Loggsampling utökar filtreringsfunktionerna genom att ge dig mer detaljerad kontroll över vilka loggar som genereras av ditt program. I stället för att bara aktivera eller inaktivera loggar kan du konfigurera sampling för att endast generera en bråkdel av dem.

Om filtrering till exempel vanligtvis använder sannolikheter som 0 (genererar inga loggar) eller 1 (genererar alla loggar), kan du med sampling välja valfritt värde däremellan, till exempel 0.1 att generera 10% loggar eller 0.25 att generera 25%.

Get started

Kom igång genom att 📦 installera NuGet-paketet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

Mer information finns i dotnet add package eller på Hantera paketsberoenden i .NET-applikationer.

Konfigurera spårningsbaserad provtagning

Spårningsbaserad sampling säkerställer att loggarna samplas konsekvent med den underliggande Activity. Detta är användbart när du vill upprätthålla korrelation mellan spårningar och loggar. Du kan aktivera spårningssampling (enligt beskrivningen i guiden) och sedan konfigurera spårningsbaserad loggsampling i enlighet med detta:

builder.Logging.AddTraceBasedSampler();

När spårningsbaserad sampling är aktiverad genereras loggar endast om den underliggande Activity är samplad. Samplingsbeslutet kommer från det aktuella Recorded värdet.

Konfigurera slumpmässigt probabilistiskt urval

Du kan använda slumpmässig sannolikhetssampling för att välja ut loggar baserat på konfigurerade sannolikhetsregler. Du kan definiera regler som är specifika för:

  • Loggkategori
  • Loggnivå
  • Händelse-ID

Det finns flera sätt att konfigurera slumpmässig probabilistisk sampling med dess regler:

Filbaserad konfiguration

Skapa ett konfigurationsavsnitt i din appsettings.json, till exempel:

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

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

Föregående konfiguration:

  • Samplar 10 % av loggar från kategorier som börjar med System. på alla nivåer.
  • Samplar 25% av loggar från kategorier som börjar med Microsoft.AspNetCore. av LogLevel.Information.
  • Exempel 5% av loggar med händelse-ID 1001 av alla kategorier och nivåer.
  • Provtar 100 % av alla övriga loggar.

Viktigt!

Värdet Probability representerar sannolikheten med värden från 0 till 1. 0,25 innebär till exempel att 25% loggar samplas. 0 innebär att inga loggar samplas och 1 innebär att alla loggar samplas. Dessa fall med 0 och 1 kan användas för att effektivt inaktivera eller aktivera alla loggar för en specifik regel. Sannolikheten får inte vara mindre än 0 eller större än 1, och om detta inträffar i programmet genereras ett undantag.

För att registrera samplern med konfigurationen, använd följande kod:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Ändra samplingsregler i en app som körs

Slumpmässig probabilistisk sampling stöder uppdateringar av konfigurationer under körning via IOptionsMonitor<TOptions> gränssnittet. Om du använder en konfigurationsprovider som stöder omladdningar, till exempel filkonfigurationsprovidern, kan du uppdatera samplingsreglerna vid körning utan att starta om programmet.

Du kan till exempel starta ditt program med följande appsettings.json, som effektivt fungerar som en no-op:

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

När appen körs kan du uppdatera appsettings.json med följande konfiguration:

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

De nya reglerna tillämpas automatiskt, till exempel med den följande konfigurationen samplas 1% av loggarna med LogLevel.Information.

Så här tillämpas samplingsregler

Algoritmen liknar loggfiltrering, men det finns vissa skillnader.

Utvärdering av loggsamplingsregler utförs på varje loggpost, men det finns prestandaoptimeringar på plats, till exempel cachelagring. Följande algoritm används för varje loggpost för en viss kategori:

  • Välj regler med LogLevel som är lika med eller högre än loggnivån för loggern.
  • Välj regler med EventId som inte är definierade eller som är definierade och lika med logghändelse-ID:t.
  • Välj regler med det längsta matchande kategoriprefixet. Om ingen matchning hittas väljer du alla regler som inte anger en kategori.
  • Om flera regler har valts tar du den sista .
  • Om inga regler har valts tillämpas inte sampling, till exempel genereras loggposten som vanligt.

Konfiguration av infogad kod

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

Föregående konfiguration:

  • Exempel 5% av loggar med händelse-ID 1001 av alla kategorier och nivåer.
  • Provtar 100 % av alla övriga loggar.

Enkel sannolikhetskonfiguration

För grundläggande scenarier kan du konfigurera ett enda sannolikhetsvärde som gäller för alla loggar på eller under en angiven nivå:

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

Koden ovan registrerar samplaren som tar ett urval av 10% av Warning loggar och 1% av Information (och under). Om konfigurationen inte hade regeln för Information, skulle den ha samplat 10% av Warning loggar och alla nivåer nedan, inklusive Information.

Implementera anpassad sampling

Du kan skapa en anpassad samplingsstrategi genom att härleda från den LoggingSampler abstrakta klassen och åsidosätta dess abstrakta medlemmar. På så sätt kan du anpassa samplingsbeteendet efter dina specifika krav. En anpassad urvalslösning kan till exempel:

  • Fatta samplingsbeslut baserat på förekomsten och värdet för specifika nyckel/värde-par i loggtillståndet.
  • Tillämpa hastighetsbegränsningslogik, till exempel att endast generera loggar om antalet loggar inom ett fördefinierat tidsintervall ligger under ett visst tröskelvärde.

Följ dessa steg för att implementera ett anpassat exempel:

  1. Skapa en klass som ärver från LoggingSampler.
  2. Åsidosätt LoggingSampler.ShouldSample metoden för att definiera din anpassade samplingslogik.
  3. Registrera din anpassade sampler i loggningspipelinen med hjälp av AddSampler tilläggsmetoden.

För varje loggpost som inte filtreras bort LoggingSampler.ShouldSample anropas metoden exakt en gång. Dess returvärde avgör om loggposten ska genereras.

Prestandaöverväganden

Loggsampling är utformat för att minska lagringskostnaderna, med den kompromissen att CPU-användningen ökar något. Om ditt program genererar en stor mängd loggar som är dyra att lagra kan sampling bidra till att minska volymen. När det är konfigurerat på rätt sätt kan sampling sänka lagringskostnaderna utan att förlora information som är viktig för att diagnostisera incidenter.

Den inbyggda samplingen finns i Benchmarks.

Vägledning på loggnivå om när sampling ska användas

Loggnivå Recommendation
Trace Använd inte sampling, eftersom du normalt inaktiverar dessa loggar i produktionsmiljöer.
Debug Använd inte sampling, eftersom du normalt inaktiverar dessa loggar i produktionsmiljöer.
Information Se till att använda sampling
Warning Överväg att tillämpa sampling
Error Använd inte sampling
Critical Använd inte sampling

Metodtips

  • Börja med högre samplingshastigheter och justera dem nedåt efter behov.
  • Använd kategoribaserade regler för att rikta in dig på specifika komponenter.
  • Om du använder distribuerad spårning kan du överväga att implementera spårningsbaserad sampling.
  • Övervaka effektiviteten i dina samplingsregler tillsammans.
  • Hitta rätt balans för ditt program – för låg samplingsfrekvens kan minska observerbarheten, medan en för hög frekvens kan öka kostnaderna.

Se även

  • Last updated on