Einführung in Windows-Ereignisprotokoll und ETW ── Protokolle von Geschäftsanwendungen in die Standardmechanismen des Betriebssystems einordnen

Bei der Entwicklung von Geschäftsanwendungen oder Windows-Diensten in C# werden tägliche Protokolle meist bereits mit einem eigenen Dateilogger oder Bibliotheken wie Serilog und NLog geschrieben. Bedeutet das, dass Windows-Ereignisprotokoll und ETW (Event Tracing for Windows) nicht mehr gebraucht werden? Nein. Beide sind kein Ersatz für Dateiprotokolle, sondern Aufzeichnungen auf einer anderen Ebene, die Betriebsteams und Standardwerkzeuge des Betriebssystems sehen können.

Dieser Artikel ordnet die Aufgabenteilung von Dateiprotokoll, Ereignisprotokoll und ETW ein, erläutert die Umsetzung in .NET, die wichtigsten Grundlagen von ETW, die Praxis von Sammlung und Untersuchung sowie die typischen Fallstricke im Alltag.

1. Zuerst das Fazit

• Die drei Verfahren ersetzen einander nicht, sondern teilen die Arbeit auf. Dateiprotokolle dienen Entwicklern dazu, Details später nachzuvollziehen. Das Ereignisprotokoll hilft Betriebsteams sowie Standardwerkzeugen wie Ereignisanzeige und Monitoring, Störungen zu erkennen. ETW ist ein hochfrequentes Trace, das bei Performance-Untersuchungen oder schwer reproduzierbaren Fehlern bei Bedarf aktiviert wird. Die Regel lautet: alle drei gemeinsam einsetzen, aber mit unterschiedlich viel Information.
• In das Ereignisprotokoll gehören nur Start, Stopp und schwerwiegende Fehler. Werden sämtliche Logzeilen dorthin gespiegelt, gehen die für Betriebsteams wichtigen Anomalien unter. Das Dateiprotokoll bleibt detailliert, das Ereignisprotokoll wird bewusst eingegrenzt.
• Die Registrierung einer Ereignisquelle benötigt Administratorrechte. Seit Windows Vista kann EventLog.CreateEventSource ohne Administratorrechte nicht aufgerufen werden. Vermeiden Sie daher Entwürfe, die die Quelle beim ersten Zugriff zur Laufzeit registrieren; die Registrierung gehört vorab in den Installer.¹
• ETW ist keine dauerhafte Sammlung. Auch mit in EventSource definierten Ereignissen wird nichts aufgezeichnet, solange kein Abonnent wie dotnet-trace, PerfView oder ein ETW-basiertes Werkzeug zuhört. Der Provider wird nur für Performance-Analysen oder konkrete Fehleruntersuchungen angegeben und gesammelt.²
• Nachrichten werden als Vorlage, nicht durch Zeichenfolgenverkettung oder Interpolation geschrieben. Ein Aufruf wie logger.LogInformation("Order {OrderId} failed", orderId) macht OrderId als benannten Platzhalter in strukturierten Logs durchsuchbar. Verkettung und Interpolation verlieren diese Strukturinformation.³
• Übermäßig große Protokolle entstehen oft wegen der kleinen Standardgrenze. Das Ereignisprotokoll hat standardmäßig nur 512 KB. Nutzt eine Geschäftsanwendung es regelmäßig, muss die Größe ausdrücklich erhöht werden; auch das Verhalten beim Erreichen der Grenze – alte Einträge überschreiben oder neue verwerfen – gehört in die Konzeption.⁴

Die folgende Tabelle erleichtert die Entscheidung.

2. Grundlagen des Windows-Ereignisprotokolls

Windows verfügt standardmäßig über die drei Protokolle Application, System und Security; Security ist schreibgeschützt. Geschäftsanwendungen und Dienste schreiben in das Application-Protokoll oder in ein eigenes benutzerdefiniertes Protokoll beziehungsweise einen eigenen Kanal. Gerätetreiber schreiben üblicherweise in System.⁵

