Delen via

Logboeksampling in .NET

.NET biedt mogelijkheden voor logboeksampling waarmee u het volume van logboeken kunt beheren dat uw toepassing verzendt zonder dat belangrijke informatie verloren gaat. De volgende samplingstrategieën zijn beschikbaar:

  • Steekproeven op basis van tracering: voorbeeldlogboeken op basis van de steekproefbeslissing van de huidige tracering.
  • Willekeurige probabilistische steekproeven: voorbeeldlogboeken op basis van geconfigureerde waarschijnlijkheidsregels.
  • Aangepaste steekproeven: implementeer uw eigen aangepaste samplingstrategie. Zie Aangepaste steekproeven implementeren voor meer informatie.

Opmerking

Er kan slechts één sampler tegelijk worden gebruikt. Als u meerdere samplers registreert, wordt de laatste gebruikt.

Logboeksampling breidt de filtermogelijkheden uit door u meer gedetailleerde controle te geven over welke logboeken door uw toepassing worden verzonden. In plaats van logboeken in of uit te schakelen, kunt u steekproeven configureren om slechts een fractie ervan te verzenden.

Bij het filteren wordt bijvoorbeeld meestal gebruikgemaakt van waarschijnlijkheden zoals 0 (geen logboeken verzenden) of 1 (alle logboeken verzenden), kunt u met steekproeven een willekeurige waarde kiezen, zoals 0.1 het verzenden van 10% logboeken of 0.25 het verzenden van 25%.

Get started

Installeer het NuGet-pakket Microsoft.Extensions.Telemetry om aan de📦 slag te gaan:

dotnet add package Microsoft.Extensions.Telemetry

Zie dotnet-pakket toevoegen of Pakketafhankelijkheden beheren in .NET-toepassingenvoor meer informatie.

Sampling op basis van tracering configureren

Traceringsgebaseerde steekproeven zorgen ervoor dat logboeken consistent worden bemonsterd met de onderliggende Activitygegevens. Dit is handig als u de correlatie tussen traceringen en logboeken wilt behouden. U kunt trace-sampling inschakelen (zoals beschreven in de handleiding) en vervolgens logboeken op basis van trace-sampling configureren overeenkomstig:

builder.Logging.AddTraceBasedSampler();

Wanneer steekproeven op basis van tracering zijn ingeschakeld, worden logboeken alleen verzonden als de onderliggende Activity steekproef wordt genomen. De steekproefbeslissing komt uit de huidige Recorded waarde.

Willekeurige probabilistische steekproeven configureren

Met willekeurige probabilistische steekproeven kunt u logboeken steekproefen op basis van geconfigureerde waarschijnlijkheidsregels. U kunt regels definiëren die specifiek zijn voor:

  • Logboekcategorie
  • Logniveau
  • Gebeurtenis-id

Er zijn verschillende manieren om willekeurige probabilistische steekproeven te configureren met de bijbehorende regels:

Bestandsgebaseerde configuratie

Maak een configuratiesectie in uw appsettings.json, bijvoorbeeld:

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

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

De voorgaande configuratie:

  • Bemonstert 10% van de logboeken uit categorieën die beginnen met System. op alle niveaus.
  • 25% van de logboeken uit categorieën die beginnen met Microsoft.AspNetCore. van de LogLevel.Information worden bemonsterd.
  • Steekproeftrekken van 5% van de logboeken met gebeurtenis-ID 1001 uit alle categorieën en niveaus.
  • Maakt een voorbeeld van 100% van alle overige logboeken.

Belangrijk

De Probability waarde vertegenwoordigt waarschijnlijkheid met waarden tussen 0 en 1. 0,25 betekent bijvoorbeeld dat er 25% van de logboeken zal worden bemonsterd. 0 betekent dat er geen logboeken worden bemonsterd en 1 betekent dat alle logboeken worden gesampleerd. Deze gevallen met 0 en 1 kunnen worden gebruikt om alle logboeken voor een specifieke regel effectief uit te schakelen of in te schakelen. De kans mag niet kleiner zijn dan 0 of groter dan 1 en als dit gebeurt in de toepassing, wordt er een uitzondering gegenereerd.

Als u de sampler wilt registreren bij de configuratie, moet u rekening houden met de volgende code:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Samplingregels in een actieve app wijzigen

Willekeurige probabilistische steekproeven ondersteunen runtimeconfiguratie-updates via de IOptionsMonitor<TOptions> interface. Als u een configuratieprovider gebruikt die ondersteuning biedt voor opnieuw laden, zoals de bestandsconfiguratieprovider, kunt u samplingregels tijdens runtime bijwerken zonder de toepassing opnieuw op te starten.

U kunt uw toepassing bijvoorbeeld starten met de volgende appsettings.json, die effectief fungeert als een no-op:

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

Terwijl de app wordt uitgevoerd, kunt u de appsettings.json bijwerken met de volgende configuratie:

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

