次の方法で共有

StartKernelTrace

  • [アーティクル]

この関数は、カーネル イベント トレース セッションを登録して開始します。 この関数を使用して、特定のカーネル イベントのスタックウォークを有効にすることもできます。

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

パラメーター

TraceHandle [out]
イベント トレース セッションへのハンドルを格納します。 ハンドルが無効な場合、このパラメーターは 0 に設定されます。 このパラメーターは、INVALID_HANDLE_VALUE と比較する事はできません。 関数が失敗した場合は、このハンドルを使用しないでください。

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　プロパティ [in, out]
EVENT_TRACE_PROPERTIES 構造体へのポインターを格納します。 EVENT_TRACE_PROPERTIESは、セッション動作の特定の側面を構成します。

EVENT_TRACE_PROPERTIES構造体の最初のメンバー はWnodeに関連したWNODE_HEADER構造体と呼ばれる、新しい構造体 です。

以下はEVENT_TRACE_PROPERTIESです。カーネル トレース制御を構成するには、Wnode メンバーを設定する必要があります。

BufferSize
このメンバーには、イベント トレース セッションプロパティに割り当てられたメモリの合計サイズ、 バイト単位が含まれます。 メモリのサイズには、次のデータを格納するのに十分な領域が含まれる必要があります:

  • EVENT_TRACE_PROPERTIES構造体。

  • セッション名の文字列。

  • ログ ファイル名の文字列。

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　Guid
各トレース セッションには、セッションを参照する GUID が定義されている必要があります。

NT カーネル ロガー セッションの場合、このメンバーを SystemTraceControlGuid に設定する必要があります。 ログ モード定数の詳細については、「NT カーネル ロガー定数 」を参照してください。

ClientContext
このメンバーは、各イベントのログタイム スタンプを計算するときに使用されるクロック解像度を設定します。 このメンバーの既定値は、クエリ パフォーマンス カウンターです。

次のいずれかの値を指定できます。

  • 1:QUERY_PERFORMANCE_COUNTER(QPC)。 QPC は高解像度 (100 ナノ秒) のタイム スタンプを提供しますが、取得するコストは比較的高くなります。 イベント レートが高い場合、またはコンシューマーが異なるバッファーからイベントをマージする場合は、この解決方法を使用します。 古いコンピューターでは、ハードウェア エラーが原因でカウンターがスキップされる場合があるため、タイム スタンプが正確ではない可能性があります。

  • 2:システム時刻。 システム時刻は低解像度 (10 ミリ秒) のタイム スタンプを提供しますが、取得するコストは比較的低くなります。 イベントの量が多い場合は、システム時間の解像度が不十分で、イベントのシーケンスを決定できない可能性があります。 この場合、一連のイベントのタイム スタンプは同じですが、ETW がイベントを配信する順序が正しくありません。

  • 3:サイクル カウンター。 CPU カウンターは、最高の解像度のタイム スタンプを提供し、取得するコストが最も低くなります。 ただし、CPU カウンターは信頼できず、実稼働環境では使用できません。 たとえば、一部のコンピューターでは、一部の状態で停止するだけでなく、温度と電力の変化によってタイマーの頻度が変化します。 ハードウェアでこのクロックの種類がサポートされていない場合、ETW ではシステム時刻が使用されます。 Windows Server 2003、SP1であるWINDOWS XPおよびWINDOWS XPの場合、このWindows値はサポートされていません。 これは、SP1 がある Windows SERVER 2003 SP2がある　Windows XP で導入されました。

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 フラグ
このメンバーには、構造にイベントトレース情報が含まれ、その情報がロガーに送信されることを示すために、WNODE_FLAG_TRACED_GUIDが含まれている必要があります。 WNODE_FLAG_TRACED_GUIDは Evntrace.h で定義されています。

次のEVENT_TRACE_PROPERTIESメンバーも設定する必要があります:

LogFileMode
カーネル イベント トレース セッションで使用するログ モードを示します。 このメンバーを使用して、ログ ファイル、リアルタイム コンシューマー、または両方にイベントを書き込むように指定できます。

このメンバーは、セッションがプライベート ロガー セッションとして指定するためにも使用できます。 1 つ以上のモードを指定できます。 可能なモードの一覧については、「ログ モード定数 」を参照してください。

注意イベントを使用する準備ができているリアルタイム コンシューマーでない限り、リアルタイム ログ記録は指定しない。 リアルタイム コンシューマーがない場合、イベントは再生ファイルに書き込まれます。 再生ファイルのサイズは制限されています。 制限に達した場合、ログ ファイルまたは再生ファイルに新しいイベントは記録されません。 ログ関数は、ログ記録が失敗の場合はSTATUS_LOG_FILE_FULLとなります。

EnableFlags
このメンバーは、NT カーネル ロガー セッションにのみ使用されます。 トレースするイベントをカーネル ロガーに識別します。 論理 OR を 使用すると、このメンバーに 1 つ以上の値を含めることができます。 指定されたイベントに加えて、カーネル ロガーはハードウェア構成イベントもログに記録します。