Die Schreibeinheit ist die „Ereignisquelle“. Eine Quelle ist ein Name, der die Anwendung identifiziert, und wird vorab mit EventLog.CreateEventSource registriert. Seit Windows Vista erfordert die Registrierung einer Quelle Administratorrechte. Um die Eindeutigkeit des Namens zu prüfen, müssen alle Ereignisprotokolle einschließlich Security durchsucht werden; Standardbenutzer können jedoch nicht auf Security zugreifen.¹

using System.Diagnostics;

// Im Installer oder Setup-Prozess ausführen, solange Administratorrechte vorhanden sind.
const string SourceName = "KomuraSoft.OrderService";
const string LogName = "Application";

if (!EventLog.SourceExists(SourceName))
{
    EventLog.CreateEventSource(SourceName, LogName);
}

Wird die Quelle erst beim ersten Zugriff zur Laufzeit erzeugt, schlägt dieser Aufruf im Betrieb fehl, sobald die Anwendung als Standardbenutzer läuft. Allgemein erläutert Wann werden unter Windows tatsächlich Administratorrechte benötigt? solche Fälle. Die Registrierung einer Ereignisquelle gehört genau dazu: Der Installer registriert die Quelle, die Anwendung selbst schreibt nur in die bereits registrierte Quelle. Das ist die sichere Architektur.

Jedes Ereignis trägt zwei Kennzeichnungen: „Level“ und „Ereignis-ID“. Das Level ist ein EventLogEntryType (Information, Warning, Error, SuccessAudit, FailureAudit); es steuert das Symbol und die Standardfilter in der Ereignisanzeige. Die Ereignis-ID ist eine ganzzahlige Anwendungskonstante und dient dazu, gleichartige Vorgänge später zu suchen und zusammenzufassen.

3. Aus .NET in das Ereignisprotokoll schreiben

Es gibt grundsätzlich zwei Wege, aus .NET in das Ereignisprotokoll zu schreiben.

3.1 System.Diagnostics.EventLog direkt verwenden

Diese API auf niedriger Ebene passt, wenn feine Steuerung benötigt wird, etwa Kategorien oder das Anhängen binärer Daten. In .NET außerhalb von .NET Framework muss das NuGet-Paket System.Diagnostics.EventLog referenziert werden.

using System.Diagnostics;

public sealed class OrderServiceEventLog
{
    private const string SourceName = "KomuraSoft.OrderService";

    public void WriteServiceStarted()
    {
        EventLog.WriteEntry(SourceName, "OrderService wurde gestartet.",
            EventLogEntryType.Information, eventID: 1000);
    }

    public void WriteFatalError(Exception ex)
    {
        EventLog.WriteEntry(SourceName,
            $"Ein schwerwiegender Fehler ist aufgetreten; die Verarbeitung kann nicht fortgesetzt werden. Details finden Sie im Dateiprotokoll. {ex.GetType().Name}: {ex.Message}",
            EventLogEntryType.Error, eventID: 1999);
    }
}

3.2 ILogger + AddEventLog verwenden

Ist strukturiertes Logging bereits über ILogger aufgebaut, fügt sich AddEventLog aus dem Paket Microsoft.Extensions.Logging.EventLog natürlicher in die vorhandene Logging-Pipeline ein. Bei ASP.NET Core und Worker Services auf Basis des Generic Host ist der EventLog-Provider unter Windows standardmäßig aktiviert.⁶

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.EventLog;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(settings =>
{
    settings.SourceName = "KomuraSoft.OrderService";
    settings.LogName = "Application";
    // Zusätzlich zum Standard-Kategoriefilter gehen nur Warning und darüber
    // ins Ereignisprotokoll; Details bleiben im Dateiprotokoll.
    settings.Filter = (_, level) => level >= LogLevel.Warning;
});

using IHost host = builder.Build();
await host.RunAsync();

Ohne EventLogSettings ist LogName standardmäßig "Application" und SourceName ".NET Runtime".⁷ Mit dieser allgemeinen Quelle lässt sich in der Ereignisanzeige kaum erkennen, ob ein Eintrag von der eigenen oder einer anderen .NET-Anwendung stammt. SourceName sollte daher immer ausdrücklich für die eigene Anwendung festgelegt werden.

