HTTP-Clientprotokollierung in .NET

Wenn Sie Anwendungen erstellen, die HTTP-Anforderungen stellen, hilft Ihnen die strukturierte Protokollierung bei der Überwachung, Problembehandlung und Analyse ausgehenden Datenverkehrs. Die AddExtendedHttpClientLogging Erweiterung bietet eine erweiterte Protokollierung für alle HTTP-Clients, die mit IHttpClientFactory erstellt wurden, mit integrierter Unterstützung für:

• Konfigurierbare Protokollierung – Steuern, was protokolliert wird (Header, Textkörper, Abfrageparameter, Routenparameter)
• Datenredaktion – Anwenden von Datenklassifizierungs- und Datenmaskierungsrichtlinien für Datenschutz und Compliance
• Protokollanreicherung – Hinzufügen eines benutzerdefinierten Kontexts zu HTTP-Anforderungsprotokollen
• Minimaler Aufwand – Opt-In-Features mit leistungsbewussten Standardwerten

Aktivieren Sie die erweiterte HTTP-Clientprotokollierung, indem Sie die AddExtendedHttpClientLogging Erweiterungsmethode aufrufen. Dadurch wird der standardmäßige HTTP-Client-Logger durch einen erweiterten Logger ersetzt, der differenzierte Konfigurations- und Datenkonformitätsfunktionen unterstützt.

Hinzufügen des Pakets

dotnet add package Microsoft.Extensions.Http.Diagnostics

dotnet package add Microsoft.Extensions.Http.Diagnostics

<PackageReference Include="Microsoft.Extensions.Http.Diagnostics"
                  Version="*" /> <!-- Adjust version -->

Weitere Informationen finden Sie unter dotnet package add or Manage package dependencies in .NET applications.

HTTP-Clientprotokollierung aktivieren

Rufen Sie zum Hinzufügen der erweiterten HTTP-Clientprotokollierung zu Ihrer Anwendung die AddExtendedHttpClientLogging Erweiterungsmethode beim Konfigurieren Ihrer Dienste auf:

using Microsoft.Extensions.DependencyInjection;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

// Register redaction services (required)
builder.Services.AddRedaction();

// Add enhanced HTTP client logging
builder.Services.AddExtendedHttpClientLogging();

// Add your HTTP clients
builder.Services.AddHttpClient<MyApiClient>();

using IHost host = builder.Build();

await host.RunAsync();

Diese Registrierung fügt allen HTTP-Clients, die durch IHttpClientFactory erstellt wurden, einen erweiterten Logger hinzu, wobei der Standardlogger durch einen ersetzt wird, der eine erweiterte Konfiguration unterstützt.

Anwenden der Protokollierung auf bestimmte HTTP-Clients

Sie können die erweiterte Protokollierung auch auf bestimmte benannte oder typierte HTTP-Clients anwenden, indem Sie die IHttpClientBuilder Erweiterungsmethoden verwenden:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

// Register redaction services (required)
builder.Services.AddRedaction();

// Apply to a named client
builder.Services.AddHttpClient("MyNamedClient")
    .AddExtendedHttpClientLogging();

// Apply to a typed client with configuration
builder.Services.AddHttpClient<MyApiClient>()
    .AddExtendedHttpClientLogging(options =>
    {
        options.LogBody = true;
        options.ResponseBodyContentTypes.Add("application/json");
    });

using IHost host = builder.Build();

await host.RunAsync();    

Bei Verwendung der IHttpClientBuilder Überladungen wird die Protokollierung nur auf diesen bestimmten Client angewendet, nicht global.

Anzeigen erweiterter Protokolldaten

Die verbesserte HTTP-Clientprotokollierung fügt unter Verwendung von Anreicherungen Informationen zu den Protokollen hinzu, was bedeutet, dass Daten als Tags zu strukturierten Protokollen und nicht zur Konsolennachricht hinzugefügt werden. Verwenden Sie einen Protokollierungsanbieter, der strukturierte Protokolle unterstützt, um die erweiterten Informationen anzuzeigen.

Verwenden Sie AddJsonConsole, um für schnelle Tests strukturierte Protokolle in der Konsole auszugeben.

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddJsonConsole();

builder.Services.AddRedaction();

builder.Services.AddHttpClient("MyClient")
    .AddExtendedHttpClientLogging(options =>
    {
        options.LogBody = true;
        options.ResponseBodyContentTypes.Add("application/json");
    });

Für Produktionsszenarien sollten Sie die Verwendung von strukturierten Protokollierungsanbietern wie Application Insights, Seq oder Elasticsearch in Betracht ziehen, die die erweiterten Tagdaten abfragen und visualisieren können.

Konfigurieren von Protokollierungsoptionen

Sie konfigurieren die HTTP-Clientprotokollierung über die LoggingOptions Klasse mithilfe des Standardoptionenmusters. Sie können Optionen im Code konfigurieren oder aus der Konfiguration binden (z. B appsettings.json. ).

Konfigurieren mit einer Stellvertretung

builder.Services.AddExtendedHttpClientLogging(options =>
{
    // Log request headers with data classification
    options.RequestHeadersDataClasses.Add("User-Agent", DataClassification.None);
    options.RequestHeadersDataClasses.Add("Authorization", DataClassification.Unknown);

    // Log response headers
    options.ResponseHeadersDataClasses.Add("Content-Type", DataClassification.None);

    // Enable request/response body logging (use carefully in production)
    options.LogBody = true;
    options.BodySizeLimit = 4096; // Limit to 4KB
    options.RequestBodyContentTypes.Add("application/json");
    options.ResponseBodyContentTypes.Add("application/json");
});