トレース制御フラグは、次のEVENT_TRACE_PROPERTIESによって提供されたものに加え次のトレース制御フラグを使用できます:

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　LogFileNameOffset
この数値は、構造体に割り当てられたメモリの開始から、ログ ファイル名を含む null 終端文字列の開始へのオフセットを表します。

次の考慮事項が適用されます。

  • ファイル名拡張子は .etl である必要があります。

  • パス内のすべてのフォルダーが存在する必要があります。

  • パスには、相対パス、絶対パス、ローカル パス、またはリモートパスを指定できます。

  • これらの変数は展開されないので、パスには環境変数を含む事はできません。

  • トレースを開始するユーザーは、 フォルダーに対する書き込みアクセス許可を持っている必要があります。

  • 名前の上限は 1024 文字です。

  • LogFileModeを EVENT_TRACE_PRIVATE_LOGGER_MODE または EVENT_TRACE_FILE_MODE_NEWFILE に設定する場合は、プライベート ロガー セッションのファイル名に追加されるプロセス識別子と、新しいファイル ログ モードを使用して作成されたログ ファイルに追加されるシーケンシャル番号を含めるのに十分なメモリを割り当てしてください。

  • イベントをログ ファイルに記録しない場合 (たとえば、ログ ファイルのみを指定EVENT_TRACE_REAL_TIME_MODE LogFileNameOffset を 0 に設定します。 リアルタイム ログ記録のみを指定し、有効なログ ファイル名を持つオフセットも指定した場合、ログ ファイル名を使用して、ログ ファイルへのシーケンシャル ログ ファイルとログ イベントが作成されます。 LogFileModeが 0 で、有効なログ ファイル名を持つオフセットを指定した場合も、シーケンシャル ログ ファイルが作成されます。

  • イベントをログ ファイルに記録する場合は、この構造体の後にログ ファイル名とセッション名を含めるのに十分なメモリを割り当てる必要があります。 ログ ファイル名は、メモリ内のセッション名の後に続く必要があります。

  • トレース ファイルは、既定のセキュリティ記述子を使用して作成されます。つまり、ログ ファイルは ACL は親ディレクトリと同じです。 ファイルへのアクセスを制限する場合は、適切な ACL を持つ親ディレクトリを作成します。

LoggerNameOffset
このメンバーは、構造体に割り当てられたメモリの開始から、ログ ファイル名を含む null 終端文字列の開始へのオフセットを表します。

次の考慮事項が適用されます。

  • アクション名は 1024 文字までに制限されています。

  • セッション名では大文字と小文字は区別されません。一意である必要があります。

  • この構造体にメモリを割り当てる場合は、構造体の後にセッション名とログ ファイル名を含めるのに十分なメモリを予約する必要があります。

  • メモリ内のセッション名はログ ファイル名の後に続く必要があります。 ログ ファイル名はオフセット領域にコピーする必要があります。 この関数は、KERNEL_LOGGER_NAME によって定義されたセッション名を書き込みます。

選択したログ ファイルの種類に応じて 、MaximumFileSize メンバーを設定する必要がある場合 があります。

メモLoggerNameOffsetでロガー名を設定する必要はありません。この関数では常に、StartKernelTrace を呼び出す KERNEL_LOGGER_NAME値が使用されます。 この関数は 、Wnode.Guid が SystemTraceControlGuid に対応するかどうかを確認します。それではない場合は、ERROR_INVALID_PARAMETERを返します。 Wnode.Guid がKernelRundownGuidに対応する場合は、ロガー名を指定する必要があります。 KernelRundownGuidは、既存のプロセス情報、スレッド情報、プロセスごとに読み込まれたイメージ、CPU、ビデオ、ディスク、ネットワーク カード、サービス、電源、プラグ アンド プレイ、ディスク IDE チャネルなどのハードウェア構成などのイベントをログに記録するために使用されるコントロール GUID です。

戻り値

ERROR_SUCCESS は成功を示します。

次の表に、このオプションでエラーの可能性な値を示します。

エラー値 説明

ERROR_ALREADY_EXISTS

システム上で実行されるカーネル ロガーのインスタンスは 1 つのみです。 別のコンポーネントがカーネル ログを開始した後にこの関数を開始しようとすると、このエラーが返される可能性があります。

ERROR_INVALID_FLAGS

Properties.EnableFlagsに無効なトレース フラグが含まれている可能性があります。

ERROR_OUT_OF_MEMORY

EVENT_TRACE_PROPERTIES に対してメモリの割り当てに失敗した可能性があります。

一覧以外の理由で失敗した場合は、システム エラー コードが返されます。

注釈

StackTracingEventIds に、有効になっていないイベントが含まれている場合は、EVENT_TRACE_PROPERTIES。EnableFlagsフィールドまたはカーネル トレース コントロールでデコードできない場合、これらのフラグは無視され、エラー コードは返されません。

要件:

バージョン: Windows Vista 以降で使用できます。 この構造体は、Windows パフォーマンス アナライザーで配布されています。

ヘッダー: KernelTraceControl.h で宣言されます。 KernelTraceControl.h を含みます。

ライブラリ: KernelTraceControl.dll に含まれます。

関数

システム情報のカスタム挿入