EVENT_TRACE_LOGFILEW-Struktur (evntrace.h)
Die EVENT_TRACE_LOGFILE-Struktur speichert Informationen zu einer Ablaufverfolgungsdatenquelle.
Die EVENT_TRACE_LOGFILE-Struktur wird beim Aufrufen von OpenTrace verwendet. Der Benutzer stellt eine EVENT_TRACE_LOGFILE Struktur mit Informationen zur Ablaufverfolgungsdatenquelle (entweder den Namen einer ETL-Datei oder den Namen einer aktiven Echtzeitprotokollierungssitzung), Ablaufverfolgungsverarbeitungsflags und die Rückruffunktionen bereit, die Ablaufverfolgungsdaten empfangen. Bei Erfolg füllt OpenTrace die verbleibenden Felder der -Struktur aus, um Details zur Ablaufverfolgungsdatenquelle zurückzugeben.
Wenn ProcessTrace einen Puffer verarbeitet, ruft er den benutzerdefinierten BufferCallback mit einer EVENT_TRACE_LOGFILE-Struktur auf, um Informationen über die Ereignisverarbeitungssitzung und den Puffer bereitzustellen.
Syntax
typedef struct _EVENT_TRACE_LOGFILEW {
LPWSTR LogFileName;
LPWSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;
Member
LogFileName
Name der zu verarbeitenden Protokolldatei oder NULL , wenn Daten aus einer Echtzeitablaufverfolgungssitzung verarbeitet werden. Geben Sie einen Wert für dieses Element an, wenn Sie OpenTrace aufrufen, um Daten aus einer Protokolldatei zu nutzen.
Wenn LoggerName beim Aufrufen von OpenTrace ungleich NULL ist, muss LogFileNameNULL sein.
Beim Aufrufen von OpenTrace muss der Benutzer, der die Ereignisse nutzt, über Berechtigungen zum Lesen der Datei verfügen.
Hinweis
Der für OpenTrace über das Feld LogFileName bereitgestellte Dateiname muss der vollständige Dateiname sein, einschließlich aller Suffixe. Einige ERSTELLUNGs-APIs für Ablaufverfolgungsdateien können dem vom Benutzer angegebenen Dateinamen automatisch ein Suffix hinzufügen. Wenn der Controller beispielsweise Ereignisse in einer privaten Sitzung protokolliert hat (der Controller legt das LogFileMode-Element von EVENT_TRACE_PROPERTIES beim Aufrufen von StartTrace auf EVENT_TRACE_PRIVATE_LOGGER_MODE fest), enthält die generierte ETL-Datei ein Prozess-ID-Suffix, z. B. mytrace.etl_123.
Dies kann auch der Fall sein, wenn die Datei mit dem EVENT_TRACE_FILE_MODE_NEWFILE-Modus erstellt wurde. In diesem Fall enthält die generierte ETL-Datei eine Sequenznummer.
LoggerName
Name der Echtzeitereignisablaufverfolgungssitzung oder NULL , wenn Daten aus einer Protokolldatei verarbeitet werden. Geben Sie einen Wert für diesen Member an, wenn Sie OpenTrace aufrufen, um Daten aus einer Echtzeitsitzung zu nutzen.
Wenn LogFileName beim Aufrufen von OpenTrace ungleich NULL ist, muss LoggerNameNULL sein.
Sie können Ereignisse nur in Echtzeit nutzen, wenn der Ablaufverfolgungscontroller das LogFileMode-Element von EVENT_TRACE_PROPERTIES so festgelegt hat, dass das flag EVENT_TRACE_REAL_TIME_MODE enthalten ist.
Nur Benutzer mit Administratorrechten, Benutzer in der Gruppe Leistungsprotokollbenutzer und Anwendungen, die als LocalSystem, LocalService und NetworkService ausgeführt werden, können Ereignisse in Echtzeit nutzen. Um einem eingeschränkten Benutzer die Möglichkeit zu geben, Ereignisse in Echtzeit zu nutzen, fügen Sie sie der Gruppe Leistungsprotokollbenutzer hinzu, oder rufen Sie EventAccessControl auf.
Windows XP und Windows 2000: Jeder kann Echtzeitereignisse nutzen.
CurrentTime
Bei der Ausgabe, die aktuelle Zeit, in Intervallen von 100 Nanosekunden seit Mitternacht, 1. Januar 1601.
BuffersRead
Bei der Ausgabe die Anzahl der verarbeiteten Puffer.
DUMMYUNIONNAME
DUMMYUNIONNAME.LogFileMode
Reserviert. Darf nicht verwendet werden.
DUMMYUNIONNAME.ProcessTraceMode
Modi für die Verarbeitung von Ereignissen. Die Modi werden in der evntcons.h Headerdatei definiert. Sie können einen oder mehrere der folgenden Modi angeben:
PROCESS_TRACE_MODE_EVENT_RECORD
Geben Sie diesen Modus an, wenn Sie Ereignisse im neuen EVENT_RECORD-Format empfangen möchten (dringend empfohlen). Um Ereignisse im neuen Format zu empfangen, müssen Sie einen Rückruf im EventRecordCallback-Element angeben. Wenn Sie diesen Modus nicht angeben, erhalten Sie Ereignisse im alten Format über den im EventCallback-Member angegebenen Rückruf.
Vor Windows Vista: Nicht unterstützt.
PROCESS_TRACE_MODE_RAW_TIMESTAMP
Standardmäßig konvertiert ProcessTrace den TimeStamp des Ereignisses aus dem ursprünglichen Rohformat (Systemzeit, QPC-Zeit oder CPU-Zykluszähler) in Systemzeit (Intervalle von 100 Nanosekunden seit Mitternacht, 1. Januar 1601).
Geben Sie das flag PROCESS_TRACE_MODE_RAW_TIMESTAMP an, wenn der Zeitstempelwert im TimeStamp-Element von EVENT_HEADER nicht in die Systemzeit konvertiert EVENT_TRACE_HEADER . Wenn dieses Flag angegeben wird, belässt ProcessTrace den Zeitstempelwert in dem ursprünglichen Format, das der Controller im Wnode.ClientContext-Membervon EVENT_TRACE_PROPERTIES angegeben hat.
Vor Windows Vista: Nicht unterstützt.
PROCESS_TRACE_MODE_REAL_TIME
Geben Sie diesen Modus an, um Ereignisse in Echtzeit zu empfangen. Sie müssen diesen Modus angeben, wenn LoggerName nicht NULL ist.
CurrentEvent
Bei der Ausgabe wird eine EVENT_TRACE Struktur, die das zuletzt verarbeitete Ereignis enthält.
LogfileHeader
Bei der Ausgabe wird eine TRACE_LOGFILE_HEADER Struktur, die allgemeine Informationen über die Sitzung und den Computer enthält, auf dem die Sitzung ausgeführt wurde.
BufferCallback
Zeiger auf die BufferCallback-Funktion , die pufferbezogene Statistiken für jede Puffer-ETW-Leerung empfängt. ETW ruft diesen Rückruf auf, nachdem alle Ereignisse im Puffer übermittelt wurden. Dieser Rückruf ist optional.
BufferSize
Enthält bei der Ausgabe die Größe jedes Puffers in Byte.
Filled
Enthält bei der Ausgabe die Anzahl der Bytes im Puffer, die gültige Informationen enthalten.
EventsLost
Wird nicht verwendet.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.EventCallback
Zeiger auf die EventCallback-Funktion , die ETW für jedes Ereignis im Puffer aufruft. Dieses Feld wird nur verwendet, wenn das Feld ProcessTraceMode das Flag nicht enthält PROCESS_TRACE_MODE_EVENT_RECORD .
Hinweis
Das EventCallback-Feld wird als EventRecordCallback behandelt, wenn das Feld ProcessTraceMode das PROCESS_TRACE_MODE_EVENT_RECORD Flag enthält. Wenn Ihr EventCallback unzutreffende Daten von ProcessTrace empfängt, überprüfen Sie, ob das Feld ProcessTraceMode das PROCESS_TRACE_MODE_EVENT_RECORD Flag nicht enthält.
Tipp
Neuer Code sollte EventRecordCallback anstelle von EventCallback verwenden. EventRecordCallback empfängt eine EVENT_RECORD die umfassendere Ereignisinformationen enthält, kann mit Decodierungs-APIs wie TdhGetEventInformation verwendet werden und verfügt über einen Kontextzeiger, der vom Rückruf verwendet werden kann.
DUMMYUNIONNAME2.EventRecordCallback
Zeiger auf die EventRecordCallback-Funktion , die ETW für jedes Ereignis im Puffer aufruft. Dieses Feld wird nur verwendet, wenn das Feld ProcessTraceMode das PROCESS_TRACE_MODE_EVENT_RECORD Flag enthält.
Hinweis
Das Feld EventRecordCallback wird als EventCallback behandelt, wenn das Feld ProcessTraceMode das PROCESS_TRACE_MODE_EVENT_RECORD Flag nicht enthält. Wenn Ihr EventRecordCallback unzutreffende Daten von ProcessTrace empfängt, überprüfen Sie, ob das Feld ProcessTraceMode das PROCESS_TRACE_MODE_EVENT_RECORD Flag enthält.
Vor Windows Vista: Nicht unterstützt.
IsKernelTrace
Wenn dieser Member bei der Ausgabe TRUE ist, ist die Ereignisablaufverfolgungssitzung die NT-Kernelprotokollierung. Andernfalls handelt es sich um eine weitere Ereignisablaufverfolgungssitzung.
Context
Kontextdaten, die ein Consumer beim Aufrufen von OpenTrace angeben kann. Wenn der Consumer EventRecordCallback verwendet, um Ereignisse zu nutzen, legt ETW den UserContext-Member der EVENT_RECORD-Struktur auf diesen Wert fest.
Vor Windows Vista: Nicht unterstützt.
Hinweise
Ereignisconsumer sollten:
- Initialisieren Sie den Arbeitsspeicher für diese Struktur auf Null.
- Wenn Sie aus einer ETL-Datei lesen, legen Sie LogFileName auf den Pfad zur Datei fest.
Andernfalls (wenn Sie aus einer Echtzeitsitzung lesen), legen Sie LoggerName auf den Namen der Sitzung und ProcessTraceMode auf fest
PROCESS_TRACE_MODE_REAL_TIME. - Wenn Sie EventRecordCallback (empfohlen) verwenden, legen Sie EventRecordCallback auf die Adresse Ihrer Ereignisdatensatz-Rückruffunktion fest, legen Sie Context auf einen Wert fest, der ihrem Rückruf zur Verfügung gestellt werden soll, und fügen Sie ProcessTraceMode hinzu
PROCESS_TRACE_MODE_EVENT_RECORD. Andernfalls (bei Verwendung von EventCallback) legen Sie EventCallback auf die Adresse Ihrer Ereignisrückruffunktion fest. - Wenn Sie einen Rückruf benötigen, nachdem jeder Puffer verarbeitet wurde, legen Sie BufferCallback auf die Adresse Ihrer Pufferrückruffunktion fest.
- Wenn Sie die ursprünglichen rohen Zeitstempeldaten anstelle des verarbeiteten Zeitstempels verwenden möchten, fügen Sie ProcessTraceMode hinzu
PROCESS_TRACE_MODE_RAW_TIMESTAMP. - Rufen Sie OpenTrace auf. Beachten Sie, dass bei erfolgreicher Ausführung die OpenTrace-Funktion Elemente dieser Struktur mit Informationen aus der Ablaufverfolgungsdatenquelle ausfüllt.
- Rufen Sie ProcessTrace mit dem von OpenTrace zurückgegebenen Handle auf.
- ProcessTrace ruft ihre Ereignisrückruffunktion für jedes Ereignis auf.
- ProcessTrace ruft ihre Pufferrückruffunktion auf (sofern angegeben), nachdem die einzelnen Puffer abgeschlossen wurden, und schließt eine instance der EVENT_TRACE_LOGFILE-Struktur mit Ablaufverfolgungsverarbeitung status Informationen ein.
- Rufen Sie nach Abschluss der Ablaufverfolgungsverarbeitung CloseTrace auf, um das von OpenTrace zurückgegebene Handle zu schließen.
Hinweis
Der evntrace.h-Header definiert EVENT_TRACE_LOGFILE als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Kopfzeile | evntrace.h |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für