W3CLogger in ASP.NET Core

W3CLogger ist eine Middleware, die Protokolldateien im W3C-Standardformat schreibt. Die Protokolle enthalten Informationen zu HTTP-Anforderungen und HTTP-Antworten. W3CLogger stellt Protokolle hiervon bereit:

  • HTTP-Anforderungsinformationen
  • Allgemeine Eigenschaften
  • Header
  • HTTP-Antwortinformationen
  • Metadaten zum Anforderungs-/Antwortpaar (Startdatum/-uhrzeit, Dauer)

W3CLogger ist in verschiedenen Szenarien nützlich, wie etwa:

  • Aufzeichnen von Informationen zu eingehenden Anforderungen und Antworten.
  • Filtern, welche Teile der Anforderung und Antwort protokolliert werden.
  • Filtern, welche Header protokolliert werden sollen.

W3CLogger kann die Leistung einer App beeinträchtigen. Berücksichtigen Sie die Auswirkungen auf die Leistung, wenn Sie die zu protokollierenden Felder auswählen. Die Leistung wird umso stärker beeinträchtigt, je mehr Eigenschaften Sie protokollieren. Testen Sie die Auswirkungen der ausgewählten Protokollierungseigenschaften auf die Leistung.

Warnung

W3CLogger kann potenziell personenbezogene Informationen (Personally Identifiable Information, PII) protokollieren. Berücksichtigen Sie das Risiko, und vermeiden Sie die Protokollierung vertraulicher Informationen. Standardmäßig werden Felder, die PII enthalten könnten, nicht protokolliert.

Aktivieren von W3CLogger

W3CLogger wird mit UseW3CLogging aktiviert, wodurch die W3CLogger-Middleware hinzugefügt wird.

app.UseW3CLogging();

app.UseRouting();

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

app.Run();

Standardmäßig protokolliert W3CLogger allgemeine Eigenschaften wie Pfad, Statuscode, Datum, Uhrzeit und Protokoll. Alle Informationen zu einem einzelnen Anforderungs-/Antwortpaar werden in die gleiche Zeile geschrieben.

#Version: 1.0
#Start-Date: 2021-09-29 22:18:28
#Fields: date time c-ip s-computername s-ip s-port cs-method cs-uri-stem cs-uri-query sc-status time-taken cs-version cs-host cs(User-Agent) cs(Referer)
2021-09-29 22:18:28 ::1 DESKTOP-LH3TLTA ::1 5000 GET / - 200 59.9171 HTTP/1.1 localhost:5000 Mozilla/5.0+(Windows+NT+10.0;+WOW64)+AppleWebKit/537.36+(KHTML,+like+Gecko)+Chrome/93.0.4577.82+Safari/537.36 -
2021-09-29 22:18:28 ::1 DESKTOP-LH3TLTA ::1 5000 GET / - 200 0.1802 HTTP/1.1 localhost:5000 Mozilla/5.0+(Windows+NT+10.0;+WOW64)+AppleWebKit/537.36+(KHTML,+like+Gecko)+Chrome/93.0.4577.82+Safari/537.36 -
2021-09-29 22:18:30 ::1 DESKTOP-LH3TLTA ::1 5000 GET / - 200 0.0966 HTTP/1.1 localhost:5000 Mozilla/5.0+(Windows+NT+10.0;+WOW64)+AppleWebKit/537.36+(KHTML,+like+Gecko)+Chrome/93.0.4577.82+Safari/537.36 -

W3CLogger-Optionen

Zum Konfigurieren der W3CLogger-Middleware rufen Sie AddW3CLogging in ConfigureServices auf.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});

LoggingFields

