EnableTraceEx2

トレースセッション コントローラは、EnableTraceEx2 を呼び出して ETW イベントプロバイダがトレースセッションにイベントをどのようにログ記録するかを構成する。

EnableTraceEx2 TraceHandle, ProviderId, ControlCode, Level, MatchAnyKeyword, MatchAllKeyword, Timeout, EnableParameters

TraceHandle : [int] プロバイダを構成するイベントトレーシングセッションのハンドル。新しいトレースが開始されたとき、[StartTrace](/windows/win32/api/evntrace/nf-evntrace-starttracea) 関数がこのハンドルを返す。既存のトレースのハンドルを取得するには、[ControlTrace](/windows/win32/api/evntrace/nf-evntrace-controltracew) を使用してトレース名に基づいてトレースプロパティをクエリし、返された `EVENT_TRACE_PROPERTIES` データの **Wnode.HistoricalContext** フィールドからハンドルを取得する。
ProviderId : [var] 構成したいイベントプロバイダのプロバイダ ID (制御 GUID)。
ControlCode : [int] 次の制御コードのいずれかを指定できる。| 値                                      | 意味                                                                                   | | --------------------------------------- | -------------------------------------------------------------------------------------- | | **EVENT_CONTROL_CODE_DISABLE_PROVIDER** | セッション構成を更新してセッションがプロバイダからイベントを受信しないようにする。     | | **EVENT_CONTROL_CODE_ENABLE_PROVIDER**  | セッション構成を更新してセッションがプロバイダから要求されたイベントを受信できるようにする。 | | **EVENT_CONTROL_CODE_CAPTURE_STATE**    | プロバイダに状態情報をログ記録するよう要求する。                                       |
Level : [int] プロバイダに書き込ませたいイベントの最大レベルを示す値。プロバイダは通常、イベントのレベルがこの値以下であり、かつ _MatchAnyKeyword_ と _MatchAllKeyword_ の条件を満たす場合にイベントを書き込む。Microsoft はレベル 1 から 5 のセマンティクスを以下のように定義している。値が小さいほど重大なイベントを示す。各 _Level_ の値は、指定されたレベルとそれより重大なすべてのレベルを有効化する。たとえば `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_ で定義されている。
MatchAnyKeyword : [int64] プロバイダに書き込ませたいイベントのカテゴリを決定するキーワードの 64 ビット ビットマスク。プロバイダは通常、イベントのキーワード ビットがこの値で設定されたビットの **いずれか** と一致する場合、またはイベントにキーワード ビットが設定されていない場合、加えて _Level_ と _MatchAllKeyword_ の条件を満たす場合にイベントを書き込む。
MatchAllKeyword : [int64] プロバイダに書き込ませたいイベントを制限するキーワードの 64 ビット ビットマスク。プロバイダは通常、イベントのキーワード ビットがこの値で設定されたビットの **すべて** と一致する場合、またはイベントにキーワード ビットが設定されていない場合、加えて _Level_ と _MatchAnyKeyword_ の条件を満たす場合にイベントを書き込む。この値はしばしば 0 に設定される。
Timeout : [int] _Timeout_ が 0 の場合、この関数はプロバイダを非同期で構成し始め、即座に戻る (つまり、プロバイダコールバックの完了を待たずに戻る)。それ以外の場合、この関数はプロバイダの構成を開始し、構成が完了するのを待つ (すべてのプロバイダコールバックの完了を待つことを含む)。指定したタイムアウト前に構成が完了した場合、この関数は **ERROR_SUCCESS** を返す。それ以外の場合は **ERROR_TIMEOUT** を返す。無限に待機するには **INFINITE** を指定する。
EnableParameters : [var] プロバイダを有効化するために使用するトレース パラメータ。詳細は [ENABLE_TRACE_PARAMETERS](/windows/win32/api/evntrace/ns-evntrace-enable_trace_parameters) を参照。

(プラグイン / モジュール : advapi32.dll)

解説

トレースセッション コントローラは、EnableTraceEx2 を呼び出して ETW
イベントプロバイダがトレースセッションにイベントをどのようにログ記録するかを構成する。

[戻り値]
関数が成功した場合、戻り値は **ERROR_SUCCESS** となる。失敗した場合、戻り値は [system error
codes](/windows/win32/debug/system-error-codes)
のいずれかとなる。一般的なエラーとその原因を以下に示す。- **ERROR_INVALID_PARAMETER**
パラメータが正しくない。次のいずれかが該当する。- _ProviderId_ が **NULL** である。- _TraceHandle_
が **0** である。- **ERROR_TIMEOUT** 有効化コールバックの完了前にタイムアウト値が経過した。詳細は
_Timeout_ パラメータを参照。- **ERROR_INVALID_FUNCTION**
プロバイダが登録されていない場合はレベルを更新できない。- **ERROR_NO_SYSTEM_RESOURCES**
プロバイダを有効にできるトレース セッション数を超過した。- **ERROR_ACCESS_DENIED**
管理者特権を持つユーザー、`Performance Log Users`
グループのユーザー、`LocalSystem`、`LocalService`、`NetworkService`
として実行されているサービスのみが、クロス プロセス
セッションに対してイベントプロバイダを有効化できる。制限付きユーザーにイベントプロバイダを有効化する機能を付与するには、そのユーザーを
`Performance Log Users`
グループに追加するか、[EventAccessControl](/windows/desktop/api/evntcons/nf-evntcons-eventaccesscontrol)
を参照する。**Windows XP と Windows 2000:** 誰でもイベントプロバイダを有効化できる。

[備考]
イベント トレース
コントローラは、この関数を呼び出してセッションにイベントを書き込むイベントプロバイダを構成する。たとえば、コントローラはプロバイダからのイベント収集を開始する、プロバイダから収集しているイベントのレベルやキーワードを調整する、またはプロバイダからのイベント収集を停止するためにこの関数を呼び出すことができる。プロバイダの有効化動作は、そのプロバイダが使用する
API によって異なる。-
[RegisterTraceGuids](/windows/win32/api/evntrace/nf-evntrace-registertraceguidsa)
を使用するプロバイダ (TMF ベースの WPP や MOF を使用するプロバイダなど) は、レガシーの有効化システム
(古くは「クラシック ETW」と呼ばれる) を使用する。レガシー プロバイダがセッションに対して有効化または再構成されると、ETW
ランタイムはプロバイダに通知し、レベル、MatchAnyKeyword マスクの下位 32 ビット、およびセッション ID
へのアクセスを提供する。プロバイダは独自のロジックを使用してどのイベントを有効化すべきかを決定し、それらのイベントを指定されたセッションに直接送信する。実行時に
ETW に送信されるイベントデータにはイベントのデコード GUID とメッセージ ID が含まれるが、イベントの制御
GUID、レベル、キーワードは含まれない。ETW
はプロバイダが必要な権限を持っていることを確認した後、イベントデータを指定されたセッションに追加する。- 制御
GUID、レベル、キーワードの情報なしにイベントが特定のセッションに直接送信されるため、ETW
はレガシーの有効化システムを使用するプロバイダに対して追加のフィルタリングやルーティングを実行できない。各イベントは最大 1
つのセッションにしかルーティングできない。-
[EventRegister](/windows/win32/api/evntprov/nf-evntprov-eventregister)
を使用するプロバイダ (マニフェスト ベースのプロバイダや TraceLogging プロバイダなど) はモダンな有効化システム
(古くは「crimson ETW」と呼ばれる) を使用する。モダン プロバイダがセッションに対して有効化または再構成されると、ETW
ランタイムはプロバイダに対してレベル、64 ビット MatchAnyKeyword マスク、64 ビット MatchAllKeyword
マスク、およびトレース コントローラが指定したカスタム プロバイダ側フィルタリング
データを通知する。プロバイダは独自のロジックを使用してどのイベントを有効化すべきかを決定する。ただし、ほとんどのプロバイダは
[EventProviderEnabled](/windows/win32/api/evntprov/nf-evntprov-eventproviderenabled)
のロジックをそのまま用いる。プロバイダは、ETW にルーティング用に有効化されたイベントを送信する。ETW
に送信されるイベントデータにはイベントの制御 GUID、メッセージ ID、レベル、キーワードが含まれる。ETW
は必要に応じて追加のフィルタリングを実行し、イベントを適切なセッションにルーティングする。- 記述情報を伴ってイベントが ETW
に送信されるため、ETW
はイベントをセッションに追加する前に追加のフィルタリングとルーティングを実行できる。適切な場合、イベントを複数のセッションにルーティングできる。
（以下省略）

情報