Konfigurieren von appsettings.json

{
  "HttpClientLogging": {
    "LogRequestStart": false,
    "LogBody": false,
    "BodySizeLimit": 32768,
    "BodyReadTimeout": "00:00:01",
    "RequestHeadersDataClasses": {
      "User-Agent": "None",
      "Content-Type": "None"
    },
    "ResponseHeadersDataClasses": {
      "Content-Type": "None"
    },
    "RequestPathLoggingMode": "Formatted",
    "RequestPathParameterRedactionMode": "Strict"
  }
}

builder.Services.AddExtendedHttpClientLogging(
    builder.Configuration.GetSection("HttpClientLogging"));

Konfigurationsoptionen

Die LoggingOptions Klasse bietet die folgenden Konfigurationsoptionen:

Grundlegende Protokollierungsoptionen

Header- und Abfrageparameterprotokollierung

Pfad- und Routenparameterprotokollierung

Hinzufügen von Protokollanreicherungsfunktionen

Mithilfe von HTTP-Client-Loganreicherern können Sie HTTP-Client-Logs mit benutzerdefinierten Kontextinformationen basierend auf der Anforderung, der Antwort und einer Ausnahme anreichern. Im Gegensatz zu allgemeinen Log-Erweiterern zielen HTTP-Client-Erweiterer speziell auf ausgehende HTTP-Anforderungen ab und haben Zugriff auf HTTP-spezifischem Kontext.

Hier ist ein schnelles Beispiel:

public class CustomHttpLogEnricher : IHttpClientLogEnricher
{
    public void Enrich(IEnrichmentTagCollector collector,
        HttpRequestMessage request, HttpResponseMessage? response, Exception? exception)
    {
        // Add tags based on the exception (if available)
        if (exception is not null)
        {
            collector.Add("error_type", exception.GetType().Name);
        }
    }
}

// Register the enricher
builder.Services.AddHttpClientLogEnricher<CustomHttpLogEnricher>();

Ausführliche Informationen zum Erstellen und Verwenden von HTTP-Clientprotokollreicherern, einschließlich bewährter Methoden und erweiterter Szenarien, finden Sie unter HTTP-Clientprotokollreicherer.

Datenklassifizierung und -redaction

Die HTTP-Clientprotokollierung ist in die Datenreduzierung und die Datenklassifizierung integriert, um vertrauliche Informationen zu schützen. Wenn Sie DataClassification für Kopfzeilen, Abfrageparameter oder Routenparameter angeben, wird das Bearbeitungssystem basierend auf den konfigurierten Redakteuren entsprechende Bearbeitungsaktionen anwenden.

Beispiel: Bearbeiten vertraulicher Kopfzeilen

using Microsoft.Extensions.Compliance.Classification;

builder.Services.AddExtendedHttpClientLogging(options =>
{
    // Public headers - no redaction
    options.RequestHeadersDataClasses.Add("User-Agent", DataClassification.None);
    options.RequestHeadersDataClasses.Add("Content-Type", DataClassification.None);

    // Sensitive headers - apply redaction
    options.RequestHeadersDataClasses.Add("Authorization", DataClassification.Unknown);
    options.RequestHeadersDataClasses.Add("X-API-Key", DataClassification.Unknown);
});

Weitere Informationen zum Konfigurieren von Redactors finden Sie unter Data redaction in .NET.

Redaction des Pfad- und Routenparameters

Standardmäßig werden Anforderungs- und Antwortpfade bei der HTTP-Client-Protokollierung unkenntlich gemacht, um den Datenschutz zu schützen. Beim Protokollieren von HTTP-Anforderungspfaden können Sie steuern, wie Routenparameter mithilfe der RequestPathParameterRedactionMode Option redigiert werden:

Die RequestPathLoggingMode Option steuert das Format des protokollierten Pfads:

Beispiel: Deaktivieren der Pfadanonymisierung

Um vollständige, unveränderte Pfade (z. B. in Entwicklungsumgebungen) zu protokollieren, setzen Sie RequestPathParameterRedactionMode auf None.

builder.Services.AddExtendedHttpClientLogging(options =>
{
    // Disable redaction of request/response paths
    options.RequestPathParameterRedactionMode = HttpRouteParameterRedactionMode.None;
});

Leistungsüberlegungen

Die erweiterte HTTP-Clientprotokollierung ist unter Berücksichtigung der Leistung konzipiert, es gibt jedoch Kompromisse:

• Body-Logging: Das Aktivieren von LogBody fügt Overhead beim Puffern und Lesen der Anfrage-/Antwortkörper hinzu. Verwenden Sie BodySizeLimit und BodyReadTimeout, um die Ressourcennutzung zu steuern.
• Headerprotokollierung: Loggen Sie nur die Header, die Sie benötigen. Leere RequestHeadersDataClasses und ResponseHeadersDataClasses vermeiden den Verarbeitungsaufwand der Kopfzeilen.
• Anreicher: Jeder registrierte Anreicherer wird für jede Anforderung aufgerufen. Halten Sie die Anreicherungslogik leichtgewichtig.
• Redaction: Datenklassifizierung und Redaction fügen minimalen Aufwand hinzu, skalieren jedoch mit der Anzahl der klassifizierten Elemente.

Siehe auch

• HTTP-Clientfabrik in .NET
• HTTP-Client-Log-Anreicherer
• Überwachen und Analysieren der HTTP-Clientleistung
• Datenunkenntlichmachung in .NET
• Datenklassifizierung in .NET
• Protokollierung in .NET