Bei Windows-Diensten und Batch-Verarbeitung über die Aufgabenplanung gehören nur „Start“, „Stopp“ und „schwerwiegender Fehler“ in das Ereignisprotokoll; alle anderen Details bleiben im Dateiprotokoll. Wie Dienste aufgebaut und betrieben werden, beschreibt Windows-Dienste entwickeln und betreiben. Fehler beim Start über die Aufgabenplanung behandelt Aufgaben der Windows-Aufgabenplanung starten nicht oder enden mit 0x1. In beiden Fällen schaut das Betriebsteam bei einer Störung oft zuerst in das Ereignisprotokoll. Ob dort die wesentlichen Punkte stehen, bestimmt die Geschwindigkeit der Erstuntersuchung.

4. Was ist ETW? ── Eine Trace-Grundlage für das gesamte Betriebssystem

Event Tracing for Windows (ETW) ist ein Trace-Mechanismus, der vom Kernel bis zu Anwendungen im Benutzermodus auf einer gemeinsamen Grundlage instrumentiert werden kann. Seine besondere Stärke liegt darin, Kernelereignisse wie Datenträger-I/O oder Prozesserzeugung und eigene Anwendungsereignisse auf derselben Zeitachse gemeinsam aufzuzeichnen und zu analysieren.⁸

In .NET lässt sich ein eigener ETW-Provider durch eine Klasse definieren, die System.Diagnostics.Tracing.EventSource erbt. ETW arbeitet nach dem Publish-Subscribe-Prinzip: Ohne Abonnent werden keine Ereignisse aufgezeichnet. Allein die Implementierung von EventSource bewirkt also nichts; erst die ausdrückliche Aktivierung in einem Sammelwerkzeug zeichnet Ereignisse auf.²

using System.Diagnostics.Tracing;

[EventSource(Name = "KomuraSoft-OrderService")]
internal sealed class OrderServiceEventSource : EventSource
{
    public static readonly OrderServiceEventSource Log = new();

    [Event(1, Level = EventLevel.Informational, Message = "Bestellverarbeitung wurde gestartet. OrderId={0}")]
    public void OrderProcessingStart(string orderId)
    {
        if (IsEnabled())
        {
            WriteEvent(1, orderId);
        }
    }

    [Event(2, Level = EventLevel.Informational, Message = "Bestellverarbeitung wurde abgeschlossen. OrderId={0}")]
    public void OrderProcessingStop(string orderId)
    {
        if (IsEnabled())
        {
            WriteEvent(2, orderId);
        }
    }
}

Aufrufende Komponenten verwenden die Quelle so. Die Prüfung mit IsEnabled() vor dem eigentlichen Schreiben vermeidet Aufwand, wenn gerade keine Sammlung läuft.

OrderServiceEventSource.Log.OrderProcessingStart(order.Id);
try
{
    ProcessOrder(order);
}
finally
{
    OrderServiceEventSource.Log.OrderProcessingStop(order.Id);
}

Zum Sammeln dieser Ereignisse ist das plattformübergreifende Werkzeug dotnet-trace der einfachste Einstieg.⁹

dotnet-trace collect --providers KomuraSoft-OrderService -- OrderService.exe

Die gesammelte Datei .nettrace kann in Visual Studio oder PerfView geöffnet und untersucht werden. Für weitergehende Performance-Analysen einschließlich Kernelereignissen wird der im Windows Assessment and Deployment Kit (ADK) enthaltene Windows Performance Recorder (WPR) verwendet und die Daten im Windows Performance Analyzer (WPA) ausgewertet.¹⁰ Der Umfang dieses Artikels endet jedoch bei „Was kann ETW, und wann wird es eingesetzt?“. Detaillierte Analysen mit PerfView oder WPA bleiben außen vor. Für Entwicklung und Wartung von Geschäftsanwendungen genügt zunächst, einen eigenen Provider mit EventSource definieren und mit dotnet-trace sammeln zu können.

5. Strukturierte Logs in der Praxis