W3CLoggerOptions.LoggingFields ist eine Bitflagenumeration, die bestimmte Teile der Anforderung und Antwort für die Protokollierung sowie andere Informationen zur Verbindung konfiguriert. LoggingFields schließt standardmäßig alle möglichen Felder außer UserName und Cookie ein.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});
Flag Beschreibung Wert
Keine Keine Protokollierung. 0x0
Date Das Datum, an dem die Aktivität aufgetreten ist. 0x1
Time Die Uhrzeit, zu der die Aktivität aufgetreten ist. 0x2
ClientIpAddress Die IP-Adresse des Clients, der auf den Server zugegriffen hat. 0x4
UserName Der Name des authentifizierten Benutzers, der auf den Server zugegriffen hat. 0x8
ServerName Der Name des Servers, auf dem der Protokolleintrag generiert wurde. 0x10
ServerIpAddress Die IP-Adresse des Servers, auf dem der Protokolleintrag generiert wurde. 0x20
ServerPort Die Nummer des Ports, mit dem der Client verbunden ist. 0x40
Method Anforderung Method. 0x80
UriStem Der Anforderungspfad, der sowohl Path als auch PathBase enthält. 0x100
UriQuery Anforderung QueryString. 0x200
ProtocolStatus Antwort StatusCode. 0x400
TimeTaken Die Dauer der Aktion in Millisekunden. 0x800
ProtocolVersion Anforderung Protocol. 0x1000
Host Anforderung Microsoft.AspNetCore.Http.Headers.HeaderNames.Host. 0x2000
UserAgent Anforderung Microsoft.AspNetCore.Http.Headers.HeaderNames.UserAgent. 0x4000
Cookie Anforderung Microsoft.AspNetCore.Http.Headers.HeaderNames.Cookie. 0x8000
Referer Anforderung Microsoft.AspNetCore.Http.Headers.HeaderNames.Referer. 0x10000
ConnectionInfoFields Flag zur Protokollierung einer Sammlung von Eigenschaften zur HTTP-Verbindung, darunter ClientIpAddress, ServerIpAddress und ServerPort. ClientIpAddress | ServerIpAddress | ServerPort
RequestHeaders Flag zur Protokollierung einer Sammlung von Anforderungsheadern, darunter Host, Referer und UserAgent. Host | Referer | UserAgent
Request Flag zur Protokollierung einer Sammlung von Eigenschaften der Anforderung, darunter UriStem, UriQuery, ProtocolVersion, Method und RequestHeaders. UriStem | UriQuery | ProtocolVersion | Method | RequestHeaders
All Flag zur Protokollierung aller möglichen Felder. Date | Time | ServerName | Method | UriStem | UriQuery | ProtocolStatus | TimeTaken | ProtocolVersion | Host | UserAgent | Referer | ConnectionInfoFields | UserName | Cookie

FileSizeLimit

Maximale Größe der Protokolldatei in Bytes. Der Standardwert ist 10 MiB.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});

RetainedFileCountLimit

Maximale Anzahl Dateien pro Anwendung, die auf dem Datenträger gespeichert werden sollen, bevor das rollierende Schema einsetzt. Der Standardwert ist 4, begrenzt auf 10.000.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});

FileName

Präfix, das für den Protokolldateinamen verwendet werden soll. Das aktuelle Datum plus eine Dateinummer im Format {YYYYMMDD.X} wird angefügt.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});

LogDirectory

Verzeichnis, in das die Protokolldatei geschrieben wird. Der Standardwert ist ./logs/, relativ zum App-Verzeichnis.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});

FlushInterval

Der Zeitraum, nach dem Protokolle in die Protokolldatei geleert werden. Der Standardwert ist 1 Sekunde.

builder.Services.AddW3CLogging(logging =>
{
    // Log all W3C fields
    logging.LoggingFields = W3CLoggingFields.All;
    
    logging.FileSizeLimit = 5 * 1024 * 1024;
    logging.RetainedFileCountLimit = 2;
    logging.FileName = "MyLogFile";
    logging.LogDirectory = @"C:\logs";
    logging.FlushInterval = TimeSpan.FromSeconds(2);
});