De nieuwe regels worden automatisch toegepast. Bijvoorbeeld, met de voorgaande configuratie wordt 1% van de logboeken met de LogLevel.Information bemonsterd.

Hoe steekproevenregels worden toegepast

Het algoritme is vergelijkbaar met logboekfiltering, maar er zijn enkele verschillen.

Evaluatie van logboeksamplingsregels wordt uitgevoerd op elke logboekrecord, maar er zijn prestatieoptimalisaties, zoals caching. Het volgende algoritme wordt gebruikt voor elke logboekrecord voor een bepaalde categorie:

  • Selecteer regels die LogLevel gelijk zijn aan of hoger zijn dan het logboekniveau van de logger.
  • Selecteer regels met EventId niet gedefinieerd of gedefinieerd en gelijk aan de logboekgebeurtenis-ID.
  • Selecteer regels met het langste overeenkomende categorievoorvoegsel. Als er geen overeenkomst wordt gevonden, selecteert u alle regels die geen categorie opgeven.
  • Als er meerdere regels zijn geselecteerd, neemt u de laatste regel.
  • Als er geen regels zijn geselecteerd, wordt bijvoorbeeld geen steekproeven toegepast, wordt de logboekrecord zoals gebruikelijk verzonden.

Configuratie van inlinecode

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

De voorgaande configuratie:

  • Steekproeftrekken van 5% van de logboeken met gebeurtenis-ID 1001 uit alle categorieën en niveaus.
  • Maakt een voorbeeld van 100% van alle overige logboeken.

Eenvoudige waarschijnlijkheidsconfiguratie

Voor basisscenario's kunt u één waarschijnlijkheidswaarde configureren die van toepassing is op alle logboeken op of onder een opgegeven niveau:

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

De bovenstaande code registreert de sampler die 10% van de Warning logbestanden en 1% van de Information logbestanden (en lager) zou bemonsteren. Als de configuratie niet over de regel voor Information beschikte, zou 10% van de Warning-logboeken en alle niveaus daaronder, inclusief Information, zijn bemonsterd.

Aangepaste steekproeven implementeren

U kunt een aangepaste samplingstrategie maken door de abstracte klasse af te leiden LoggingSampler en de abstracte leden ervan te overschrijven. Hiermee kunt u het steekproefgedrag aanpassen aan uw specifieke vereisten. Een aangepaste sampler kan bijvoorbeeld het volgende doen:

  • Neem steekproeven op basis van de aanwezigheid en waarde van specifieke sleutel-/waardeparen in de logboekstatus.
  • Pas frequentiebeperkingslogica toe, zoals het verzenden van logboeken alleen als het aantal logboeken binnen een vooraf gedefinieerd tijdsinterval onder een bepaalde drempelwaarde blijft.

Voer de volgende stappen uit om een aangepaste sampler te implementeren:

  1. Maak een klasse die wordt overgenomen van LoggingSampler.
  2. Overschrijf de LoggingSampler.ShouldSample methode om uw aangepaste samplinglogica te definiëren.
  3. Registreer uw aangepaste sampler in de logboekpijplijn met behulp van de AddSampler extension method.

Voor elke logboekrecord die niet is uitgefilterd, wordt de LoggingSampler.ShouldSample methode precies één keer aangeroepen. De retourwaarde bepaalt of de logboekrecord moet worden verzonden.

Prestatie-overwegingen

Logsampling is ontworpen om de opslagkosten te verlagen, met als afweging een licht verhoogde CPU-belasting. Als uw toepassing een groot aantal logboeken genereert die duur zijn om op te slaan, kan het nemen van steekproeven helpen om dat volume te verminderen. Wanneer steekproeven op de juiste wijze zijn geconfigureerd, kunnen de opslagkosten worden verlaagd zonder dat er gegevens verloren gaan die essentieel zijn voor het diagnosticeren van incidenten.

Zie Benchmarks voor de ingebouwde steekproeven.

Richtlijnen op logboekniveau voor het gebruik van steekproeven

Logniveau Aanbeveling
Trace Geen steekproeven toepassen, omdat u deze logboeken normaal gesproken uitschakelt in productie
Debug Geen steekproeven toepassen, omdat u deze logboeken normaal gesproken uitschakelt in productie
Information Zorg ervoor dat je steekproeven toepast
Warning Overweeg steekproeven toe te passen
Error Geen steekproeven toepassen
Critical Geen steekproeven toepassen

Beste praktijken

  • Begin met een hogere steekproeffrequentie en pas ze indien nodig naar beneden aan.
  • Gebruik op categorie gebaseerde regels om specifieke onderdelen te targeten.
  • Als u gedistribueerde tracering gebruikt, kunt u overwegen om steekproeven op basis van tracering te implementeren.
  • Bewaak de effectiviteit van uw steekproefregels gezamenlijk.
  • Zoek het juiste evenwicht voor uw toepassing: een te lage steekproefsnelheid kan de waarneembaarheid verminderen, terwijl een te hoog tarief de kosten kan verhogen.

Zie ook

  • Last updated on