Nachrichtenvorlagen von ILogger werden als feste Zeichenfolgen mit benannten Platzhaltern der Form {PlaceHolder} geschrieben. Das ist mehr als ein Stilmittel: Bleibt die Vorlage unverändert und werden nur Argumente übergeben, kann die Logging-Infrastruktur die Beziehung zwischen Platzhaltername und Wert als strukturierte Daten bewahren.¹¹

// Empfohlen: Vorlage bleibt fest, Argumente werden getrennt übergeben.
logger.LogWarning("Reservierung des Bestands für Bestellung {OrderId} ist fehlgeschlagen. Lager={WarehouseId}", orderId, warehouseId);

// Nicht empfohlen: Verkettung oder Interpolation zerstört die Zuordnung von Vorlage und Wert.
logger.LogWarning("Reservierung des Bestands für Bestellung " + orderId + " ist fehlgeschlagen. Lager=" + warehouseId);
logger.LogWarning($"Reservierung des Bestands für Bestellung {orderId} ist fehlgeschlagen. Lager={warehouseId}");

Die Codeanalyzer-Regel CA2254 erkennt dieses nicht empfohlene Muster, bei dem sich die Vorlage bei jedem Aufruf verändert.³ In häufig aufgerufenen Hot Paths kann zusätzlich Quellgenerierung mit LoggerMessageAttribute verwendet werden, um Kosten für Boxing und die Analyse der Vorlage zu vermeiden.¹²

using Microsoft.Extensions.Logging;

internal static partial class Log
{
    [LoggerMessage(
        EventId = 2001,
        Level = LogLevel.Warning,
        Message = "Reservierung des Bestands für Bestellung {OrderId} ist fehlgeschlagen. Lager={WarehouseId}")]
    public static partial void StockReservationFailed(
        this ILogger logger, string orderId, string warehouseId);
}

// Aufrufende Komponente
logger.StockReservationFailed(orderId, warehouseId);

Mit diesem Aufbau lassen sich aus demselben Log-Aufruf detaillierte Werte in Dateiprotokolle über Sinks wie Serilog oder NLog, eingegrenzte Inhalte in das Ereignisprotokoll und kostengünstige Traces über EventSourceLoggerProvider an ETW leiten. Der Grundaufbau besteht aus mehreren registrierten ILoggerProvider-Instanzen und je Provider einer eigenen Ausgabestufe über Filter. Mindestanforderungen an einen eigenen Logger beschreibt Mindestanforderungen und Integrationstest-Checkliste für eigene Logger. Wie Logs und Dumps bei Abstürzen zusammen gespeichert werden, behandelt Logs und Dumps bei Abstürzen von Windows-Anwendungen bewahren.

6. Sammlung und Untersuchung ── Die Seite, die geschriebene Protokolle liest

In der Ereignisanzeige lassen sich aus der Protokollliste über „Filter“ oder „Benutzerdefinierte Ansicht“ nur bestimmte Quellen, Stufen oder Ereignis-IDs herausziehen. Häufig verwendete Bedingungen sollten als benutzerdefinierte Ansicht gespeichert werden, damit spätere Untersuchungen schneller gehen. Solche Ansichten werden als XPath-Abfrage definiert. Eine Abfrage, die etwa nur Ereignisse einer bestimmten Quelle auswählt, kann so aussehen.¹³

<QueryList>
  <Query Id="0" Path="Application">
    <Select Path="Application">
      *[System[Provider[@Name='KomuraSoft.OrderService'] and (Level=2 or Level=3)]]
    </Select>
  </Query>
</QueryList>

Über die Befehlszeile kann wevtutil Protokolle exportieren und ihre Einstellungen ändern. Das eignet sich auch für den Betrieb: Ereignisse rund um einen Fehlerzeitpunkt exportieren und an den Support senden.¹⁴

:: Das gesamte Application-Protokoll in eine evtx-Datei exportieren.
wevtutil epl Application C:\logs\application_20260707.evtx

:: Nur Ereignisse einer bestimmten Quelle anzeigen (die letzten 10).
wevtutil qe Application /q:"*[System[Provider[@Name='KomuraSoft.OrderService']]]" /c:10 /rd:true /f:text

