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_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 之前： 不支援。

備註

事件取用者應：

  1. 將這個結構的記憶體初始化為零。
  2. 如果從 ETL 檔案讀取， 請將 LogFileName 設定為檔案的路徑。 否則 (亦即，如果從即時會話讀取) ，請將 LoggerName 設定為會話的名稱，並將 ProcessTraceMode 設定為 PROCESS_TRACE_MODE_REAL_TIME 。
  3. 如果使用 EventRecordCallback (建議) ，請將 EventRecordCallback 設定為事件記錄回呼函式的位址、將 CoNtext 設定為要提供給回呼的值，並將 新增 PROCESS_TRACE_MODE_EVENT_RECORD 至 ProcessTraceMode。 否則 (亦即，如果使用 EventCallback) ，請將 EventCallback 設定為事件回呼函式的位址。
  4. 如果您在處理每個緩衝區之後需要回呼，請將 BufferCallback 設定為緩衝區回呼函式的位址。
  5. 如果您想要原始原始時間戳記資料，而不是已處理的時間戳記，請將 新增 PROCESS_TRACE_MODE_RAW_TIMESTAMP 至 ProcessTraceMode。
  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