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.

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 .

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.

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:

1. Initialisieren Sie den Arbeitsspeicher für diese Struktur auf Null.
2. 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.
3. 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 hinzuPROCESS_TRACE_MODE_EVENT_RECORD. Andernfalls (d. h. bei Verwendung von EventCallback) legen Sie EventCallback auf die Adresse Ihrer Ereignisrückruffunktion fest.
4. Wenn Sie einen Rückruf benötigen, nachdem jeder Puffer verarbeitet wurde, legen Sie BufferCallback auf die Adresse Ihrer Pufferrückruffunktion fest.
5. Wenn Sie die ursprünglichen rohen Zeitstempeldaten anstelle des verarbeiteten Zeitstempels möchten, fügen Sie ProcessTraceMode hinzuPROCESS_TRACE_MODE_RAW_TIMESTAMP.
6. Rufen Sie OpenTrace auf. Beachten Sie, dass bei erfolgreicher Ausführung die OpenTrace-Funktion Elemente dieser Struktur mit Informationen aus der Ablaufverfolgungsdatenquelle füllt.
7. 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.
8. Rufen Sie nach Abschluss der Ablaufverfolgungsverarbeitung CloseTrace auf, um das von OpenTrace zurückgegebene Handle zu schließen.

Anforderungen

Weitere Informationen

BufferCallback

EventRecordCallback

OpenTrace