ControlTraceA 関数 (evntrace.h)

ControlTrace 関数は、指定されたイベント トレース セッションをフラッシュ、クエリ、更新、または停止します。

構文

ULONG WMIAPI ControlTraceA(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

パラメーター

TraceId

[in] InstanceName

イベント トレース セッションの名前、または NULL。 TraceHandle が 0 の場合は、InstanceName を指定する必要があります。

NT カーネル ロガー セッションを指定するには、 InstanceName をKERNEL_LOGGER_NAME に設定します。

[in, out] Properties

初期化された EVENT_TRACE_PROPERTIES 構造体へのポインター。 フィールドを設定する前に、この構造体をゼロにする必要があります。

ControlCode でEVENT_TRACE_CONTROL_STOP、EVENT_TRACE_CONTROL_QUERY、またはEVENT_TRACE_CONTROL_FLUSHが指定されている場合は、EVENT_TRACE_PROPERTIES構造体の Wnode.BufferSize、Wnode.Guid、LoggerNameOffset、LogFileNameOffset メンバーのみを設定する必要があります。 セッションがプライベート セッションの場合は、 LogFileMode も設定する必要があります。 最大セッション名 (1024 文字) と最大ログ ファイル名 (1024 文字) を使用して、バッファー サイズとオフセット (不明な場合) を計算できます。

ControlCode でEVENT_TRACE_CONTROL_UPDATEが指定されている場合、メンバーは更新するプロパティの新しい値を指定する必要があります。 出力時に、 Properties にはイベント トレース セッションのプロパティと統計情報が含まれます。 次のプロパティを更新できます。

• EnableFlags: すべてのシステム プロバイダーを無効にするには、このメンバーを 0 に設定します。 これを 0 以外の値に設定して、有効にするシステム プロバイダーまたは有効な状態を維持するシステム プロバイダーを指定します。 これは、 システム ロガーの場合にのみ 0 以外の場合があります。

• FlushTimer: バッファーをフラッシュする前に待機する時間を変更する場合は、このメンバーを設定します。 このメンバーが 0 の場合、メンバーは更新されません。

• LogFileNameOffset: 別のログ ファイルに切り替える場合、またはバッファー モードのトレースを新しいログ ファイルにフラッシュする場合は、このメンバーを設定します。 このメンバーが 0 の場合、ファイル名は更新されません。 オフセットが 0 ではなく、ログ ファイル名を変更しない場合、関数はエラーを返します。

• LogFileMode: EVENT_TRACE_REAL_TIME_MODE のオンと オフを切り替える場合は、このメンバーを設定します。 リアルタイムの消費をオフにするには、このメンバーを 0 に設定します。 リアルタイムの消費を有効にするには (ディスクに記録するセッションを作成し、リアルタイムでイベントを配信する)、このメンバーを EVENT_TRACE_REAL_TIME_MODE に設定すると、現在のモードでは OR になります。

• MaximumBuffers: ETW で使用されるバッファーの最大数を変更する場合は、このメンバーを設定します。 このメンバーが 0 の場合、メンバーは更新されません。

プライベート ロガー セッションの場合は、 LogFileNameOffset メンバーと FlushTimer メンバーのみを更新できます。

新しく初期化された EVENT_TRACE_PROPERTIES 構造体を使用している場合は、構造体をゼロにしてから、 Wnode.BufferSize、 Wnode.Guid、 Wnode.Flags、および更新する値を設定します。

EVENT_TRACE_PROPERTIES構造体 (つまり、以前に StartTrace または ControlTrace に渡した構造体を使用) を再利用する場合は、ログ ファイル名を変更しない限り、LogFileNameOffset メンバーを 0 に設定し、必ずEVENT_TRACE_PROPERTIES設定してください。WNODE_FLAG_TRACED_GUIDする Wnode.Flags。

Windows 10 バージョン 1703 以降: プロセス間のシナリオでパフォーマンスを向上させるために、システム全体のプライベート ロガーの ControlTrace にフィルター情報を渡すようになりました。 フィルター情報を含めるには、 EVENT_TRACE_PROPERTIES_V2 構造体を使用する必要があります。 詳細については、「 プライベート ロガー セッションの構成と開始 」を参照してください。

[in] ControlCode

要求された制御関数。 次のいずれかの値を指定できます。

• EVENT_TRACE_CONTROL_FLUSH: セッションのアクティブなバッファーをフラッシュします。

  これは、メモリ内セッション ( EVENT_TRACE_BUFFERING_MODE フラグで開始されたセッション) と共に使用して、トレースからファイルにデータを書き込むことができます。

  通常、ファイル ベースまたはリアルタイム セッションをフラッシュする必要はありません。ETW は、バッファーがいっぱいになったとき (つまり、次のイベントの余地がない場合)、トレース セッションの FlushTimer の有効期限が切れたとき、またはトレース セッションが閉じられたときに自動的にフラッシュされるためです。

  Windows 2000: この値はサポートされていません。

• EVENT_TRACE_CONTROL_QUERY: セッションのプロパティと統計を取得します。

• EVENT_TRACE_CONTROL_STOP: セッションを停止します。 セッション ハンドルは無効です。

• EVENT_TRACE_CONTROL_UPDATE: セッションのプロパティを更新します。

• EVENT_TRACE_CONTROL_INCREMENT_FILE: セッションに がある場合は EVENT_TRACE_FILE_MODE_NEWFILE、前のファイルがいっぱいになるのを待つのではなく、セッションを更新して次のファイルにすぐに切り替えます。 Windows 10 October 2018 Update 以降でサポートされています。

• EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: ファイル モード セッションをリアルタイム セッションに変更します (リアルタイム配信を有効にし、ETL ファイルへのイベントの書き込みを無効にします)。 Windows 10 October 2020 Update 以降でサポートされています。

戻り値

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

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

• ERROR_BAD_LENGTH

  次のいずれかが当てはまります。

  • Properties の Wnode.BufferSize メンバーは、正しくないサイズを指定します。
  • セッション 名とログ ファイル名のコピーを保持するための十分な領域がプロパティに割り当てられない (使用されている場合)。

• ERROR_INVALID_PARAMETER

  次のいずれかが当てはまります。

  • プロパティ は NULL です。
  • InstanceName と TraceHandle はどちらも NULL です。
  • InstanceName は NULL で、 TraceHandle は有効なハンドルではありません。
  • Properties の LogFileNameOffset メンバーが無効です。
  • Propertiesの LoggerNameOffset メンバーが無効です。
  • Propertiesの LogFileMode メンバーは、無効なフラグの組み合わせを指定します。
  • Properties の Wnode.Guid メンバーは SystemTraceControlGuid ですが、InstanceName パラメーターは ではありませんKERNEL_LOGGER_NAME。

• ERROR_BAD_PATHNAME

  別のセッションでは、Properties 構造体の LogFileNameOffset メンバーによって指定されたファイル名が既に使用されています。

• ERROR_MORE_DATA

  EVENT_TRACE_PROPERTIESのバッファーが小さすぎて、セッションのすべての情報を保持できません。 セッションのプロパティ情報が不要な場合は、このエラーを無視できます。 セッションの停止時にこのエラーが発生した場合、ETW はこのエラーを生成する前に既にセッションを停止しています。

• ERROR_ACCESS_DENIED

  管理者特権で実行されているユーザー、パフォーマンス ログ ユーザー グループ内のユーザー、LocalSystem、LocalService、NetworkService として実行されているサービスのみが、イベント トレース セッションを制御できます。 制限付きユーザーにトレース セッションを制御する機能を付与するには、それらを [パフォーマンス ログ ユーザー] グループに追加します。 管理者特権と LocalSystem として実行されているサービスを持つユーザーのみが NT カーネル ロガー セッションを制御できます。

  Windows XP と Windows 2000: トレース セッションは誰でも制御できます。

• ERROR_WMI_INSTANCE_NOT_FOUND

  指定されたセッションが実行されていません。

注釈

イベント トレース コントローラーは、この関数を呼び出します。

この関数は、FlushTrace、QueryTrace、StopTrace、および UpdateTrace 関数よりも優先されます。

要件

こちらもご覧ください

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace