Protokollsampling in .NET

.NET bietet Protokollsamplingfunktionen, mit denen Sie das Volumen der Von Der Anwendung ausgegebenen Protokolle steuern können, ohne wichtige Informationen zu verlieren. Die folgenden Samplingstrategien sind verfügbar:

• Ablaufverfolgungsbasiertes Sampling: Protokolle werden basierend auf der Stichprobenentscheidung der aktuellen Ablaufverfolgung ausgewählt.
• Zufälliges probabilistisches Sampling: Beispielprotokolle basierend auf konfigurierten Wahrscheinlichkeitsregeln.
• Benutzerdefiniertes Sampling: Implementieren Sie Ihre eigene benutzerdefinierte Samplingstrategie. Weitere Informationen finden Sie unter Implementieren von benutzerdefiniertem Sampling.

Das Protokollsampling erweitert die Filterfunktionen , indem Sie präzisere Kontrolle darüber erhalten, welche Protokolle von Ihrer Anwendung ausgegeben werden. Anstatt einfach Protokolle zu aktivieren oder zu deaktivieren, können Sie das Sampling so konfigurieren, dass nur ein Bruchteil davon ausgegeben wird.

Beispielsweise verwenden Sie beim Filtern in der Regel Wahrscheinlichkeiten wie 0 (keine Logs erfassen) oder 1 (alle Logs erfassen), während Sie beim Sampling jeden beliebigen Wert dazwischen wählen können—etwa 0.1 um 10 % der Logs zu erfassen oder 0.25 um 25 % zu erfassen.

Get started

Installieren Sie zunächst das 📦 NuGet-Paket "Microsoft.Extensions.Telemetry ":

dotnet add package Microsoft.Extensions.Telemetry

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Telemetry"
                    Version="*" />
</ItemGroup>

Weitere Informationen finden Sie unter dotnet add package oder Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

Tracing-basiertes Sampling konfigurieren

Ablaufverfolgungsbasiertes Sampling stellt sicher, dass Protokolle konsistent mit dem zugrunde liegenden Activity abgesampelt werden. Dies ist nützlich, wenn Sie die Korrelation zwischen Traces und Protokollen erhalten möchten. Sie können das Trace-Sampling aktivieren (wie in der Anleitung beschrieben) und dann das Trace-basierte Log-Sampling entsprechend konfigurieren.

builder.Logging.AddTraceBasedSampler();

Wenn ablaufverfolgungsbasiertes Sampling aktiviert ist, werden Logs nur ausgegeben, wenn das zugrunde liegende Activity gesampelt wird. Die Samplingentscheidung stammt aus dem aktuellen Recorded Wert.

Konfigurieren von zufälligem probabilistischem Stichprobensampling

Zufälliges probabilistisches Sampling ermöglicht Ihnen das Entnehmen von Protokollen basierend auf konfigurierten Wahrscheinlichkeitsregeln. Sie können Regeln für Folgendes definieren:

• Protokollkategorie
• Protokolliergrad
• Ereignis-ID

Es gibt verschiedene Möglichkeiten, zufällige probabilistische Samplings mit ihren Regeln zu konfigurieren:

Dateibasierte Konfiguration

Erstellen Sie in Ihrem appsettings.jsoneinen Konfigurationsabschnitt, z. B.:

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

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

Die vorherige Konfiguration:

• Erfasst 10 % der Logdateien aus Kategorien, die mit System. beginnen, auf allen Ebenen.
• Erfasst 25% der Protokolle aus mit Microsoft.AspNetCore. beginnenden Kategorien des LogLevel.Information.
• Beispiele für 5% von Protokollen mit der Ereignis-ID 1001 aller Kategorien und Ebenen.
• Nimmt 100% von allen anderen Protokollen Stichproben.

Um den Sampler bei der Konfiguration zu registrieren, verwenden Sie den folgenden Code:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Ändern von Samplingregeln in einer ausgeführten App

Zufallsstichproben unterstützen Laufzeit-Konfigurationsupdates über die IOptionsMonitor<TOptions> Schnittstelle. Wenn Sie einen Konfigurationsanbieter verwenden, der Neuladen unterstützt , z. B. den Dateikonfigurationsanbieter, können Sie Samplingregeln zur Laufzeit aktualisieren, ohne die Anwendung neu zu starten.

Sie können ihre Anwendung beispielsweise mit der folgenden appsettings.jsonstarten, die effektiv als no-opfungiert:

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

Während die App ausgeführt wird, können Sie die appsettings.json mit der folgenden Konfiguration aktualisieren:

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

Die neuen Regeln werden z. B. mit der vorherigen Konfiguration automatisch angewendet, wobei 1 % der Protokolle mit dem LogLevel.Information ausgewählt werden.

Wie Samplingregeln angewendet werden

Der Algorithmus ist der Protokollfilterung sehr ähnlich, aber es gibt einige Unterschiede.