Bei Absturzuntersuchungen werden Ereignisprotokoll, Dateiprotokoll und Absturz-Dump über ihre Zeitstempel zusammengeführt. Der Zeitstempel des „schwerwiegenden Fehlers“ im Ereignisprotokoll ist der Ausgangspunkt; dazu kommen die Details im Dateiprotokoll zur selben Zeit sowie ein über WER oder ProcDump erstellter Dump. Die Erfassung von Dumps erläutert Einführung in die Sammlung von Windows-Absturzdumps – WER/ProcDump/WinDbg. Die praktische Analyse erfasster Dumps beschreibt Absturzdumps mit WinDbg + SOS lesen.

7. Fallstricke

• Schreiben mit nicht registrierter Quelle schlägt fehl. Wird ein Aufruf ähnlich RegisterEventSource mit einem nicht registrierten Quellnamen ausgeführt, landet das Ereignis zwar im Application-Protokoll, aber ohne passende Nachrichtenressourcen-DLL kann die Ereignisanzeige keinen Beschreibungstext anzeigen und meldet einen Fehler.¹⁵ Versucht ein Entwurf zusätzlich, die Quelle zur Laufzeit automatisch mit CreateEventSource zu registrieren, kann der erste Start eines Prozesses ohne Administratorrechte mit einer Ausnahme scheitern. Die Quellenregistrierung muss stets im Installer abgeschlossen sein.
• Verwirrung, weil sich unter anderem Quellnamen schreiben lässt. Hat eine Anwendung Schreibrechte, kann sie Ereignisse auch unter einem anderen bereits registrierten Quellnamen schreiben, den sie nicht selbst registriert hat. Quellnamen müssen pro Rechner eindeutig sein, doch das Betriebssystem erzwingt diese Disziplin nicht; sie liegt bei der Anwendung.⁵ Allgemeine, zu kurze Namen ohne Firmen- oder Produktbezug können mit Anwendungen anderer Anbieter kollidieren oder versehentlich deren Quellen wiederverwenden.
• Protokollwachstum und Aufbewahrungsrichtlinie. Die Standardhöchstgröße des Ereignisprotokolls beträgt nur 512 KB.⁴ Nutzt eine Geschäftsanwendung es täglich, muss die Größe mit wevtutil sl oder im Installer bewusst vergrößert werden. Bei Erreichen des Limits muss klar sein, ob alte Einträge überschrieben oder neue verworfen werden. OverwriteOlder ist veraltet und kann trotz Angabe praktisch zu „nicht überschreiben“ führen; auch das gehört in die Entscheidung.¹⁶
• Nachrichtenanzeige in mehrsprachigen Umgebungen. Bei lokalisierten Nachrichtenressourcendateien (MessageResourceFile) kann die Ereignisanzeige „Die Beschreibung für Ereignis-ID … wurde nicht gefunden“ anzeigen, wenn die Ressourcen-DLL fehlt oder eine andere Version hat. Das tritt leicht auf, wenn ein exportiertes Ereignisprotokoll auf einem anderen Server gelesen wird oder nach der Deinstallation nur das Protokoll zurückbleibt. Werden Zeichenfolgen direkt mit WriteEntry geschrieben und keine Ressourcendatei verwendet, entsteht dieses Problem nicht.
• Schreiben scheitert wegen fehlender Berechtigungen. Häufig wird übersehen: Die Registrierung der Quelle benötigt Administratorrechte, das Schreiben in eine bereits registrierte Quelle kann dagegen auch ein Standardbenutzer. Bevor eine ganze Anwendung voreilig mit Administratorrechten ausgeführt wird, muss geklärt werden, welche konkrete Operation die Berechtigung tatsächlich verlangt.

Verwandte Artikel

