EventWriteEx 函式 (evntprov.h)

  • 發行項

寫入具有活動標識碼、選擇性相關活動標識碼、工作階段篩選條件和特殊選項的 ETW 事件。

語法

ULONG EVNTAPI EventWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

參數

[in] RegHandle

提供者的註冊句柄。 句柄來自 EventRegister。 產生的事件會使用與句柄相關聯的 ProviderId。

[in] EventDescriptor

EVENT_DESCRIPTOR事件 資訊 (元數據) ，包括標識碼、版本、層級、關鍵詞、通道、Opcode 和工作。

重要

ProviderId、Level 和 Keyword 是篩選事件的主要方法。 其他種類的篩選是可行的，但額外負荷較高。 一律將非零層級和關鍵詞指派給每個事件。

[in] Filter

64 位位掩碼值。 每個設定位都表示此事件應該從特定的追蹤會話中排除。

Filter 參數會與根據 EnableCallback的 FilterData 執行自定義事件篩選的事件提供者搭配使用。

如果您不支援自定義事件篩選，或事件應該寫入所有追蹤會話，請將 Filter 設定為零。 否則，請將 Filter 設定為不應該接收事件的會話標識符位 OR。

[in] Flags

將 [旗標] 設定為零，以進行一般事件處理。

將 旗標 設定為特殊事件處理 EVENT_WRITE_FLAG 值的組合。

  • EVENT_WRITE_FLAG_INPRIVATE (0x2)

    指出此事件應該從任何已設定 EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE 選項的記錄器中排除。

[in, optional] ActivityId

此事件的128位活動標識碼選擇性指標。 如果這是非 NULL，EventWriteEx 會針對事件的活動標識碼使用指定的值。 如果這是 NULL，EventWriteEx 會使用目前線程的活動標識碼。

追蹤處理工具可以使用事件的活動標識碼，將事件組織成稱為活動的群組。 如需活動標識碼的其他資訊，請參閱 EventActivityIdControl。

[in, optional] RelatedActivityId

128 位活動標識符的選擇性指標，這是此事件活動的父系。 如果這是非 NULL，EventWriteEx 會針對事件的相關活動標識碼使用指定的值。 如果這是 NULL，事件將不會有相關的活動識別碼。 相關活動標識碼通常會在活動的 START 事件上設定， (以 Opcode = START) 記錄的第一個事件。

追蹤處理工具可以使用事件的相關活動標識符來判斷活動之間的關聯性，例如，相關活動是新啟動活動的父系。 如需相關活動標識碼的詳細資訊，請參閱 EventActivityIdControl。

[in] UserDataCount

UserData 中的EVENT_DATA_DESCRIPTOR結構數目。 最大數目為 128。

[in, optional] UserData

UserDataCount的數位EVENT_DATA_DESCRIPTOR結構，描述要包含在事件中的數據。 如果 UserDataCount 為零，UserData 可能是 NULL。

每個 EVENT_DATA_DESCRIPTOR 都會描述事件中要包含的一個記憶體區塊。 指定的區塊會依序串連，且沒有填補或對齊方式，以形成事件內容。 如果使用以指令清單為基礎的譯碼，事件內容必須符合與指令清單中事件相關聯之範本中指定的配置。

傳回值

如果成功或錯誤碼，則傳回 ERROR_SUCCESS 。 可能的錯誤碼包括：

  • ERROR_INVALID_PARAMETER：一或多個參數無效。
  • ERROR_INVALID_HANDLE：提供者的註冊句柄無效。
  • ERROR_ARITHMETIC_OVERFLOW：事件大小大於允許的最大值， (64KB - 標頭) 。
  • ERROR_MORE_DATA：會話緩衝區大小對事件而言太小。
  • ERROR_NOT_ENOUGH_MEMORY：當填滿緩衝區嘗試排清到磁碟時發生，但磁碟 IO 的速度不夠快時發生。 當磁碟變慢且事件流量很繁重時，就會發生這種情況。 最後，沒有任何可用 (空的) 緩衝區，而且會卸除事件。
  • STATUS_LOG_FILE_FULL：即時播放檔案已滿。 事件不會記錄到會話，直到即時取用者取用來自播放檔案的事件為止。

錯誤碼主要用於偵錯和診斷案例。 大部分的生產程式代碼都應該繼續執行並繼續報告事件，即使無法撰寫 ETW 事件，發行組建通常應該忽略錯誤碼。

備註

大部分的事件提供者都不會直接呼叫 EventWriteEx 。 相反地，大部分的事件提供者都是使用 ETW 架構來實作，以包裝 對 EventRegister、 EventWriteEx 和 EventUnregister 的呼叫。 例如，您可以 撰寫事件指令清單 ，然後使用 訊息編譯 程式為事件產生 C/C++ 程式代碼，或者您可以使用 TraceLogging 來避免指令清單的需求。

EventWriteEx 會根據 RegHandle) 、Level、Keyword 和其他事件特性所決定的 ProviderId (，將事件路由傳送至適當的追蹤會話。 如果沒有追蹤會話正在錄製此事件，此函式不會執行任何動作，並傳回 ERROR_SUCCESS。

若要降低任何追蹤會話未記錄的事件效能影響，您可以呼叫 EventEnabled 來判斷任何追蹤會話是否正在記錄事件，再準備數據並呼叫 EventWriteEx。

提供者可以定義會話用來根據事件數據篩選事件的篩選。 核心篩選是以層級和關鍵詞為基礎。 事件提供者可以支援更複雜的篩選。 事件提供者可以從 EnableCallback 的 FilterData 參數接收篩選資訊。 提供者可以評估篩選，並使用 EventWriteEx 的 Filter 參數來指出特定追蹤會話未通過篩選，因此不應該收到事件。

規格需求

需求 值
最低支援的用戶端 Windows 7 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 R2 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntprov.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

EventActivityIdControl

EventRegister

EventWrite

EventWriteTransfer

撰寫以指令清單為基礎的事件。