EnableTraceEx

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

EnableTraceEx ProviderId, SourceId, TraceHandle, IsEnabled, Level, MatchAnyKeyword, MatchAllKeyword, EnableProperty, EnableFilterDesc

ProviderId : [var] 構成したいイベントプロバイダのプロバイダ ID (制御 GUID)。
SourceId : [var] この構成要求のソースを一意に識別できる GUID、またはソース ID が不要な場合は **NULL** (_SourceId_ を `&GUID_NULL` に設定するのと同等)。指定された場合、この値はプロバイダの [EnableCallback](/windows/win32/api/evntprov/nc-evntprov-penablecallback) を呼び出すときの _SourceId_ パラメータとして使用される。> [!Note] > **EnableTrace** の呼び出しとプロバイダの **EnableCallback** の対応する呼び出しとの間に、常に直接的なマッピングがあるとは限らない。たとえば、まだ登録されていないプロバイダに対して **EnableTrace** が呼び出された場合、**EnableCallback** の呼び出しは登録が発生するまで延期される。また、トレース コンシューマ セッションが停止された場合、対応する **EnableTrace** の呼び出しがなくても ETW は **EnableCallback** を呼び出す。そのような場合、**EnableTrace** は _SourceId_ が **GUID_NULL** に設定された状態で呼び出される。
TraceHandle : [int] プロバイダを構成するイベントトレーシングセッションのハンドル。新しいトレースが開始されたとき、[StartTrace](/windows/win32/api/evntrace/nf-evntrace-starttracea) 関数がこのハンドルを返す。既存のトレースのハンドルを取得するには、[ControlTrace](/windows/win32/api/evntrace/nf-evntrace-controltracew) を使用してトレース名に基づいてトレースプロパティをクエリし、返された `EVENT_TRACE_PROPERTIES` データの **Wnode.HistoricalContext** フィールドからハンドルを取得する。
IsEnabled : [int] プロバイダからのイベント受信を有効化する場合、またはプロバイダからのイベント受信時に使用する設定を調整する場合 (たとえばレベルやキーワードを変更する場合) は 1 を設定する。プロバイダからのイベント受信を無効化する場合は 0 を設定する。
Level : [int] プロバイダに書き込ませたいイベントの最大レベルを示す値。プロバイダは通常、イベントのレベルがこの値以下であり、かつ _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_ で定義されている。
MatchAnyKeyword : [int64] プロバイダに書き込ませたいイベントのカテゴリを決定するキーワードの 64 ビット ビットマスク。プロバイダは通常、イベントのキーワード ビットがこの値で設定されたビットの **いずれか** と一致する場合、またはイベントにキーワード ビットが設定されていない場合、加えて _Level_ と _MatchAllKeyword_ の条件を満たす場合にイベントを書き込む。
MatchAllKeyword : [int64] プロバイダに書き込ませたいイベントを制限するキーワードの 64 ビット ビットマスク。プロバイダは通常、イベントのキーワード ビットがこの値で設定されたビットの **すべて** と一致する場合、またはイベントにキーワード ビットが設定されていない場合、加えて _Level_ と _MatchAnyKeyword_ の条件を満たす場合にイベントを書き込む。この値はしばしば 0 に設定される。
EnableProperty : [int] ETW ランタイムがこのプロバイダからイベントを収集するときに有効化すべき特別な動作を指定するフラグ。特別な動作を有効化するには、次のフラグの 1 つ以上を指定する。それ以外の場合は _EnableProperty_ を 0 に設定する。> [!Note] > これらのフラグのいくつかは、ETW が各イベントに追加情報を含めるべきであることを示す。データはイベントの [extended data item](/windows/win32/api/evntcons/ns-evntcons-event_header_extended_data_item) セクションに書き込まれる。| 値                                         | 意味                                                                        | | ------------------------------------------ | --------------------------------------------------------------------------- | | **EVENT_ENABLE_PROPERTY_SID**              | 拡張データにユーザーのセキュリティ識別子 (SID) を含める。                   | | **EVENT_ENABLE_PROPERTY_TS_ID**            | 拡張データにターミナル セッション識別子を含める。                           | | **EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0** | トレースセッションはキーワードが 0 のイベントを記録してはならない。         |
EnableFilterDesc : [var] フィルタ データを指す [EVENT_FILTER_DESCRIPTOR](/windows/desktop/api/evntprov/ns-evntprov-event_filter_descriptor) 構造体。プロバイダはこれを使用してフィルタ条件と一致しないイベントがセッションに書き込まれないようにする。プロバイダがデータのレイアウトと、フィルタをイベントのデータにどのように適用するかを決定する。セッションはプロバイダに 1 つのフィルタのみを渡すことができる。セッションは [TdhEnumerateProviderFilters](/windows/desktop/api/tdh/nf-tdh-tdhenumerateproviderfilters) 関数を呼び出して、プロバイダが登録サポートを提供しているフィルタを調べることができる。

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

解説

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

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS となる。失敗した場合、戻り値は [system error
codes](/windows/win32/debug/system-error-codes)
のいずれかとなる。一般的なエラーとその原因を以下に示す。- **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/desktop/api/evntcons/nf-evntcons-eventaccesscontrol)
を参照する。**Windows XP と Windows 2000:** 誰でもイベントプロバイダを有効化できる。

[備考]
イベント トレース
コントローラは、この関数を呼び出してセッションにイベントを書き込むイベントプロバイダを構成する。たとえば、コントローラはプロバイダからのイベント収集を開始する、プロバイダから収集しているイベントのレベルやキーワードを調整する、またはプロバイダからのイベント収集を停止するためにこの関数を呼び出すことができる。この関数は非推奨である。追加機能のため、新しいコードでは
[EnableTraceEx2](/windows/win32/api/evntrace/nf-evntrace-enabletraceex2)
を使用すべきである。ほとんどの場合、**EnableTraceEx** の呼び出しは次のように **EnableTraceEx2**
に変換できる。
（以下省略）

情報