PEVENT_RECORD_CALLBACK回呼函式 (evntrace.h)

發行項
03/11/2023

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

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

語法

PEVENT_RECORD_CALLBACK PeventRecordCallback;

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

參數

[in] EventRecord

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

傳回值

無

備註

若要指定 ETW 呼叫傳遞事件的函式，請設定您傳遞至OpenTrace函式之EVENT_TRACE_LOGFILE結構的EventRecordCallback、CoNtext和ProcessTraceMode成員。

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

注意

如果您的EventRecordCallback函式從ProcessTrace收到大量資料，請仔細檢查提供給OpenTrace之結構欄位中 EVENT_TRACE_LOGFILE 所指定的 ProcessTraceMode 旗標。 EVENT_TRACE_LOGFILE的 EventCallback 和 EventRecordCallback 欄位是等位的重迭成員。 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_RECORD的EventHeader.ProviderId和EventHeader.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