• Wann werden unter Windows tatsächlich Administratorrechte benötigt? ── UAC, geschützte Bereiche und Entwurfsentscheidungen
• Windows-Dienste entwickeln und betreiben ── Von der Abgrenzung zur Aufgabenplanung bis zu BackgroundService als Dienst
• Aufgaben der Windows-Aufgabenplanung starten nicht oder enden mit 0x1 ── Ursachen eingrenzen und sicher betreiben
• Mindestanforderungen und Integrationstest-Checkliste für eigene Logger
• Logs und Dumps bei Abstürzen von Windows-Anwendungen bewahren
• Einführung in die Sammlung von Windows-Absturzdumps – WER/ProcDump/WinDbg
• Absturzdumps mit WinDbg + SOS lesen ── Praxisleitfaden nach der Erfassung

Zugehörige Beratungsfelder

KomuraSoft unterstützt bei der Konzeption von Logs, Ereignisprotokollen und ETW-Grundlagen für Windows-Geschäftsanwendungen sowie bei der technischen Beratung zu Beobachtungspunkten für künftige Fehleruntersuchungen.

• Windows-Anwendungsentwicklung
• Fehleruntersuchung und Ursachenanalyse
• Technische Beratung und Design-Review
• Kontakt

Referenzen

Verwandte Artikel

Aktuelle Artikel mit denselben Schlagwörtern führen zu verwandten Themen weiter.

Verwandte Themen

Diese Seiten ordnen den Artikel in einen größeren Leistungs- und Entscheidungskontext ein.

Leistungen zu diesem Thema

Dieser Artikel ist direkt mit den folgenden Leistungen verbunden.

Häufige Fragen

Fragen, die in Beratungen zu diesem Artikelthema häufig gestellt werden.

Brauche ich noch ein Ereignisprotokoll, wenn ich bereits Dateiprotokolle habe?

Für detaillierte Untersuchungen reichen Dateiprotokolle häufig aus. Sollen Betriebsteams jedoch über Standardwerkzeuge wie die Ereignisanzeige oder Überwachungslösungen – etwa Fehlermeldungen der Aufgabenplanung oder SCOM – Anwendungsprobleme erkennen, ist es sinnvoll, die wesentlichen Punkte zusätzlich im Ereignisprotokoll zu erfassen. Die beiden Verfahren ersetzen einander nicht; sie sind Protokolle auf unterschiedlichen Ebenen für unterschiedliche Leser.

Wie lege ich Regeln für die Nummerierung von Ereignis-IDs fest?

Es gibt keine einzige richtige Regel. In der Praxis helfen drei Punkte: Nummernbereiche nach Funktionsgebiet trennen, etwa die 1000er für Startvorgänge und die 2000er für Kommunikation; die Bedeutung einer vergebenen ID nie ändern oder wiederverwenden; Lücken zulassen. Weil EventId von ILogger zugleich als Suchschlüssel strukturierter Logs dient, erleichtert ein später gut dokumentierbares Schema die Wartung.

Ich verwende Serilog oder NLog. Wie hängt das mit diesem Artikel zusammen?

Serilog und NLog sind Implementierungen, die unter ILogger dieselben Logeinträge an mehrere Ziele verteilen: Dateien, Ereignisprotokoll, ETW oder externes SaaS. Die hier erläuterten Grundsätze – im Ereignisprotokoll nur das Wesentliche festhalten und Nachrichtenvorlagen nicht aufbrechen – gelten sowohl bei direkter ILogger-Nutzung als auch über Serilog oder NLog. Ob ein Ereignisprotokoll-Sink wie Serilog.Sinks.EventLog oder das Standard-AddEventLog verwendet wird, ist eine Implementierungsentscheidung.

Wie viel ETW muss ich lernen?

Für Entwicklung und Wartung von Geschäftsanwendungen reicht es, einen eigenen Provider mit EventSource definieren und dessen Ereignisse mit dotnet-trace sammeln zu können. Aufrufstapelanalyse mit PerfView und Kernelereignisse mit WPR sind Themen für spezialisierte Performance-Untersuchungen; sie werden hier bewusst nicht vertieft.

Autorenprofil

Profilseite des Artikelautors.

Go Komura

Geschäftsführer von KomuraSoft LLC

Spezialisiert auf Windows-Softwareentwicklung, technische Beratung und Fehleranalyse, insbesondere bei bestehenden Systemen und schwer reproduzierbaren Störungen.