EVENT_TRACE_LOGFILEA 結構 (evntrace.h)

發行項
08/23/2023

EVENT_TRACE_LOGFILE結構會儲存追蹤資料來源的相關資訊。

呼叫OpenTrace時，會使用EVENT_TRACE_LOGFILE結構。使用者提供 EVENT_TRACE_LOGFILE 結構，其中包含追蹤資料來源的相關資訊， (ETL 檔案名或作用中即時記錄器會話的名稱) 、追蹤處理旗標，以及將接收追蹤資料的回呼函式。成功時， OpenTrace 會填入結構的其餘欄位，以傳回追蹤資料來源的詳細資料。

當ProcessTrace處理緩衝區時，它會使用EVENT_TRACE_LOGFILE結構叫用使用者定義的BufferCallback，以提供事件處理會話和緩衝區的相關資訊。

語法

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;

成員

LogFileName

正在處理的記錄檔名稱，如果處理來自即時追蹤會話的資料，則為 Null 。如果您要呼叫 OpenTrace 以取用記錄檔中的資料，請指定此成員的值。

呼叫 OpenTrace時，如果 LoggerName 不是Null ， 則 LogFileName 必須是 Null。

呼叫 OpenTrace時，取用事件的使用者必須具有讀取檔案的許可權。

注意

透過 LogFileName 欄位提供給 OpenTrace 的檔案名必須是完整檔案名，包括任何尾碼。某些追蹤檔案建立 API 可以無訊息方式將尾碼新增至使用者指定的檔案名。例如，如果控制器將事件記錄到私人會話， (控制器在呼叫StartTrace) 時將EVENT_TRACE_PROPERTIES的LogFileMode成員設定為EVENT_TRACE_PRI加值稅E_LOGGER_MODE，則產生的 ETL 檔案將會包含進程識別碼尾碼，例如。 mytrace.etl_123 如果檔案是使用 EVENT_TRACE_FILE_MODE_NEWFILE 模式建立，則也會發生這種情況，在此情況下，產生的 ETL 檔案會包含序號。

LoggerName

從記錄檔處理資料時，即時事件追蹤會話的名稱，或 Null 。如果您要呼叫 OpenTrace 以取用即時會話中的資料，請指定此成員的值。

呼叫 OpenTrace時，如果 LogFileName 不是Null ， 則 LoggerName 必須是 Null。

如果追蹤控制器已設定EVENT_TRACE_PROPERTIES的LogFileMode成員以包含EVENT_TRACE_REAL_TIME_MODE旗標，您只能即時取用事件。

只有具有系統管理許可權、效能記錄使用者群組中的使用者，以及以 LocalSystem、LocalService、NetworkService 執行的應用程式，才能即時取用事件。若要授與受限制的使用者即時取用事件的能力，請將事件新增至 Performance Log Users 群組或呼叫 EventAccessControl。

Windows XP 和 Windows 2000： 任何人都可以取用即時事件。

CurrentTime

在輸出上，目前時間，從 1601 年 1 月 1 日午夜起，以 100 奈秒的間隔為單位。

BuffersRead

在輸出上，已處理的緩衝區數目。

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

保留的。請勿使用。

DUMMYUNIONNAME.ProcessTraceMode

處理事件的模式。模式定義于 evntcons.h 標頭檔中。您可以指定下列一或多個模式：

PROCESS_TRACE_MODE_EVENT_RECORD

如果您想要以新的 EVENT_RECORD 格式接收事件，請指定此模式 (強烈建議您) 。若要以新格式接收事件，您必須在 EventRecordCallback 成員中指定回呼。如果您未指定此模式，您將會透過 EventCallback 成員中指定的回呼，以舊格式接收事件。

在 Windows Vista 之前： 不支援。
PROCESS_TRACE_MODE_RAW_TIMESTAMP

根據預設， ProcessTrace 會將事件的 TimeStamp 從原始原始格式 (系統時間、QPC 時間或 CPU 週期計數器) 轉換成系統時間 (100 奈秒間隔，自 1601 年 1 月 1 日 1601 年 1 月 1 日) 起算。

如果您不想在EVENT_HEADER的 TimeStamp成員中指定時間戳記值，並EVENT_TRACE_HEADER轉換成系統時間，請指定PROCESS_TRACE_MODE_RAW_TIMESTAMP旗標。如果指定此旗標，ProcessTrace會將時間戳記值保留EVENT_TRACE_PROPERTIES Wnode.ClientCoNtext成員中指定的原始格式。

在 Windows Vista 之前： 不支援。
PROCESS_TRACE_MODE_REAL_TIME

指定此模式以即時接收事件。如果 LoggerName 不是 Null，您必須指定此模式。

CurrentEvent

