共用方式為


EVENT_TRACE_LOGFILEA 結構 (evntrace.h)

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_PROPERTIESLogFileMode成員設定為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_PROPERTIESLogFileMode成員以包含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 ,而不是 EventCallbackEventRecordCallback會收到包含更完整事件資訊的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 之前: 不支援。

備註

事件取用者應:

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

注意

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

規格需求

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

另請參閱

BufferCallback

EventRecordCallback

OpenTrace