EnableTraceEx 函式 (evntrace.h)
追蹤會話控制器會呼叫 EnableTraceEx ,以設定 ETW 事件提供者如何將事件記錄到追蹤會話。
此函式已過時。 EnableTraceEx2函式會取代此函式。
語法
ULONG WMIAPI EnableTraceEx(
[in] LPCGUID ProviderId,
[in, optional] LPCGUID SourceId,
[in] TRACEHANDLE TraceHandle,
[in] ULONG IsEnabled,
[in] UCHAR Level,
[in] ULONGLONG MatchAnyKeyword,
[in] ULONGLONG MatchAllKeyword,
[in] ULONG EnableProperty,
[in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);
參數
[in] ProviderId
提供者識別碼 (控制項要設定之事件提供者的 GUID) 。
[in, optional] SourceId
可以唯一識別此組態要求來源的 GUID,如果不需要任何來源識別,則為 Null , (相當於將 SourceId 設定為 &GUID_NULL
) 。 如果指定,當叫用提供者的EnableCallback時,這個值會當做SourceId參數使用。
注意
呼叫 EnableTrace 與提供者 EnableCallback的對應呼叫之間不一定有直接對應。 例如,如果針對尚未註冊的提供者呼叫 EnableTrace , 則 EnableCallback 的呼叫將會延後直到註冊發生,而且如果追蹤取用者會話已停止,ETW 仍會叫用 EnableCallback ,即使沒有 對應的 EnableTrace呼叫也一樣。 在這種情況下,會叫用 EnableTrace , 並將 SourceId 設定為 GUID_Null。
[in] TraceHandle
您要設定提供者的事件追蹤會話控制碼。
StartTrace函式會在啟動新的追蹤時傳回此控制碼。 若要取得現有追蹤的控制碼,請使用ControlTrace根據追蹤的名稱查詢追蹤屬性,然後從傳 EVENT_TRACE_PROPERTIES
回資料的Wnode.HistoricalCoNtext欄位取得控制碼。
[in] IsEnabled
設定為 1 以啟用從提供者接收事件,或調整從提供者接收事件時所使用的設定 (,例如變更層級和關鍵字) 。 設定為 0 以停用從提供者接收事件。
[in] Level
值,表示您想要提供者寫入的事件層級上限。 除了符合 MatchAnyKeyword 和 MatchAllKeyword 準則之外,提供者通常會在事件層級小於或等於此值時寫入事件。
Microsoft 定義層級 1-5 的語意,如下所示。 較低的值表示更嚴重的事件。 EnableLevel的每個值都會啟用指定的層級和所有更嚴重層級。 例如,如果您指定 TRACE_LEVEL_WARNING
,取用者將會收到警告、錯誤和重大事件。
值 | 意義 |
---|---|
TRACE_LEVEL_CRITICAL (1) | 異常結束或終止事件 |
TRACE_LEVEL_ERROR (2) | 嚴重錯誤事件 |
TRACE_LEVEL_WARNING (3) | 警告事件,例如配置失敗 |
TRACE_LEVEL_INFORMATION (4) | 非錯誤資訊事件 |
TRACE_LEVEL_VERBOSE (5) | 詳細的診斷事件 |
TRACE_LEVEL
常數定義于evntrace.h中。 對等 WINMETA_LEVEL
常數定義于 winmeta.h中。
[in] MatchAnyKeyword
64 位關鍵字遮罩,可決定您想要提供者寫入的事件類別。 除了符合 Level 和MatchAllKeyword準則之外,提供者通常會寫入事件,如果事件的關鍵字位符合此值中所設定的任何位,或事件沒有設定任何關鍵字位,則此事件通常會寫入事件。
[in] MatchAllKeyword
64 位關鍵字遮罩,可限制您想要提供者寫入的事件。 如果事件的關鍵字位符合此值中設定 的所有 位,或者事件沒有設定關鍵字位,除了符合 Level 和 MatchAnyKeyword 準則 之外,提供者通常會寫入事件。
此值經常設定為 0。
[in] EnableProperty
旗標,指定 ETW 執行時間從這個提供者收集事件時應該啟用的特殊行為。 若要啟用特殊行為,請指定下列一或多個旗標。 否則,請將 EnableProperty 設定為 0。
注意
其中數個旗標表示 ETW 應該在每個事件中包含額外的資訊。 資料會寫入事件的 擴充資料項目 區段。
值 | 意義 |
---|---|
EVENT_ENABLE_PROPERTY_SID | 在延伸資料中包含使用者的安全性識別碼 (SID) 。 |
EVENT_ENABLE_PROPERTY_TS_ID | 在擴充資料中包含終端機會話識別碼。 |
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 | 追蹤會話不應該記錄關鍵字為 0 的事件。 |
[in, optional] EnableFilterDesc
指向篩選資料的 EVENT_FILTER_DESCRIPTOR 結構。 提供者會使用此來篩選資料,以防止不符合篩選準則的事件寫入會話。 提供者會決定資料的版面配置,以及如何將篩選套用至事件的資料。 會話只能將一個篩選傳遞給提供者。
會話可以呼叫 TdhEnumerateProviderFilters 函 式,以查閱提供者已註冊支援的篩選準則。
傳回值
如果函式成功,傳回值會ERROR_SUCCESS。
如果函式失敗,傳回值就是其中一個 系統錯誤碼。 以下是一些常見的錯誤及其原因。
ERROR_INVALID_PARAMETER
以下其中一項為正確:
- ProviderId 為 Null。
- TraceHandle 為 Null。
ERROR_INVALID_FUNCTION
當提供者未註冊時,您無法更新層級。
ERROR_NO_SYSTEM_RESOURCES
超過可啟用提供者的追蹤會話數目。
ERROR_ACCESS_DENIED
只有具有系統管理許可權、群組中的
Performance Log Users
使用者,以及以LocalSystem
、LocalService
執行的服務,或NetworkService
可以啟用跨進程會話的事件提供者。 若要授與受限制的使用者啟用事件提供者的能力,請將他們新增至Performance Log Users
群組或查看 EventAccessControl。Windows XP 和 Windows 2000: 任何人都可以啟用事件提供者。
備註
事件追蹤控制器會呼叫此函式,以設定將事件寫入會話的事件提供者。 例如,控制器可能會呼叫此函式來開始從提供者收集事件、調整從提供者收集的事件層級或關鍵字,或停止從提供者收集事件。
此函式已過時。 如需其他功能,新的程式碼應該使用 EnableTraceEx2。
在大部分情況下, EnableTraceEx 的呼叫可以轉換成 EnableTraceEx2 ,如下所示:
// Obsolete:
Status =
EnableTraceEx(
ProviderId,
NULL, // SourceId
TraceHandle,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // EnableProperty
NULL); // EnableFilterDesc
// Updated equivalent code:
Status = EnableTraceEx2(
TraceHandle,
ProviderId,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // Timeout
NULL); // EnableParameters
在更複雜的案例中, EnableTraceEx 的呼叫可以轉換成 EnableTraceEx2 ,如下所示:
// Obsolete:
Status =
EnableTraceEx(
ProviderId,
SourceId,
TraceHandle,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
EnableProperty,
EnableFilterDesc);
// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
ENABLE_TRACE_PARAMETERS_VERSION_2,
EnableProperty,
0, // ControlFlags
SourceId ? *SourceId : GUID_NULL,
EnableFilterDesc,
EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
TraceHandle,
ProviderId,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // Timeout
&EnableParameters);
如需設定會話提供者之語意的其他詳細資料,請參閱 EnableTraceEx2的檔。
需求
最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | evntrace.h |
程式庫 | Advapi32.lib |
Dll | Advapi32.dll |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應