ControlTraceA 関数 (evntrace.h)
ControlTrace 関数は、指定されたイベント トレース セッションをフラッシュ、クエリ、更新、または停止します。
構文
ULONG WMIAPI ControlTraceA(
[in] TRACEHANDLE TraceHandle,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
パラメーター
[in] TraceHandle
イベント トレース セッション (0) を処理します。 SessionName が NULL の場合は、0 以外の SessionHandle を指定する必要があります。 SessionName が NULL でない場合、 ETW はハンドルを無視 します。
StartTrace 関数は、新しいトレースが開始されたときにこのハンドルを返します。 既存のトレースのハンドルを取得するには、ControlTrace を使用してトレースの名前に基づいてトレース プロパティのクエリを実行し、返されたEVENT_TRACE_PROPERTIESデータの Wnode.HistoricalContext フィールドからハンドルを取得します。
[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 ファイルへのイベントの書き込みを無効にします)。 2020 年 10 月の更新プログラムWindows 10以降でサポートされます。
注意
バッファーをフラッシュしたり、DllMain からトレース セッションを停止したりしても安全ではありません (デッドロックが発生する可能性があります)。
戻り値
関数が成功した場合、戻り値は 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 関数よりも優先されます。
注意
evntrace.h ヘッダーは、ControlTrace をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | evntrace.h |
| Library | Windows 8.1 および Windows Server 2012 R2 の Sechost.lib;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows XP 上の Advapi32.lib |
| [DLL] | Windows 8.1とWindows Server 2012の Sechost.dll。Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows XP での Advapi32.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示