在輸出上，包含最後一個已處理事件的 EVENT_TRACE 結構。

LogfileHeader

輸出時， TRACE_LOGFILE_HEADER 結構，其中包含會話執行的會話和電腦的一般資訊。

BufferCallback

BufferCallback函式的指標，該函式會接收每個緩衝區 ETW 排清的緩衝區相關統計資料。 ETW 會在傳遞緩衝區中的所有事件之後呼叫此回呼。此回呼是選擇性的。

BufferSize

在輸出上，包含每個緩衝區的大小，以位元組為單位。

Filled

在輸出中，包含緩衝區中包含有效資訊的位元組數目。

EventsLost

未使用。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

ETW 針對緩衝區中的每個事件呼叫的 EventCallback 函式指標。只有當 ProcessTraceMode 欄位不包含旗標時， PROCESS_TRACE_MODE_EVENT_RECORD 才會使用此欄位。

注意

如果ProcessTraceMode欄位包含 PROCESS_TRACE_MODE_EVENT_RECORD 旗標，EventCallback欄位就會被視為EventRecordCallback。如果您的 EventCallback 收到 來自 ProcessTrace的大量資料，請確認 ProcessTraceMode 欄位不包含 PROCESS_TRACE_MODE_EVENT_RECORD 旗標。

提示

新的程式碼應該使用 EventRecordCallback ，而不是 EventCallback。 EventRecordCallback會收到包含更完整事件資訊的EVENT_RECORD，可以搭配TdhGetEventInformation等解碼 API 使用，並具有可供回呼使用的內容指標。

DUMMYUNIONNAME2.EventRecordCallback

ETW 針對緩衝區中的每個事件呼叫的 EventRecordCallback 函式指標。只有當 ProcessTraceMode 欄位包含旗標時， PROCESS_TRACE_MODE_EVENT_RECORD 才會使用此欄位。

注意

如果ProcessTraceMode欄位不包含 PROCESS_TRACE_MODE_EVENT_RECORD 旗標，EventRecordCallback欄位會被視為EventCallback。如果您的 EventRecordCallback 收到 來自 ProcessTrace的資料，請確認 ProcessTraceMode 欄位包含 PROCESS_TRACE_MODE_EVENT_RECORD 旗標。

在 Windows Vista 之前： 不支援。

IsKernelTrace

輸出時，如果此成員為 TRUE，事件追蹤會話為 NT 核心記錄器。否則，它是另一個事件追蹤會話。

Context

取用者可以在呼叫 OpenTrace時指定的內容資料。如果取用者使用EventRecordCallback取用事件，ETW 會將EVENT_RECORD結構的UserCoNtext成員設定為此值。

在 Windows Vista 之前： 不支援。

備註

事件取用者應：

將這個結構的記憶體初始化為零。
如果從 ETL 檔案讀取， 請將 LogFileName 設定為檔案的路徑。否則 (亦即，如果從即時會話讀取) ，請將 LoggerName 設定為會話的名稱，並將 ProcessTraceMode 設定為 PROCESS_TRACE_MODE_REAL_TIME 。
如果使用 EventRecordCallback (建議) ，請將 EventRecordCallback 設定為事件記錄回呼函式的位址、將 CoNtext 設定為要提供給回呼的值，並將新增 PROCESS_TRACE_MODE_EVENT_RECORD 至 ProcessTraceMode。否則 (亦即，如果使用 EventCallback) ，請將 EventCallback 設定為事件回呼函式的位址。
如果您在處理每個緩衝區之後需要回呼，請將 BufferCallback 設定為緩衝區回呼函式的位址。
如果您想要原始原始時間戳記資料，而不是已處理的時間戳記，請將新增 PROCESS_TRACE_MODE_RAW_TIMESTAMP 至 ProcessTraceMode。
呼叫 OpenTrace。請注意，如果成功， OpenTrace 函式會將來自追蹤資料來源的資訊填入此結構的成員。
使用 OpenTrace 所傳回的控制碼呼叫 ProcessTrace。
- ProcessTrace 會針對每個事件叫用事件回呼函式。
- ProcessTrace 會在完成每個緩衝區之後提供) ，並包含具有追蹤處理狀態資訊的EVENT_TRACE_LOGFILE結構的實例，則會叫用您的緩衝區回呼函式 ( 。
追蹤處理完成之後，呼叫 CloseTrace 以關閉 OpenTrace所傳回的控制碼。

注意

evntrace.h 標頭會將EVENT_TRACE_LOGFILE定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
標頭	evntrace.h

另請參閱

BufferCallback

EventRecordCallback

OpenTrace

共用方式為

EVENT_TRACE_LOGFILEA 結構 (evntrace.h)

語法

成員

備註

規格需求

另請參閱

意見反應

其他資源