EVENT_TRACE_PROPERTIES Struktur (evntrace.h)

  • Artikel

Die EVENT_TRACE_PROPERTIES-Struktur enthält Informationen zu einer Ereignisablaufverfolgungssitzung. Sie verwenden diese Struktur mit APIs wie StartTrace und ControlTrace , wenn Sie die Eigenschaften einer Sitzung definieren, aktualisieren oder abfragen.

Hinweis

Dies ist eine Struktur der Version 1. Zusätzliche Optionen werden von EVENT_TRACE_PROPERTIES_V2 unterstützt (z. B. FilterDesc und V2Options).

Syntax

typedef struct _EVENT_TRACE_PROPERTIES {
  WNODE_HEADER Wnode;
  ULONG        BufferSize;
  ULONG        MinimumBuffers;
  ULONG        MaximumBuffers;
  ULONG        MaximumFileSize;
  ULONG        LogFileMode;
  ULONG        FlushTimer;
  ULONG        EnableFlags;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG        NumberOfBuffers;
  ULONG        FreeBuffers;
  ULONG        EventsLost;
  ULONG        BuffersWritten;
  ULONG        LogBuffersLost;
  ULONG        RealTimeBuffersLost;
  HANDLE       LoggerThreadId;
  ULONG        LogFileNameOffset;
  ULONG        LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

Member

Wnode

Eine WNODE_HEADER-Struktur . Sie müssen die Elemente BufferSize, Flags und Guid angeben. Optional können Sie das ClientContext-Element angeben.

BufferSize

Für jeden Sitzungspuffer für die Ereignisablaufverfolgung zugewiesener Arbeitsspeicher. Die Mindestpuffergröße beträgt 4 (4 KB). Die maximale Puffergröße beträgt 16384 (16 MB). Die meisten Ablaufverfolgungssitzungen sollten eine Puffergröße von mindestens 64 KB verwenden, um zu vermeiden, dass Arbeitsspeicher und Speicherplatz ungenutzt werden. Vor Windows 8: Die maximale Puffergröße beträgt 1024 (1 MB).

Kleinere Puffergrößen reduzieren die Sitzungsspeicherauslastung und können die Protokolldateigröße verringern. Größere Puffergrößen unterstützen die Sammlung größerer Ereignisse, da ETW Ereignisse nicht über Puffergrenzen hinweg fragmentiert und daher keine Ereignisse sammeln kann, die größer als die Puffergröße sind. In Szenarien mit extrem hohem Datendurchsatz können auch größere Puffergrößen den CPU-Mehraufwand reduzieren.

  • Eine Sitzung mit kleinen Ereignissen und einer niedrigen Ereignisrate (einige KB/s) sollte eine kleine Puffergröße (4 KB bis 16 KB) verwenden.
  • Eine Sitzung mit kleinen Ereignissen und einer moderaten Ereignisrate sollte eine mittlere Puffergröße (16 KB bis 32 KB) verwenden.
  • Eine Sitzung mit großen Ereignissen oder einer hohen Ereignisrate (einige MB/s) sollte eine große Puffergröße (64 KB bis 128 KB) verwenden.
  • In seltenen Fällen, in denen eine große Menge an Arbeitsspeicher für eine Diagnoseablaufverfolgung mit Hunderten von Megabyte Daten pro Sekunde reserviert werden sollte, kann eine große Puffergröße (256 KB bis 1024 KB) den CPU-Mehraufwand reduzieren.

Hinweis

Unabhängig von der Puffergröße kann ETW keine Ereignisse sammeln, die größer als 64 KB sind.

ETW kann die angeforderte BufferSize in bestimmten Szenarien nach oben anpassen. Beim Schreiben einer Ablaufverfolgungsdatei auf einen Datenträger kann ETW beispielsweise die Puffergröße auf ein Vielfaches der physischen Blockgröße des Datenträgers erhöhen.

Wichtig

BufferSize ist einer der wichtigsten Parameter für eine Ablaufverfolgungssitzung. Große Puffer verschwenden in der Regel Arbeitsspeicher und Speicherplatz. Ablaufverfolgungssitzungen mit großen Puffern (256 KB oder größer) sollten nur für Diagnoseuntersuchungen oder Tests verwendet werden, nicht für die Produktionsablaufverfolgung.

Tipp

Verwenden Sie BufferSize nicht, um die Speicherauslastung der Ablaufverfolgungssitzung zu steuern. Wählen Sie stattdessen die Puffergröße basierend auf der Ereignisgröße und Ereignisrate Ihrer Sitzung aus, und verwenden Sie dann die Parameter MinimumBuffers und MaximumBuffers , um die Sitzungsspeicherauslastung anzupassen.

MinimumBuffers

Mindestanzahl von Puffern, die für den Pufferpool der Ablaufverfolgungssitzung reserviert sind.

ETW kann diesen Wert in bestimmten Szenarien anpassen.

  • Wenn der Protokollierungsmodus das EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING Flag enthält, reserviert ETW mindestens 2 Puffer.
  • Wenn der Protokollierungsmodus das EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING Flag nicht enthält, reserviert ETW mindestens 2 Puffer für jeden logischen Prozessor.
  • Wenn dieser Wert größer als ein ETW-festgelegtes Limit ist, kann ETW ihn auf den Grenzwert reduzieren, um eine übermäßige Arbeitsspeicherauslastung zu vermeiden.

Bei Dateimodus- und Echtzeitablaufverfolgungen mit moderaten Ereignisraten sollten die meisten Benutzer die Arbeitsspeicherauslastung minimieren, indem sie MinimumBuffers auf 0 oder auf ein kleines Minimum festlegen (z. B. 4 oder 8), sodass ETW den Wert basierend auf der Anzahl der Prozessoren nach oben anpassen kann. ETW reserviert die (angepasste) Mindestanzahl von Puffern, wenn die Ablaufverfolgung gestartet wird. Wenn die Puffer schneller gefüllt werden, als sie verarbeitet werden können, versucht ETW, zusätzliche Puffer bis zu der von MaximumBuffers angegebenen Zahl zuzuweisen.

Für Ablaufverfolgungen im Puffermodus (zirkuläre Speichervorgänge) sollten Benutzer den Parameter MinimumBuffers entsprechend der Gesamtmenge des Arbeitsspeichers festlegen, die ETW für die Sitzung reservieren soll. Dies wird in der Regel basierend auf der erwarteten Ereignisrate und der Zeitspanne berechnet, die die Ablaufverfolgung abdecken soll. Wenn Sie beispielsweise eine Datenrate von 16 KB pro Sekunde erwarten und ihre Ablaufverfolgung mindestens 60 Sekunden Daten aufzeichnen soll, benötigen Sie 960 KB. Bei einer Puffergröße von 32 KB würden Sie MinimumBuffers auf 30 (960 KB gesamt / 32 KB pro Puffer = 30 Puffer) festlegen. ETW reserviert die (angepasste) Mindestanzahl von Puffern, wenn die Ablaufverfolgung gestartet wird. Wenn alle Puffer gefüllt sind, verwendet ETW den ältesten gefüllten Puffer für neue Ereignisse wieder. Beachten Sie, dass ETW keine zusätzlichen Puffer ordnet (ETW ignoriert MaximumBuffers für Puffermodusablaufverfolgungen).

MaximumBuffers

Maximale Anzahl von Puffern, die für den Pufferpool der Ablaufverfolgungssitzung zugewiesen werden sollen.

ETW kann diesen Wert in bestimmten Szenarien anpassen.

  • Wenn dieser Wert kleiner als der angepasste Wert von MinimumBuffers ist, kann ETW ihn auf einen geeigneten Wert erhöhen, der mindestens MindestensBuffers entspricht.
  • Wenn dieser Wert größer als ein ETW-festgelegter Grenzwert ist, kann ETW ihn auf den Grenzwert reduzieren.

Die meisten Benutzer sollten mit der Optimierung ihrer Sitzung beginnen, indem Sie MinimumBuffers und MaximumBuffers auf denselben Wert festlegen. Sie können dann den Wert von MaximumBuffers erhöhen, wenn die Ablaufverfolgung Ereignisse während Ereignisratespitzen abwirft.

ETW kann keine Bedarfspuffer zuordnen, wenn das Ereignis von einem Treiber generiert wird, der mit hoher IRQL-Auslastung ausgeführt wird. Wenn Ihre Ablaufverfolgungssitzung Ereignisse von Anbietern mit hohem IRQL-Kernelmodus aufzeichnen muss, muss sie möglicherweise einen höheren Wert von MinimumBuffers verwenden, um zu erzwingen, dass die Puffer vorab zugeordnet werden.

Hinweis

ETW ignoriert MaximumBuffers für Puffermodussitzungen (Sitzungen, die den Protokollierungsmodus EVENT_TRACE_BUFFERING_MODEenthalten). Puffermodussitzungen weisen immer MinimumBuffers am Anfang der Ablaufverfolgungssammlung zu und weisen niemals zusätzliche Puffer zu.

MaximumFileSize

Maximale Größe der Datei, die zum Protokollieren von Ereignissen verwendet wird, in Megabyte oder null für keine Größenbegrenzung. In der Regel verwenden Sie dieses Element, um die Größe einer kreisförmigen Protokolldatei einzuschränken, wenn Sie LogFileMode auf EVENT_TRACE_FILE_MODE_CIRCULARfestlegen. Dieses Element muss auf einen wert ohne Zero festgelegt werden, wenn LogFileMode oder EVENT_TRACE_FILE_MODE_CIRCULAREVENT_TRACE_FILE_MODE_NEWFILEenthältEVENT_TRACE_FILE_MODE_PREALLOCATE.

Wenn Sie das Systemlaufwerk (das Laufwerk mit dem Betriebssystem) für die Protokollierung verwenden, sucht ETW nach zusätzlichen 200 MB Speicherplatz, unabhängig davon, ob Sie den Parameter für die maximale Dateigröße verwenden. Wenn Sie daher 100 MB als maximale Dateigröße für die Ablaufverfolgungsdatei auf dem Systemlaufwerk angeben, müssen Sie 300 MB freien Speicherplatz auf dem Laufwerk haben.

LogFileMode

Protokollierungsflags für die Ereignisablaufverfolgungssitzung. Mit diesem Member geben Sie an, ob Ereignisse in einen Speicherkreispuffer, eine Protokolldatei oder einen Echtzeit-Consumer geschrieben werden sollen. Sie können dieses Element auch verwenden, um andere Sitzungseigenschaften anzugeben, z. B. dass es sich bei der Sitzung um eine private Protokollierungssitzung handelt. Eine Liste der möglichen Flags finden Sie unter Konstanten des Protokollierungsmodus.

ETW puffert Ereignisse für Echtzeitsitzungen, wenn keine Echtzeit-Consumer für die Sitzung vorhanden sind. Beachten Sie, dass diese Pufferung begrenzt ist. Wenn der Grenzwert erreicht wird, werden neue Ereignisse ignoriert, und die Protokollierungsfunktionen schlagen mit STATUS_LOG_FILE_FULLfehl. Vor Windows Vista: Wenn kein Echtzeit-Consumer vorhanden ist, werden Ereignisse verworfen, und die Protokollierung wird fortgesetzt.

Starten Sie keine Echtzeitprotokollierungssitzung, es sei denn, ein Echtzeit-Consumer nutzt die Ereignisse. Eine Echtzeitsitzung ohne Consumer verschwendet Systemressourcen (CPU, Arbeitsspeicher und Speicherplatz zum Puffern der Ereignisse).

Wenn ein Consumer mit der Verarbeitung von Echtzeitereignissen beginnt, werden die gepufferten Ereignisse zuerst genutzt. Nachdem alle gepufferten Ereignisse genutzt wurden, beginnt die Sitzung mit der Meldung neuer Ereignisse.

FlushTimer

Wie oft in Sekunden alle nicht leeren Ablaufverfolgungspuffer geleert werden. Die minimale Spülzeit beträgt 1 Sekunde.

  • Für Dateimodussitzungen: Wenn FlushTimer auf 0 festgelegt wird, werden zeitbasierte Leerungen deaktiviert (flush tritt auf, wenn der Puffer gefüllt wird, wenn die Sitzung beendet wird oder wenn die Sitzung explizit geleert wird). Die meisten Dateimodusablaufverfolgungen sollten FlushTimer auf 0 festlegen, um verschwendeten Speicherplatz in der Ablaufverfolgungsdatei zu vermeiden (d. h., damit der Speicherplatz nicht beim Speichern meist leerer Puffer verschwendet wird). Sie können den Timer auf einen Wert ungleich 0 festlegen, wenn die Wahrscheinlichkeit besteht, dass die Ablaufverfolgung nicht geschlossen wird (z. B. wenn Sie sicher sein möchten, dass Ereignisse abgerufen werden, auch wenn das System abstürzt).
  • Für Echtzeitsitzungen: Wenn FlushTimer auf 0 festgelegt wird, wird ein Standardtimeout von 1 Sekunde aktiviert. In Echtzeitsitzungen sollte der Flush-Timer basierend darauf festgelegt werden, wie schnell die Daten empfangen werden müssen. Beachten Sie, dass ein höherer Timerwert den CPU-Mehraufwand für die Ablaufverfolgung verringert. Die meisten Echtzeitablaufverfolgungen sollten mit einem Timer von 5 oder 10 Sekunden beginnen und den Timer je nach Bedarf optimieren.
  • Für gepufferte Sitzungen (kreisförmige In-Memory-Sitzungen) wird FlushTimer nicht verwendet. Die Ablaufverfolgungsdaten werden nur bei Bedarf geleert (d. h. über ControlTrace in eine Datei geleert).

EnableFlags

Eine Systemprotokollierungssitzung kann EnableFlags festlegen, um anzugeben, welche SystemTraceProvider-Ereignisse in die Ablaufverfolgung einbezogen werden sollen.

Hinweis

EnableFlags ist nur für Systemprotokollierungen gültig, d. h. Ablaufverfolgungssitzungen, die mithilfe des Flags für den EVENT_TRACE_SYSTEM_LOGGER_MODE Protokolliermodus, des KERNEL_LOGGER_NAME Sitzungsnamens, der SystemTraceControlGuid Sitzungs-GUID oder der GlobalLoggerGuid Sitzungs-GUID gestartet werden.

Dieses Element kann mindestens einen der folgenden Werte enthalten. Zusätzlich zu den von Ihnen angegebenen Ereignissen zeichnet die Protokollierung, sofern Sie nicht angeben EVENT_TRACE_FLAG_NO_SYSCONFIG, auch Hardwarekonfigurationsereignisse unter Windows XP und Systemkonfigurationsereignisse unter Windows Server 2003 oder höher auf.

DUMMYUNIONNAME

DUMMYUNIONNAME.AgeLimit

Wird nicht verwendet.

Windows 2000: Zeitverzögerung, bevor nicht verwendete Puffer freigegeben werden( in Minuten). Der Standardwert ist 15 Minuten.

DUMMYUNIONNAME.FlushThreshold

NumberOfBuffers

Bei der Ausgabe die Anzahl der Puffer, die dem Pufferpool der Ereignisablaufverfolgungssitzung zugeordnet sind.

FreeBuffers

Bei der Ausgabe die Anzahl der Puffer, die zugeordnet, aber im Pufferpool der Ereignisablaufverfolgungssitzung nicht verwendet werden.

EventsLost

Bei der Ausgabe die Anzahl der Ereignisse, die nicht aufgezeichnet wurden.

BuffersWritten

Bei der Ausgabe die Anzahl der geschriebenen Puffer.

LogBuffersLost

Bei der Ausgabe die Anzahl der Puffer, die nicht in die Protokolldatei geschrieben werden konnten.

RealTimeBuffersLost

Bei der Ausgabe die Anzahl der Puffer, die nicht in Echtzeit an den Consumer übermittelt werden konnten.

LoggerThreadId

Bei der Ausgabe der Threadbezeichner für die Ereignisablaufverfolgungssitzung.

LogFileNameOffset

Offset (in Bytes) vom Anfang des zugeordneten Arbeitsspeichers dieser Struktur bis zum Anfang der nul-terminierten Zeichenfolge, die den Namen der Protokolldatei enthält.

Der Dateiname hat normalerweise eine .etl Erweiterung. Alle Ordner im Pfad müssen bereits vorhanden sein (ETW erstellt keine Ordner für Sie). Der Pfad kann relativ, absolut, lokal oder remote sein. Umgebungsvariablen im Pfad werden nicht erweitert. Der Benutzer muss über die Berechtigung zum Schreiben in den Ordner verfügen.

Der Name der Protokolldatei ist auf 1.024 Zeichen beschränkt. Wenn Sie LogFileMode auf EVENT_TRACE_PRIVATE_LOGGER_MODE oder EVENT_TRACE_FILE_MODE_NEWFILE festlegen, achten Sie darauf, dass Sie genügend Arbeitsspeicher reservieren, um den Prozessbezeichner einzuschließen, der an den Dateinamen für private Protokollierungssitzungen angefügt wird, und die sequenzielle Nummer, die Protokolldateien hinzugefügt wird, die im neuen Dateiprotokollmodus erstellt wurden.

Wenn Sie keine Ereignisse in einer Protokolldatei protokollieren möchten (z. B. wenn Sie nur EVENT_TRACE_REAL_TIME_MODE angeben), legen Sie LogFileNameOffset auf 0 fest. Wenn Sie nur die Echtzeitprotokollierung angeben und auch einen Offset mit einem gültigen Namen der Protokolldatei angeben, verwendet ETW den Namen der Protokolldatei, um eine sequenzielle Protokolldatei und Protokollereignisse an die Protokolldatei zu erstellen, zusätzlich zum Senden der Ereignisse an Echtzeitverbraucher. ETW erstellt auch die sequenzielle Protokolldatei, wenn LogFileMode 0 ist und Sie einen Offset mit einem gültigen Protokolldateinamen bereitstellen.

Wenn Sie Ereignisse in einer Protokolldatei protokollieren möchten, müssen Sie genügend Arbeitsspeicher reservieren, damit diese Struktur den Namen der Protokolldatei und den Sitzungsnamen nach der Struktur enthält. Der Protokolldateiname muss dem Sitzungsnamen im Arbeitsspeicher folgen. Ein Beispiel finden Sie in den Anmerkungen.

Ablaufverfolgungsdateien werden mithilfe des Standardsicherheitsdeskriptors erstellt, d. h. die Protokolldatei verfügt über dieselbe ACL wie das übergeordnete Verzeichnis. Wenn Der Zugriff auf die Dateien eingeschränkt sein soll, erstellen Sie ein übergeordnetes Verzeichnis mit den entsprechenden ACLs.

LoggerNameOffset

Offset (in Bytes) vom Anfang des zugewiesenen Arbeitsspeichers der Struktur bis zum Anfang der nul-terminated-Zeichenfolge, die den Sitzungsnamen enthält.

Wichtig

Verwenden Sie einen aussagekräftigen Namen für Ihre Sitzung, damit der Besitz und die Nutzung der Sitzung anhand des Sitzungsnamens bestimmt werden können. Verwenden Sie keine GUID oder einen anderen nicht beschreibenden Wert. Fügen Sie keine zufälligen Ziffern an, um Ihren Sitzungsnamen eindeutig zu machen. ETW-Sitzungen sind eine begrenzte Ressource, sodass Ihre Komponente nicht mehrere Sitzungen starten sollte. Wenn die Sitzung Ihrer Komponente bereits ausgeführt wird, wenn Ihre Komponente startet, sollte Ihre Komponente die verwaiste Sitzung sauber, anstatt eine zweite Sitzung zu erstellen.

Der Sitzungsname ist auf 1.024 Zeichen beschränkt. Beim Sitzungsnamen wird die Groß-/Kleinschreibung nicht beachtet. Das System startet keine neue Sitzung, wenn bereits eine andere Sitzung mit demselben Namen ausgeführt wird.

Windows 2000: Bei Sitzungsnamen wird die Groß-/Kleinschreibung beachtet. Daher sind Sitzungen, deren Namen nur für den Fall abweichen, dass sie zulässig sind. Um Verwirrung zu vermeiden, sollten Sie jedoch sicherstellen, dass Ihre Sitzungsnamen eindeutig sind.

Hinweise

Wenn Sie den Arbeitsspeicher für diese Struktur zuweisen, müssen Sie genügend Arbeitsspeicher zuweisen, um den Sitzungsnamen und den Namen der Protokolldatei nach der Struktur aufzunehmen. Der Sitzungsname muss vor dem Protokolldateinamen im Arbeitsspeicher kommen. Sie müssen den Namen der Protokolldatei in den Offset kopieren, aber den Sitzungsnamen nicht in den Offset kopieren. Die StartTrace-Funktion kopiert den Namen für Sie.

Stellen Sie sicher, dass Sie den Arbeitsspeicher für diese Struktur auf Null initialisieren, bevor Sie Elemente festlegen. Beispiel:

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);

Ereignisse von Anbietern werden in die Puffer einer Sitzung geschrieben. Wenn ein Puffer in einer Datei oder Echtzeitsitzung voll ist (oder wenn der FlushTimer abläuft), löscht die Sitzung den Puffer, indem die Ereignisse entweder in eine Protokolldatei geschrieben und an einen Echtzeit-Consumer gesendet werden, oder beides. Wenn die Puffer einer Sitzung schneller gefüllt werden, als sie geleert werden können, werden neue Puffer zugeordnet und dem Pufferpool der Sitzung bis zu MaximumBuffers hinzugefügt. Über diesen Grenzwert hinaus verwirft die Sitzung eingehende Ereignisse, bis ein Puffer verfügbar ist. Jede Sitzung speichert die Anzahl der verworfenen Ereignisse (siehe EventLost-Member ).

Um Sitzungsstatistiken anzuzeigen, z. B. EventsLost , während die Sitzung ausgeführt wird, rufen Sie die ControlTrace-Funktion auf, und legen Sie den ControlCode-Parameter auf fest EVENT_TRACE_CONTROL_QUERY.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Kopfzeile evntrace.h

Weitere Informationen

StartTrace

ControlTrace

QueryAllTraces

Protokollierungsmoduskonstanten

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER