Share via

EVENT_TRACE_LOGFILEW結構 (evntrace.h)

  • 發行項

EVENT_TRACE_LOGFILE結構會儲存追蹤數據源的相關信息。

呼叫 OpenTrace 時會使用EVENT_TRACE_LOGFILE結構。 使用者提供 EVENT_TRACE_LOGFILE 結構，其中包含追蹤數據源的相關信息， (ETL 檔案的名稱，或是使用中實時記錄器會話的名稱，) 、追蹤處理旗標，以及將接收追蹤數據的回呼函式。 成功時， OpenTrace 會填入結構的其餘字段，以傳回追蹤數據源的詳細數據。

當 ProcessTrace 處理緩衝區時，它會使用EVENT_TRACE_LOGFILE結構叫用使用者定義的 BufferCallback，以提供事件處理工作階段和緩衝區的相關信息。

語法

typedef struct _EVENT_TRACE_LOGFILEW {
  LPWSTR                        LogFileName;
  LPWSTR                        LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;

成員

LogFileName

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

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

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

注意

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

LoggerName

即時事件追蹤會話的名稱，如果處理記錄檔中的數據，則為 NULL 。 如果您要呼叫 OpenTrace 以取用來自即時會話的數據，請指定這個成員的值。

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

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

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

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

CurrentTime

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

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 的 garbled 數據，請確認 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 的 garbled 數據，請確認 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 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
標頭 evntrace.h

另請參閱

BufferCallback

EventRecordCallback

OpenTrace