EVENT_TRACE_PROPERTIES 構造体 (evntrace.h)
EVENT_TRACE_PROPERTIES構造体には、イベント トレース セッションに関する情報が含まれています。 セッションのプロパティを定義、更新、またはクエリする場合は、 StartTrace や ControlTrace などの API でこの構造を使用します。
注意
これはバージョン 1 の構造体です。 その他のオプションは、 EVENT_TRACE_PROPERTIES_V2 ( FilterDesc や V2Options など) でサポートされています。
構文
typedef struct _EVENT_TRACE_PROPERTIES {
WNODE_HEADER Wnode;
ULONG BufferSize;
ULONG MinimumBuffers;
ULONG MaximumBuffers;
ULONG MaximumFileSize;
ULONG LogFileMode;
ULONG FlushTimer;
ULONG EnableFlags;
union {
LONG AgeLimit;
LONG FlushThreshold;
} DUMMYUNIONNAME;
ULONG NumberOfBuffers;
ULONG FreeBuffers;
ULONG EventsLost;
ULONG BuffersWritten;
ULONG LogBuffersLost;
ULONG RealTimeBuffersLost;
HANDLE LoggerThreadId;
ULONG LogFileNameOffset;
ULONG LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;
メンバー
Wnode
WNODE_HEADER構造体。 BufferSize、Flags、Guid の各メンバーを指定する必要があります。 必要に応じて、 ClientContext メンバーを指定できます。
BufferSize
イベント トレース セッション バッファーごとに割り当てられたメモリのキロバイト数。 最小バッファー サイズは 4 (4 KB) です。 最大バッファー サイズは 16384 (16 MB) です。 ほとんどのトレース セッションでは、メモリとディスク領域を無駄にしないように、バッファー サイズが 64 KB 以下である必要があります。 Windows 8より前: 最大バッファー サイズは 1024 (1 MB) です。
バッファー サイズを小さくすると、セッション メモリの使用量が減り、ログ ファイルのサイズを減らすことができます。 バッファー サイズを大きくすると、より大きなイベントの収集がサポートされます。ETW ではバッファー境界を越えてイベントがフラグメント化されないため、バッファー サイズよりも大きいイベントを収集できません。 非常に高いデータ スループットを伴うシナリオでは、バッファー サイズを大きくすると CPU オーバーヘッドも削減できます。
- 小さなイベントと低いイベント レート (数 KB/秒) のセッションでは、小さなバッファー サイズ (4 KB から 16 KB) を使用する必要があります。
- 小さなイベントと中程度のイベント レートのセッションでは、中程度のバッファー サイズ (16 KB から 32 KB) を使用する必要があります。
- 大きなイベントまたは高いイベント レート (数 MB/秒) のセッションでは、大きなバッファー サイズ (64 KB から 128 KB) を使用する必要があります。
- まれに、1 秒あたり数百メガバイトのデータを含む診断トレース用に大量のメモリを予約する必要がある場合、膨大なバッファー サイズ (256 KB から 1024 KB) を使用すると、CPU オーバーヘッドが削減されます。
注意
バッファー サイズに関係なく、ETW は 64 KB を超えるイベントを収集できません。
ETW では、特定のシナリオで要求された BufferSize を上方に調整できます。 たとえば、トレース ファイルをディスクに書き込む場合、ETW はバッファー サイズをディスクの物理ブロック サイズの倍数に増やします。
重要
BufferSize は、トレース セッションの最も重要なパラメーターの 1 つです。 通常、大きなバッファーではメモリとディスク領域が無駄になります。 大きなバッファー (256 KB 以上) を含むトレース セッションは、診断調査またはテストにのみ使用する必要があり、実稼働トレースには使用しないでください。
ヒント
トレース セッションのメモリ使用量を制御するために BufferSize を使用しないでください。 代わりに、セッションのイベント サイズとイベント レートに基づいてバッファー サイズを選択し、 MinimumBuffers パラメーターと MaximumBuffers パラメーターを使用してセッション メモリの使用量を調整します。
MinimumBuffers
トレース セッションのバッファー プール用に予約されているバッファーの最小数。
ETW では、特定のシナリオでこの値を調整できます。
- ログ モードに フラグが
EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING含まれている場合、ETW は少なくとも 2 つのバッファーを予約します。 - ログ モードに フラグが含
EVENT_TRACE_NO_PER_PROCESSOR_BUFFERINGまれていない場合、ETW は論理プロセッサごとに少なくとも 2 つのバッファーを予約します。 - この値が ETW によって決定された制限より大きい場合、ETW はメモリの過剰な使用を回避するために、この値を制限に減らすことができます。
中程度のイベント レートのファイル モードおよびリアルタイム トレースの場合、ほとんどのユーザーは 、MinimumBuffers を 0 または小さな最小値 (4 や 8 など) に設定してメモリ使用量を最小限に抑え、ETW がプロセッサの数に基づいて値を上方向に調整できるようにする必要があります。 ETW は、トレースの開始時にバッファーの最小数 (調整済み) を予約します。 バッファーの入力速度が処理よりも速い場合、ETW は MaximumBuffers で指定された数までの追加バッファーの割り当てを試みます。
バッファー モード (循環メモリ内) トレースの場合、ユーザーは、セッション用に ETW で予約するメモリの合計量に応じて MinimumBuffers パラメーターを設定する必要があります。 これは通常、予想されるイベントレートとトレースでカバーする時間に基づいて計算されます。 たとえば、1 秒あたり 16 KB のデータレートが予想され、トレースで少なくとも 60 秒のデータを記録する場合は、960 KB が必要です。 バッファー サイズが 32 KB の場合、 MinimumBuffers を 30 (バッファーあたり合計 960 KB/ 32 KB = 30 バッファー) に設定します。 ETW は、トレースの開始時にバッファーの最小数 (調整済み) を予約します。 すべてのバッファーが塗りつぶされると、ETW は新しいイベントに対して最も古い塗りつぶされたバッファーを再利用します。 ETW では追加のバッファーは割り当てられません (ETW では、バッファリング モード トレースの MaximumBuffers は無視されます)。
MaximumBuffers
トレース セッションのバッファー プールに割り当てられるバッファーの最大数。
ETW では、特定のシナリオでこの値を調整できます。
- この値が MinimumBuffers の調整値より小さい場合、ETW はそれを MinimumBuffers 以上の適切な値に増加させる可能性があります。
- この値が ETW によって決定された制限より大きい場合、ETW はそれを制限に減らすことができます。
ほとんどのユーザーは、MinimumBuffers と MaximumBuffers を同じ値に設定して、セッションのチューニングを開始する必要があります。 イベント レートのピーク時にトレースによってイベントがドロップされた場合は、 MaximumBuffers の値を増やします。
イベントが高 IRQL で実行されているドライバーによって生成された場合、ETW はオンデマンド バッファーを割り当てることができません。 トレース セッションで高 IRQL カーネル モード プロバイダーからのイベントを記録する必要がある場合は、より高い値の MinimumBuffers を使用して、バッファーを強制的に事前割り当てする必要がある場合があります。
注意
ETW は、バッファリング モード セッション (ログ EVENT_TRACE_BUFFERING_MODEモードを含むセッション) の MaximumBuffers を無視します。 Buffering-mode セッションは、常にトレース コレクションの開始時に MinimumBuffers を割り当て、追加のバッファーを割り当てることはありません。
MaximumFileSize
サイズ制限がない場合は、イベントのログ記録に使用されるファイルの最大サイズ (メガバイト単位)、または 0。 通常、このメンバーを使用して、 LogFileMode を に設定するときに循環ログ ファイルのサイズを EVENT_TRACE_FILE_MODE_CIRCULAR制限します。 LogFileMode に 、EVENT_TRACE_FILE_MODE_CIRCULARまたは EVENT_TRACE_FILE_MODE_NEWFILEが含まれている場合、このメンバーは 0 以外の値に設定するEVENT_TRACE_FILE_MODE_PREALLOCATE必要があります。
ログ記録にシステム ドライブ (オペレーティング システムを含むドライブ) を使用している場合、最大ファイル サイズ パラメーターを使用しているかどうかに関係なく、ETW は追加の 200 MB のディスク領域を確認します。 したがって、システム ドライブ内のトレース ファイルの最大ファイル サイズとして 100 MB を指定する場合は、ドライブに 300 MB の空き領域が必要です。
LogFileMode
イベント トレース セッションのログ フラグ。 このメンバーを使用して、イベントをメモリ内循環バッファー、ログ ファイル、またはリアルタイム コンシューマーに書き込むかどうかを指定します。 また、このメンバーを使用して、セッションがプライベート ロガー セッションであるなど、他のセッション特性を指定することもできます。 使用可能なフラグの一覧については、「 ログ モード定数」を参照してください。
ETW は、セッションにリアルタイム コンシューマーが存在しない場合に、リアルタイム セッションのイベントをバッファーします。 このバッファリングは制限されることに注意してください。 制限に達すると、新しいイベントは無視され、ログ関数は で STATUS_LOG_FILE_FULL失敗します。 Windows Vista より前: リアルタイム コンシューマーがない場合、イベントは破棄され、ログ記録が続行されます。
リアルタイム コンシューマーがイベントを使用しない限り、リアルタイム ログ セッションを開始しないでください。 コンシューマーなしのリアルタイム セッションでは、システム リソース (イベントをバッファリングするための CPU、メモリ、ディスク領域) が無駄になります。
コンシューマーがリアルタイム イベントの処理を開始すると、バッファー内のイベントが最初に使用されます。 バッファー内のすべてのイベントが使用されると、セッションは新しいイベントの報告を開始します。
FlushTimer
空でないトレース バッファーがフラッシュされる頻度 (秒単位)。 最小フラッシュ時間は 1 秒です。
- ファイル モード セッションの場合: FlushTimer を 0 に設定すると、時間ベースのフラッシュが無効になります (バッファーがいっぱいになったとき、セッションが停止されたとき、またはセッションが明示的にフラッシュされたときにフラッシュが発生します)。 ほとんどのファイル モード トレースでは、トレース ファイル内の無駄な領域を回避するために FlushTimer を 0 に設定する必要があります (つまり、ほとんどの空のバッファーを格納するディスク領域が無駄にならないようにします)。 トレースが閉じられない可能性がある場合 (システムがクラッシュした場合でもイベントを確実に取得する場合など) は、タイマーを 0 以外の値に設定できます。
- リアルタイム セッションの場合: FlushTimer を 0 に設定すると、既定のタイムアウトは 1 秒になります。 リアルタイム セッションでは、データの受信速度に基づいてフラッシュ タイマーを設定する必要があります。 タイマー値を大きくすると、トレースの CPU オーバーヘッドが削減されることに注意してください。 ほとんどのリアルタイム トレースは、5 秒または 10 秒のタイマーで開始し、必要に応じてタイマーを調整する必要があります。
- バッファー (循環メモリ内) セッションの場合、 FlushTimer は使用されません。 トレース データはオンデマンドでのみフラッシュされます (つまり、 ControlTrace を介してファイルにフラッシュされます)。
EnableFlags
システム ロガー セッションでは、トレースに含める SystemTraceProvider イベントを示す EnableFlags を設定できます。
注意
EnableFlags は、システム ロガー (ロガー モード フラグ、セッション名SystemTraceControlGuid、セッション GUID、KERNEL_LOGGER_NAMEまたはGlobalLoggerGuidセッション GUID を使用してEVENT_TRACE_SYSTEM_LOGGER_MODE開始されたトレース セッション) でのみ有効です。
このメンバーには、次の値の 1 つ以上を含めることができます。 を指定しない限り EVENT_TRACE_FLAG_NO_SYSCONFIG、指定したイベントに加えて、ロガーは Windows XP のハードウェア構成イベントと Windows Server 2003 以降のシステム構成イベントも記録します。
EVENT_TRACE_FLAG_ALPC (0x00100000)
ALPC イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_CSWITCH (0x00000010)
次の Thread イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_DBGPRINT (0x00040000)
DbgPrint 呼び出しと DbgPrintEx 呼び出しを ETW イベントに変換できるようにします。
EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)
次の FileIo イベントの種類を有効にします (EVENT_TRACE_FLAG_DISK_IOも有効にする必要があります)。
EVENT_TRACE_FLAG_DISK_IO (0x00000100)
次の DiskIo イベントの種類を有効にします。
EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)
次の DiskIo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_DISPATCHER (0x00000800)
次の Thread イベントの種類を有効にします。
この値は、Windows 7、Windows Server 2008 R2 以降でサポートされています。
EVENT_TRACE_FLAG_DPC (0x00000020)
次の PerfInfo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_DRIVER (0x00800000)
次の DiskIo イベントの種類を有効にします。
- DriverCompleteRequest
- DriverCompleteRequestReturn
- DriverCompletionRoutine
- DriverMajorFunctionCall
- DriverMajorFunctionReturn
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_FILE_IO (0x02000000)
次の FileIo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)
次の FileIo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)
次の Image イベントの種類を有効にします。
EVENT_TRACE_FLAG_INTERRUPT (0x00000040)
次の PerfInfo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_JOB (0x00080000)
この値は、Windows 10でサポートされています
EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)
次の PageFault_V2 イベントの種類を有効にします。
EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)
次の PageFault_V2 イベントの種類を有効にします。
EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)
EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)
システム構成の実行を行わないでください。
この値は、Windows 8、Windows Server 2012、以降でサポートされています。
EVENT_TRACE_FLAG_PROCESS (0x00000001)
次の Process イベントの種類を有効にします。
EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)
次の Process_V2 イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_PROFILE (0x01000000)
次の PerfInfo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_REGISTRY (0x00020000)
レジストリ イベントの種類 を 有効にします。
EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)
SplitIo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)
次の PerfInfo イベントの種類を有効にします。
この値は、Windows Vista 以降でサポートされています。
EVENT_TRACE_FLAG_THREAD (0x00000002)
次の Thread イベントの種類を有効にします。
EVENT_TRACE_FLAG_VAMAP (0x00008000)
マップとマップ解除 (イメージ ファイルを除く) イベントの種類を有効にします。
この値は、Windows 8、Windows Server 2012、以降でサポートされています。
EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)
次の PageFault_V2 イベントの種類を有効にします。
この値は、Windows 7、Windows Server 2008 R2 以降でサポートされています。
DUMMYUNIONNAME
DUMMYUNIONNAME.AgeLimit
使用されていません。
Windows 2000: 未使用のバッファーが解放されるまでの時間の遅延 (分単位)。 既定では 15 分です。
DUMMYUNIONNAME.FlushThreshold
NumberOfBuffers
出力時に、イベント トレース セッションのバッファー プールに割り当てられたバッファーの数。
FreeBuffers
出力時に、イベント トレース セッションのバッファー プールで割り当てられているが未使用のバッファーの数。
EventsLost
出力時に、記録されなかったイベントの数。
BuffersWritten
出力時に書き込まれたバッファーの数。
LogBuffersLost
出力時に、ログ ファイルに書き込めなかったバッファーの数。
RealTimeBuffersLost
出力時に、コンシューマーにリアルタイムで配信できなかったバッファーの数。
LoggerThreadId
出力時に、イベント トレース セッションのスレッド識別子。
LogFileNameOffset
この構造体の割り当てられたメモリの先頭から、ログ ファイル名を含む nul で終わる文字列の先頭までのオフセット (バイト単位)。
通常、ファイル名には拡張子があります .etl 。 パス内のすべてのフォルダーが既に存在している必要があります (ETW ではフォルダーは作成されません)。 パスには、相対パス、絶対パス、ローカル パス、またはリモートパスを指定できます。 パス内の環境変数は展開されません。 ユーザーには、フォルダーに書き込むアクセス許可が必要です。
ログ ファイル名は 1,024 文字に制限されています。 LogFileMode を EVENT_TRACE_PRIVATE_LOGGER_MODE または EVENT_TRACE_FILE_MODE_NEWFILE に設定する場合は、プライベート ロガー セッションのファイル名に追加されるプロセス識別子と、新しいファイル ログ モードを使用して作成されたログ ファイルに追加されるシーケンシャル番号を含めるのに十分なメモリを確保してください。
イベントをログ ファイルに記録しない場合 (たとえば、 EVENT_TRACE_REAL_TIME_MODE のみを指定した場合)、 LogFileNameOffset を 0 に設定します。 リアルタイム ログのみを指定し、有効なログ ファイル名を持つオフセットも指定した場合、ETW はログ ファイル名を使用して、イベントをリアルタイム コンシューマーに送信するだけでなく、ログ ファイルに対するシーケンシャル ログ ファイルとログ イベントを作成します。 また、LogFileMode が 0 の場合、ETW はシーケンシャル ログ ファイルを作成し、有効なログ ファイル名を持つオフセットを指定します。
イベントをログ ファイルに記録する場合は、この構造体に対して十分なメモリを予約して、構造の後にログ ファイル名とセッション名を含める必要があります。 ログ ファイル名は、メモリ内のセッション名の後に続く必要があります。 例については、「解説」を参照してください。
トレース ファイルは、既定のセキュリティ記述子を使用して作成されます。つまり、ログ ファイルは ACL は親ディレクトリと同じです。 ファイルへのアクセスを制限する場合は、適切な ACL を持つ親ディレクトリを作成します。
LoggerNameOffset
構造体の割り当てられたメモリの先頭から、セッション名を含む nul で終わる文字列の先頭までのオフセット (バイト単位)。
重要
セッションの所有権と使用状況をセッション名から決定できるように、セッションのわかりやすい名前を使用します。 GUID やその他のわかりやすい値は使用しないでください。 セッション名を一意にするためにランダムな数字を追加しないでください。 ETW セッションは限られたリソースであるため、コンポーネントが複数のセッションを開始しないようにする必要があります。 コンポーネントの起動時にコンポーネントのセッションが既に実行されている場合、コンポーネントは、2 つ目のセッションを作成するのではなく、孤立したセッションをクリーンする必要があります。
セッション名は 1,024 文字に制限されています。 セッション名では大文字と小文字が区別されません。 同じ名前の別のセッションが既に実行されている場合、システムは新しいセッションを開始しません。
Windows 2000: セッション名では大文字と小文字が区別されます。 その結果、名前が大文字と小文字のみが異なるセッションが許可されます。 ただし、混乱を減らすには、セッション名が一意であることを確認する必要があります。
注釈
この構造体にメモリを割り当てるときは、構造体の後にセッション名とログ ファイル名を含めるのに十分なメモリを割り当てる必要があります。 メモリ内のセッション名はログ ファイル名の後に続く必要があります。 ログ ファイル名をオフセットにコピーする必要がありますが、セッション名をオフセットにコピーしないでください。 StartTrace 関数は、名前をコピーします。
メンバーを設定する前に、この構造体のメモリを必ず 0 に初期化してください。 例:
typedef struct EventTracePropertyData {
EVENT_TRACE_PROPERTIES Props;
WCHAR LoggerName[128];
WCHAR LogFileName[1024];
} EventTracePropertyData;
EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);
プロバイダーからのイベントは、セッションのバッファーに書き込まれます。 ファイルまたはリアルタイム セッションのバッファーがいっぱいの場合 (または FlushTimer の有効期限が切れた場合)、セッションはイベントをログ ファイルに書き込み、リアルタイム コンシューマーに配信するか、またはその両方を行ってバッファーをフラッシュします。 セッションのバッファーの塗りつぶしがフラッシュできる時間よりも速い場合は、新しいバッファーが割り当てられ、 MaximumBuffers までセッションのバッファー プールに追加されます。 この制限を超えると、バッファーが使用可能になるまで、セッションは受信イベントを破棄します。 各セッションでは、破棄されたイベントの数のレコードが保持されます ( EventsLost メンバーを参照)。
セッションの実行中に EventsLost などのセッション統計を表示するには、 ControlTrace 関数を呼び出し、 ControlCode パラメーターを に EVENT_TRACE_CONTROL_QUERY設定します。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| Header | evntrace.h |