HTTP-Protokollierung in ASP.NET Core

Die HTTP-Protokollierung ist eine Middleware, die Informationen zu eingehenden HTTP-Anforderungen und HTTP-Antworten protokolliert. Die HTTP-Protokollierung enthält Protokolle zu:

• HTTP-Anforderungsinformationen
• Allgemeine Eigenschaften
• Header
• Text
• HTTP-Antwortinformationen

Die HTTP-Protokollierung kann:

• alle Anforderungen und Antworten oder nur Anforderungen und Antworten protokollieren, die bestimmten Kriterien entsprechen
• auswählen, welche Teile der Anforderung und Antwort protokolliert werden
• die Bearbeitung vertraulicher Informationen aus den Protokollen ermöglichen

Die HTTP-Protokollierung kann die Leistung einer App reduzieren, insbesondere beim Protokollieren des Anforderungs- und Antworttexts. Berücksichtigen Sie die Auswirkungen auf die Leistung, wenn Sie die zu protokollierenden Felder auswählen. Testen Sie die Auswirkungen der ausgewählten Protokollierungseigenschaften auf die Leistung.

Warnung

Die HTTP-Protokollierung kann potenziell personenbezogene Informationen (Personally Identifiable Information, PII) protokollieren. Berücksichtigen Sie das Risiko, und vermeiden Sie die Protokollierung vertraulicher Informationen.

Aktivieren der HTTP-Protokollierung

Die HTTP-Protokollierung wird durch Aufrufen von AddHttpLogging und UseHttpLogging aktiviert, wie im folgenden Beispiel gezeigt:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(o => { });

var app = builder.Build();

app.UseHttpLogging();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}
app.UseStaticFiles();

app.MapGet("/", () => "Hello World!");

app.Run();

Der leere Lambdaausdruck im vorherigen Beispiel für den Aufruf AddHttpLogging fügt die Middleware mit der Standardkonfiguration hinzu. Standardmäßig protokolliert die HTTP-Protokollierung allgemeine Eigenschaften wie Pfad, Statuscode und Header für Anforderungen und Antworten.

Fügen Sie der Datei appsettings.Development.json auf der Ebene "LogLevel": { die folgende Zeile hinzu, damit die HTTP-Protokolle angezeigt werden:

 "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"

Bei der Standardkonfiguration werden eine Anforderung und eine Antwort als Nachrichtenpaar protokolliert, das dem folgenden Beispiel ähnelt:

info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[1]
      Request:
      Protocol: HTTP/2
      Method: GET
      Scheme: https
      PathBase:
      Path: /
      Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7
      Host: localhost:52941
      User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36 Edg/118.0.2088.61
      Accept-Encoding: gzip, deflate, br
      Accept-Language: en-US,en;q=0.9
      Upgrade-Insecure-Requests: [Redacted]
      sec-ch-ua: [Redacted]
      sec-ch-ua-mobile: [Redacted]
      sec-ch-ua-platform: [Redacted]
      sec-fetch-site: [Redacted]
      sec-fetch-mode: [Redacted]
      sec-fetch-user: [Redacted]
      sec-fetch-dest: [Redacted]
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[2]
      Response:
      StatusCode: 200
      Content-Type: text/plain; charset=utf-8
      Date: Tue, 24 Oct 2023 02:03:53 GMT
      Server: Kestrel

HTTP-Protokollierungsoptionen

Um globale Optionen für die HTTP-Protokollierungsmiddleware zu konfigurieren, rufen Sie AddHttpLogging in Program.cs auf, indem Sie den Lambdaausdruck verwenden, um HttpLoggingOptions zu konfigurieren.

using Microsoft.AspNetCore.HttpLogging;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.All;
    logging.RequestHeaders.Add("sec-ch-ua");
    logging.ResponseHeaders.Add("MyResponseHeader");
    logging.MediaTypeOptions.AddText("application/javascript");
    logging.RequestBodyLogLimit = 4096;
    logging.ResponseBodyLogLimit = 4096;
    logging.CombineLogs = true;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();

app.UseHttpLogging(); 

app.Use(async (context, next) =>
{
    context.Response.Headers["MyResponseHeader"] =
        new string[] { "My Response Header Value" };

    await next();
});

app.MapGet("/", () => "Hello World!");

app.Run();

Hinweis

Im vorherigen Beispiel und den folgenden Beispielen wird UseHttpLogging nach UseStaticFiles aufgerufen. Die HTTP-Protokollierung ist also für statische Dateien nicht aktiviert. Um die HTTP-Protokollierung für statische Dateien zu aktivieren, rufen Sie UseHttpLogging vor UseStaticFiles auf.

LoggingFields

HttpLoggingOptions.LoggingFields ist ein Enumerationsflag, das bestimmte Teile der zu protokollierenden Anforderung und Antwort konfiguriert. HttpLoggingOptions.LoggingFields ist standardmäßig RequestPropertiesAndHeaders | ResponsePropertiesAndHeaders.

RequestHeaders und ResponseHeaders

RequestHeaders und ResponseHeaders sind die HTTP-Header, die protokolliert werden. Headerwerte werden nur für Headernamen protokolliert, die in diesen Sammlungen enthalten sind. Der folgende Code fügt sec-ch-ua zu RequestHeaders hinzu, sodass der Wert des sec-ch-ua-Headers protokolliert wird. Außerdem wird MyResponseHeader zu ResponseHeaders hinzugefügt, sodass der Wert des MyResponseHeader-Headers protokolliert wird. Wenn diese Zeilen entfernt werden, lauten die Werte dieser Header [Redacted].

using Microsoft.AspNetCore.HttpLogging;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.All;
    logging.RequestHeaders.Add("sec-ch-ua");
    logging.ResponseHeaders.Add("MyResponseHeader");
    logging.MediaTypeOptions.AddText("application/javascript");
    logging.RequestBodyLogLimit = 4096;
    logging.ResponseBodyLogLimit = 4096;
    logging.CombineLogs = true;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();

app.UseHttpLogging(); 

app.Use(async (context, next) =>
{
    context.Response.Headers["MyResponseHeader"] =
        new string[] { "My Response Header Value" };

    await next();
});

app.MapGet("/", () => "Hello World!");

app.Run();

MediaTypeOptions

MediaTypeOptions stellt die Konfiguration für die Auswahl der für einen bestimmten Medientyp zu verwendenden Codierung bereit.

using Microsoft.AspNetCore.HttpLogging;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.All;
    logging.RequestHeaders.Add("sec-ch-ua");
    logging.ResponseHeaders.Add("MyResponseHeader");
    logging.MediaTypeOptions.AddText("application/javascript");
    logging.RequestBodyLogLimit = 4096;
    logging.ResponseBodyLogLimit = 4096;
    logging.CombineLogs = true;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();

app.UseHttpLogging(); 

app.Use(async (context, next) =>
{
    context.Response.Headers["MyResponseHeader"] =
        new string[] { "My Response Header Value" };

    await next();
});

app.MapGet("/", () => "Hello World!");

app.Run();

Dieser Ansatz kann auch verwendet werden, um die Protokollierung für Daten zu ermöglichen, die standardmäßig nicht protokolliert werden (z. B. Formulardaten, deren Medientyp application/x-www-form-urlencoded oder multipart/form-data lauten kann).

MediaTypeOptions Methoden

• AddText
• AddBinary
• Clear

RequestBodyLogLimit und ResponseBodyLogLimit

• RequestBodyLogLimit
• ResponseBodyLogLimit

using Microsoft.AspNetCore.HttpLogging;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.All;
    logging.RequestHeaders.Add("sec-ch-ua");
    logging.ResponseHeaders.Add("MyResponseHeader");
    logging.MediaTypeOptions.AddText("application/javascript");
    logging.RequestBodyLogLimit = 4096;
    logging.ResponseBodyLogLimit = 4096;
    logging.CombineLogs = true;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();

app.UseHttpLogging(); 

app.Use(async (context, next) =>
{
    context.Response.Headers["MyResponseHeader"] =
        new string[] { "My Response Header Value" };

    await next();
});

app.MapGet("/", () => "Hello World!");

app.Run();

CombineLogs

Wenn Sie CombineLogs auf true festlegen, wird die Middleware so konfiguriert, dass alle aktivierten Protokolle für eine Anforderung und Antwort in einem Protokoll am Ende konsolidiert werden. Das umfasst die Anforderung, den Anforderungstext, die Antwort, den Antworttext und die Dauer.

using Microsoft.AspNetCore.HttpLogging;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.All;
    logging.RequestHeaders.Add("sec-ch-ua");
    logging.ResponseHeaders.Add("MyResponseHeader");
    logging.MediaTypeOptions.AddText("application/javascript");
    logging.RequestBodyLogLimit = 4096;
    logging.ResponseBodyLogLimit = 4096;
    logging.CombineLogs = true;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
}

app.UseStaticFiles();

app.UseHttpLogging(); 

app.Use(async (context, next) =>
{
    context.Response.Headers["MyResponseHeader"] =
        new string[] { "My Response Header Value" };

    await next();
});

app.MapGet("/", () => "Hello World!");

app.Run();

Endpunktspezifische Konfiguration

Für endpunktspezifische Konfigurationen in minimalen API-Apps ist eine WithHttpLogging-Erweiterungsmethode verfügbar. Das folgende Beispiel zeigt, wie die HTTP-Protokollierung für einen Endpunkt konfiguriert wird:

app.MapGet("/response", () => "Hello World! (logging response)")
    .WithHttpLogging(HttpLoggingFields.ResponsePropertiesAndHeaders);

Für endpunktspezifische Konfigurationen in Apps, die Controller verwenden, ist das [HttpLogging]-Attribut verfügbar. Das Attribut kann auch in minimalen API-Apps verwendet werden, wie im folgenden Beispiel gezeigt:

app.MapGet("/duration", [HttpLogging(loggingFields: HttpLoggingFields.Duration)]
    () => "Hello World! (logging duration)");

IHttpLoggingInterceptor

IHttpLoggingInterceptor ist die Schnittstelle für einen Dienst, der implementiert werden kann, um Rückrufe pro Anforderung und Antwort zu verarbeiten und anzupassen, welche Details protokolliert werden. Alle endpunktspezifischen Protokolleinstellungen werden zuerst angewendet und können dann in diesen Rückrufen überschrieben werden. Eine Implementierung kann:

• eine Anforderung oder Antwort untersuchen
• alle HttpLoggingFields aktivieren oder deaktivieren
• anpassen, welcher Anteil des Anforderungs- oder Antworttexts protokolliert wird
• benutzerdefinierte Felder zu Protokollen hinzufügen

Registrieren Sie eine IHttpLoggingInterceptor-Implementierung, indem Sie AddHttpLoggingInterceptor<T> in Program.cs aufrufen. Wenn mehrere IHttpLoggingInterceptor-Instanzen registriert sind, werden sie in der registrierten Reihenfolge ausgeführt.

Das folgende Beispiel zeigt, wie Sie eine IHttpLoggingInterceptor-Implementierung registrieren:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpLogging(logging =>
{
    logging.LoggingFields = HttpLoggingFields.Duration;
});
builder.Services.AddHttpLoggingInterceptor<SampleHttpLoggingInterceptor>();

Das folgende Beispiel ist eine IHttpLoggingInterceptor-Implementierung, die:

• die Anforderungsmethode untersucht und die Protokollierung für POST-Anforderungen deaktiviert
• Für Nicht-POST-Anforderungen:
  • den Anforderungspfad, die Anforderungsheader und die Antwortheader bearbeitet
  • den Anforderungs- und Antwortprotokollen benutzerdefinierte Felder und Feldwerte hinzufügt

using Microsoft.AspNetCore.HttpLogging;

namespace HttpLoggingSample;

