EVENT_TRACE_LOGFILEA-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_LOGFILEA {
LPSTR LogFileName;
LPSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;
Member
LogFileName
Name der verarbeiteten Protokolldatei oder NULL , wenn Daten aus einer Echtzeitablaufverfolgungssitzung verarbeitet werden. Geben Sie einen Wert für diesen Member an, wenn Sie OpenTrace aufrufen, um Daten aus einer Protokolldatei zu nutzen.
Wenn Beim Aufrufen von OpenTraceLoggerName nicht 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 ABLAUFverfolgungsdateierstellungs-APIs können dem vom Benutzer angegebenen Dateinamen unbeaufsichtigt ein Suffix hinzufügen. Wenn der Controller beispielsweise Ereignisse in einer privaten Sitzung protokolliert hat (der Controller legt beim Aufrufen von StartTrace das LogFileMode-Element von EVENT_TRACE_PROPERTIES 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 auftreten, wenn die Datei im 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 dieses Element an, wenn Sie OpenTrace aufrufen, um Daten aus einer Echtzeitsitzung zu nutzen.
Wenn LogFileName beim Aufrufen von OpenTrace nicht 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 er das EVENT_TRACE_REAL_TIME_MODE-Flag enthält.
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 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 mindestens einen 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 nicht im TimeStamp-Element von EVENT_HEADER und in Systemzeit konvertiert EVENT_TRACE_HEADER soll. Wenn dieses Flag angegeben ist, belässt ProcessTrace den Zeitstempelwert im 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
In der Ausgabe eine EVENT_TRACE Struktur, die das zuletzt verarbeitete Ereignis enthält.
LogfileHeader
Bei der Ausgabe 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 in der Ausgabe die Größe jedes Puffers in Bytes.
Filled
Enthält in 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, vergewissern Sie sich, dass das Feld ProcessTraceMode das Flag nicht enthält PROCESS_TRACE_MODE_EVENT_RECORD .
Tipp
Neuer Code sollte EventRecordCallback anstelle von EventCallback verwenden. EventRecordCallback empfängt eine EVENT_RECORD die vollständigere Ereignisinformationen enthält, kann mit Decodierungs-APIs wie TdhGetEventInformation verwendet werden und verfügt über einen Kontextzeiger, der von Ihrem 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 EventRecordCallback-Feld wird als EventCallback behandelt, wenn das Feld ProcessTraceMode das Flag nicht enthält PROCESS_TRACE_MODE_EVENT_RECORD . Wenn Ihr EventRecordCallback unzutreffende Daten von ProcessTrace empfängt, vergewissern Sie sich, dass das Feld ProcessTraceMode das PROCESS_TRACE_MODE_EVENT_RECORD Flag enthält.
Vor Windows Vista: Nicht unterstützt.
IsKernelTrace
Wenn dieser Member true ist, ist die Ereignisablaufverfolgungssitzung bei der Ausgabe 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
Ereignisverbraucher sollten Folgendes ausführen:
- 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 (d. h. beim Lesen aus einer Echtzeitsitzung) legen Sie LoggerName auf den Namen der Sitzung fest, und legen Sie ProcessTraceMode auf fest
PROCESS_TRACE_MODE_REAL_TIME. - Wenn Sie EventRecordCallback verwenden (empfohlen), 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 (d. h. 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 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 fü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 (sofern angegeben) nach Abschluss jedes Puffers auf 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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Kopfzeile | evntrace.h |