EnableTraceEx 関数 (evntrace.h)

[アーティクル]
08/23/2023

トレースセッションコントローラーは 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

構成するイベントプロバイダーのプロバイダー ID (コントロール GUID)。

[in, optional] SourceId

この構成要求のソースを一意に識別できる GUID。ソース ID が必要ない場合は NULL ( SourceId をに &GUID_NULL設定することと同じです)。指定した場合、プロバイダーの EnableCallback を呼び出すときに SourceId パラメーターとしてこの値が使用されます。

注意

EnableTrace の呼び出しとプロバイダーの EnableCallback への対応する呼び出しの間に、常に直接マッピングがあるとは限りません。たとえば、まだ登録されていないプロバイダーに対して EnableTrace が呼び出された場合、EnableCallback の呼び出しは登録が行われるまで延期され、トレースコンシューマーセッションが停止した場合、対応する EnableTrace の呼び出しがなかった場合でも、ETW は EnableCallback を呼び出します。このような場合、SourceId を GUID_NULL に設定して EnableTrace が呼び出されます。

[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_LEVELevntrace.h で定義されています。同等 WINMETA_LEVEL の定数は winmeta.h で定義されます。

[in] MatchAnyKeyword

プロバイダーが書き込むイベントのカテゴリを決定するキーワードの 64 ビットビットマスク。通常、プロバイダーは、イベントのキーワード (keyword) ビットがこの値に設定されているビットのいずれかと一致する場合、または Level と MatchAllKeyword の条件を満たすだけでなく、イベントにキーワード (keyword)ビットが設定されていない場合にイベントを書き込みます。

[in] MatchAllKeyword

プロバイダーが書き込むイベントを制限するキーワードの 64 ビットビットマスク。通常、プロバイダーは、イベントのキーワード (keyword) ビットがこの値に設定されているすべてのビットと一致する場合、または Level 条件とMatchAnyKeyword 条件を満たすだけでなく、イベントにキーワード (keyword)ビットが設定されていない場合にイベントを書き込みます。

この値は、多くの場合、0 に設定されます。

[in] EnableProperty

このプロバイダーからイベントを収集するときに ETW ランタイムが有効にする必要がある特別な動作を指定するフラグ。特別な動作を有効にするには、次のフラグの 1 つ以上を指定します。それ以外の場合は、 EnableProperty を 0 に設定します。

注意

これらのフラグのいくつかは、ETW が各イベントに追加情報を含める必要があることを示しています。データは、イベントの拡張データ項目セクションに書き込まれます。

値	意味
EVENT_ENABLE_PROPERTY_SID	拡張データにユーザーのセキュリティ識別子 (SID) を含めます。
EVENT_ENABLE_PROPERTY_TS_ID	拡張データにターミナルセッション識別子を含めます。
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0	トレースセッションでは、キーワード (keyword)が 0 のイベントを記録しないでください。

[in, optional] EnableFilterDesc

フィルターデータを指す EVENT_FILTER_DESCRIPTOR 構造体。プロバイダーはこれを使用してデータをフィルター処理し、フィルター条件に一致しないイベントがセッションに書き込まれないようにします。プロバイダーは、データのレイアウトと、イベントのデータにフィルターを適用する方法を決定します。セッションでプロバイダーに渡すことができるフィルターは 1 つだけです。

セッションは TdhEnumerateProviderFilters 関数を呼び出して、プロバイダーがサポートを登録しているフィルターを検索できます。

戻り値

関数が成功した場合、戻り値はERROR_SUCCESS。

関数が失敗した場合、戻り値はシステムエラーコードの 1 つです。一般的なエラーとその原因を次に示します。

ERROR_INVALID_PARAMETER

次のいずれかが当てはまります。
- ProviderId が NULL です。
- TraceHandle は NULL です。
ERROR_INVALID_FUNCTION

プロバイダーが登録されていない場合、レベルを更新することはできません。
ERROR_NO_SYSTEM_RESOURCES

プロバイダーを有効にできるトレースセッションの数を超えました。
ERROR_ACCESS_DENIED

管理者特権を持つユーザー、グループ内のPerformance Log Usersユーザー、およびとして実行されているサービス、または NetworkService としてLocalSystemLocalService実行されているサービスのみが、クロスプロセスセッションに対してイベントプロバイダーを有効にすることができます。制限付きユーザーにイベントプロバイダーを有効にする機能を付与するには、それらをグループに 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
Library	Advapi32.lib
[DLL]	Advapi32.dll

EnableTraceEx 関数 (evntrace.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

フィードバック

その他のリソース