internal sealed class SampleHttpLoggingInterceptor : IHttpLoggingInterceptor
{
    public ValueTask OnRequestAsync(HttpLoggingInterceptorContext logContext)
    {
        if (logContext.HttpContext.Request.Method == "POST")
        {
            // Don't log anything if the request is a POST.
            logContext.LoggingFields = HttpLoggingFields.None;
        }

        // Don't enrich if we're not going to log any part of the request.
        if (!logContext.IsAnyEnabled(HttpLoggingFields.Request))
        {
            return default;
        }

        if (logContext.TryDisable(HttpLoggingFields.RequestPath))
        {
            RedactPath(logContext);
        }

        if (logContext.TryDisable(HttpLoggingFields.RequestHeaders))
        {
            RedactRequestHeaders(logContext);
        }

        EnrichRequest(logContext);

        return default;
    }

    public ValueTask OnResponseAsync(HttpLoggingInterceptorContext logContext)
    {
        // Don't enrich if we're not going to log any part of the response
        if (!logContext.IsAnyEnabled(HttpLoggingFields.Response))
        {
            return default;
        }

        if (logContext.TryDisable(HttpLoggingFields.ResponseHeaders))
        {
            RedactResponseHeaders(logContext);
        }

        EnrichResponse(logContext);

        return default;
    }

    private void RedactPath(HttpLoggingInterceptorContext logContext)
    {
        logContext.AddParameter(nameof(logContext.HttpContext.Request.Path), "RedactedPath");
    }

    private void RedactRequestHeaders(HttpLoggingInterceptorContext logContext)
    {
        foreach (var header in logContext.HttpContext.Request.Headers)
        {
            logContext.AddParameter(header.Key, "RedactedHeader");
        }
    }

    private void EnrichRequest(HttpLoggingInterceptorContext logContext)
    {
        logContext.AddParameter("RequestEnrichment", "Stuff");
    }

    private void RedactResponseHeaders(HttpLoggingInterceptorContext logContext)
    {
        foreach (var header in logContext.HttpContext.Response.Headers)
        {
            logContext.AddParameter(header.Key, "RedactedHeader");
        }
    }

    private void EnrichResponse(HttpLoggingInterceptorContext logContext)
    {
        logContext.AddParameter("ResponseEnrichment", "Stuff");
    }
}

Mit diesem Interceptor generiert eine POST-Anforderung keine Protokolle, auch wenn die HTTP-Protokollierung so konfiguriert ist, dass HttpLoggingFields.All protokolliert wird. Eine GET-Anforderung generiert Protokolle, die dem folgenden Beispiel ähneln:

info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[1]
      Request:
      Path: RedactedPath
      Accept: RedactedHeader
      Host: RedactedHeader
      User-Agent: RedactedHeader
      Accept-Encoding: RedactedHeader
      Accept-Language: RedactedHeader
      Upgrade-Insecure-Requests: RedactedHeader
      sec-ch-ua: RedactedHeader
      sec-ch-ua-mobile: RedactedHeader
      sec-ch-ua-platform: RedactedHeader
      sec-fetch-site: RedactedHeader
      sec-fetch-mode: RedactedHeader
      sec-fetch-user: RedactedHeader
      sec-fetch-dest: RedactedHeader
      RequestEnrichment: Stuff
      Protocol: HTTP/2
      Method: GET
      Scheme: https
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[2]
      Response:
      Content-Type: RedactedHeader
      MyResponseHeader: RedactedHeader
      ResponseEnrichment: Stuff
      StatusCode: 200
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[4]
      ResponseBody: Hello World!
info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[8]
      Duration: 2.2778ms

Rangfolge der Protokollierungskonfiguration

Die folgende Liste zeigt die Rangfolge für die Protokollierungskonfiguration:

1. Die globale Konfiguration von HttpLoggingOptions wird durch Aufrufen von AddHttpLogging festgelegt.
2. Die endpunktspezifische Konfiguration aus dem Attribut [HttpLogging] oder der Erweiterungsmethode WithHttpLogging überschreibt die globale Konfiguration.
3. IHttpLoggingInterceptor wird mit den Ergebnissen aufgerufen und kann die Konfiguration pro Anforderung weiter ändern.