共用方式為


PEVENT_RECORD_CALLBACK回呼函式 (evntrace.h)

取用者會實作此回呼,以接收來自追蹤處理會話的事件。

PEVENT_RECORD_CALLBACK類型會定義這個回呼函式的指標。 EventRecordCallback 是應用程式定義函數名稱的預留位置。

語法

PEVENT_RECORD_CALLBACK PeventRecordCallback;

void PeventRecordCallback(
  [in] PEVENT_RECORD EventRecord
)
{...}

參數

[in] EventRecord

包含事件資訊的 EVENT_RECORD 結構的指標。

傳回值

備註

若要指定 ETW 呼叫傳遞事件的函式,請設定您傳遞至OpenTrace函式之EVENT_TRACE_LOGFILE結構的EventRecordCallbackCoNtextProcessTraceMode成員。

  • EventRecordCallback 設定為回呼函式的位址。
  • [內容] 設定為應該包含在每個EVENT_RECORD提供給回呼之UserCoNtext欄位中的值。
  • ProcessTraceMode 設定為處理追蹤時要使用的旗標。 若要使用EventRecordCallback,您必須在ProcessTraceMode值中包含PROCESS_TRACE_MODE_EVENT_RECORD

注意

如果您的EventRecordCallback函式從ProcessTrace收到大量資料,請仔細檢查提供給OpenTrace之結構欄位中 EVENT_TRACE_LOGFILE 所指定的 ProcessTraceMode 旗標。 EVENT_TRACE_LOGFILEEventCallbackEventRecordCallback 欄位是等位的重迭成員。 ProcessTraceMode如果欄位包含 PROCESS_TRACE_MODE_EVENT_RECORD 旗標,ProcessTrace將會使用EventRecordCallback函式簽章叫用您的回呼。 否則, ProcessTrace 會使用 EventCallback 函式簽章叫用您的回呼。

使用 OpenTrace 建立追蹤處理會話之後,請呼叫 ProcessTrace 函式開始接收事件。

ProcessTrace 從追蹤開始處理事件時,它可能會使用一或多個綜合事件叫用回呼,其中包含追蹤 (中繼資料的相關資料) ,而不是來自記錄事件的資料。 這些綜合事件會將 EventHeader.ProviderId 設定為 EventTraceGuid ,並根據綜合事件的內容設定 EventHeader.EventDescriptor.Opcode 。 例如,每個追蹤檔案中的第一個事件將會是包含 TRACE_LOGFILE_HEADER 資訊的 Opcode 0 綜合事件。

您收到的所有其他事件都包含提供者特定的事件資料。 您可以使用EVENT_RECORDEventHeader.ProviderIdEventHeader.EventDescriptor成員來判斷您收到的事件種類。

  • 如果事件來自已知的提供者,而且您知道資料的版面配置,您可以使用自己的系統來解碼事件。
  • 如果 EventHeader.Flags 欄位包含 EVENT_HEADER_FLAG_TRACE_MESSAGE 旗標,則事件是 WPP 訊息。 如果可用的 TMF 或 PDB 檔案 (適當的解碼資訊) ,可以使用TdhGetProperty 或 TdhGetWppProperty來解碼事件。
  • 否則,事件可能是 MOF 型、資訊清單型或 TraceLogging 事件。 如果有適當的解碼資訊可用,可以使用 TdhGetEventInformation來解碼事件。
    • 如果事件使用 MOF 型解碼, TdhGetEventInformation 會在系統的 WMI 資料存放區中尋找事件解碼資訊。
    • 如果事件使用以資訊清單為基礎的解碼,TdhGetEventInformation會尋找系統已註冊資訊清單中的事件解碼資訊,或在由TdhLoadManifest 或 TdhLoadManifestFromBinary載入每個進程解碼內容的指令清單或二進位檔中尋找事件解碼資訊。
    • 如果事件使用 TraceLogging 型解碼, TdhGetEventInformation 將會使用事件內的解碼資訊。

在大部分情況下,事件會依發生的順序傳遞至您的回呼 (時間戳記順序) 。 不過,在某些情況下,事件可能不會依原始順序傳遞。

  • 如果追蹤針對會話時間戳記使用系統時間 (,亦即追蹤會話已 properties.Wnode.ClientContext 從設定為 2) 開始,而系統時鐘會在會話收集事件時向後調整,則某些事件可能會依序傳遞。 若要避免這種情況,請將 ClientCoNtext 設定為 0,以取得預設時間戳記 (QPC 時間) 。
  • 如果使用不精確的時鐘時間戳記收集追蹤,則來自不同 CPU 的相同時間戳記的事件可能會依序傳遞。 當追蹤針對會話時間戳記使用系統時間,因為系統時間刻度,所以最常發生此情況。 透過在LogFileMode旗標中啟動會話 EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING ,可以避免此問題,但這可能會對追蹤效能造成重大負面影響。 從Windows 10開始:系統時間時鐘類型會使用GetSystemTimePreciseAsFileTime來降低此問題的可能性。
  • 如果追蹤損毀,則會使用低階 API 產生,而該 API 不會維護檔案內的預期時間戳記規則,或在寫入事件時使用時間戳覆寫選項,某些事件可能會依序傳遞。

技術詳細資料: 事件會儲存在緩衝區中。 每個緩衝區都會指派給緩衝區資料流程,通常是每個 CPU 的一個資料流程。 ProcessTrace 實作假設緩衝區中的所有事件都會依時間戳記排序,而且每個緩衝區都包含單一時間範圍的事件,該事件不會與該緩衝區資料流程中任何其他緩衝區範圍重迭。 不符合這些假設時,ProcessTrace可能會依序傳遞事件。

當即時追蹤收集會話沒有相關聯的追蹤處理會話時,系統會緩衝收集的事件,直到緩衝區已滿為止。 當追蹤處理會話連線到即時追蹤收集會話時,追蹤處理會話會接收會話的綜合事件,然後緩衝事件,然後開始接收新產生的即時事件。 如果第二個即時處理會話連線到相同的追蹤收集會話,它會收到綜合事件,而新產生的即時事件 (第二個追蹤處理會話將不會收到較舊的事件) 。

重要

從即時會話處理事件時,如果處理回呼花費太多時間來處理每個事件和事件太快,它就會落後。 系統會緩衝事件以防止資料遺失,但這會增加系統資源使用量 (,例如記憶體和磁片使用量) 。 使用會話篩選 (例如,每個提供者的層級和關鍵字篩選) 以減少傳入事件的速率,在回呼中執行早期篩選以略過不需要完整處理的事件,並將回呼優化以儘快傳回以避免封鎖處理執行緒。

如需解譯事件資料的其他詳細資料,請參閱使用 TDH 取用事件和擷取事件資料

需求

   
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 evntrace.h

另請參閱

BufferCallback

取用事件

使用 TDH 擷取事件資料

EVENT_TRACE_LOGFILE

OpenTrace

ProcessTrace