Die Auswertung von Protokoll-Samplingregeln wird für jeden Protokolldatensatz durchgeführt, es gibt jedoch Leistungsoptimierungen, z. B. durch Zwischenspeicherung. Der folgende Algorithmus wird für jeden Protokolldatensatz für eine bestimmte Kategorie verwendet:

• Wählen Sie Regeln aus, LogLevel die gleich oder höher als die Protokollebene des Loggers sind.
• Wählen Sie Regeln aus, die EventId nicht definiert sind oder nicht definiert sind und der Protokollereignis-ID entsprechen.
• Wählen Sie Regeln aus, deren Kategorie-Präfix am längsten übereinstimmt. Wenn keine Übereinstimmung gefunden wird, werden alle Regeln ohne Angabe einer Kategorie ausgewählt.
• Wenn mehrere Regeln ausgewählt sind, wird die letzte Regel verwendet.
• Wenn keine Regeln ausgewählt sind, wird das Sampling nicht angewendet, z. B. wird der Protokolldatensatz wie gewohnt ausgegeben.

Inline-Code-Konfiguration

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

Die vorherige Konfiguration:

• Beispiele für 5% von Protokollen mit der Ereignis-ID 1001 aller Kategorien und Ebenen.
• Nimmt 100% von allen anderen Protokollen Stichproben.

Einfache Wahrscheinlichkeitskonfiguration

Für grundlegende Szenarien können Sie einen einzelnen Wahrscheinlichkeitswert konfigurieren, der für alle Protokolle auf oder unter einer angegebenen Ebene gilt:

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

Der obige Code registriert den Sampler, der 10% von Warning Protokollen und 1% von Information (und unten) Protokollen beispielen würde. Wenn die Konfiguration nicht über die Regel für Information verfügte, hätte sie 10% von Warning Protokollen sowie alle darunterliegenden Ebenen, einschließlich Information, abgetastet.

Implementieren von benutzerdefiniertem Sampling

Sie können eine benutzerdefinierte Samplingstrategie erstellen, indem Sie von der LoggingSampler abstrakten Klasse ableiten und die abstrakten Elemente überschreiben. Auf diese Weise können Sie das Samplingverhalten auf Ihre spezifischen Anforderungen anpassen. Beispielsweise könnte ein benutzerdefinierter Sampler:

• Treffen Sie Samplingentscheidungen basierend auf dem Vorhandensein und Wert bestimmter Schlüssel-Wert-Paare im Protokollstatus.
• Wenden Sie eine Rate-Limiting-Logik an, z. B. indem Sie Protokolle nur dann ausgeben, wenn die Anzahl der Protokolle innerhalb eines vordefinierten Zeitintervalls unter einem bestimmten Schwellenwert bleibt.

Führen Sie die folgenden Schritte aus, um einen benutzerdefinierten Sampler zu implementieren:

1. Erstellen Sie eine Klasse, die von LoggingSampler erbt.
2. Überschreiben Sie die LoggingSampler.ShouldSample Methode, um Ihre benutzerdefinierte Samplinglogik zu definieren.
3. Registrieren Sie Ihren benutzerdefinierten Sampler in der Protokollierungspipeline mithilfe der AddSampler Erweiterungsmethode.

Für jeden Protokolldatensatz, der nicht herausgefiltert wird, wird die LoggingSampler.ShouldSample Methode genau einmal aufgerufen. Der Rückgabewert bestimmt, ob der Protokolldatensatz ausgegeben werden soll.

Leistungsüberlegungen

Log Sampling wurde entwickelt, um die Speicherkosten zu reduzieren, mit einem Kompromiss von leicht erhöhter CPU-Auslastung. Wenn Ihre Anwendung ein hohes Volumen von Protokollen generiert, die teuer zu speichern sind, kann das Sampling dazu beitragen, dieses Volumen zu reduzieren. Bei entsprechender Konfiguration kann das Sampling die Speicherkosten senken, ohne dass Informationen verloren gehen, die für die Diagnose von Vorfällen von entscheidender Bedeutung sind.

Die integrierten Samplings finden Sie unter Benchmarks.

Anleitungen zur Protokollebene für die Verwendung des Samplings

Bewährte Methoden

• Beginnen Sie mit höheren Samplingraten, und passen Sie sie nach Bedarf nach unten an.
• Verwenden Sie kategoriebasierte Regeln, um bestimmte Komponenten als Ziel festzulegen.
• Wenn Sie die verteilte Ablaufverfolgung verwenden, sollten Sie das trace-basierte Sampling implementieren.
• Überwachen Sie die Effektivität Ihrer Samplingregeln gemeinsam.
• Finden Sie das richtige Gleichgewicht für Ihre Anwendung – eine zu niedrige Abtastrate kann die Beobachtbarkeit verringern, während eine zu hohe die Kosten erhöhen kann.

Siehe auch

• Protokollierung in .NET
• Hochleistungsprotokollierung in .NET
• OpenTelemetry-Ablaufverfolgungs-Sampling