StartTraceW

StartTrace 関数はイベントトレースセッションを開始する。(Unicode)

StartTraceW TraceHandle, InstanceName, Properties

TraceHandle : [var] [ControlTrace](/windows/win32/api/evntrace/nf-evntrace-controltracew) などの API での後続の使用のために、イベントトレースセッションへのハンドルを受け取る。関数が失敗した場合、このハンドルを使用してはならない。セッションハンドルを INVALID_HANDLE_VALUE と比較してはならない。ハンドルが有効でない場合、セッションハンドルは 0 となる。
InstanceName : [wstr] イベントトレースセッションの名前を含む null 終端文字列。セッション名は 1,024 文字までに制限され、大文字小文字を区別せず、一意でなければならない。> [!Important] > セッションの所有者と使用目的がセッション名から判断できるように、セッションに説明的な名前を使用すること。GUID などの非決定論的または非記述的な値は使用しないこと。セッション名を一意にするためにランダムな数字を付加しないこと。ETW セッションは限られたリソースであるため、コンポーネントが複数のセッションを開始すべきではない。コンポーネントの開始時にコンポーネントのセッションがすでに実行中の場合、コンポーネントは 2 番目のセッションを作成するのではなく、孤立したセッションをクリーンアップすべきである。この関数は、指定されたセッション名を _Properties_ の **LoggerNameOffset** メンバが指すオフセットにコピーする。
Properties : [var] セッションの動作を指定する [EVENT_TRACE_PROPERTIES](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties) 構造体へのポインタ。設定すべき主要な構造体メンバは次のとおり: - **Wnode.BufferSize** - **Wnode.Guid** - **Wnode.ClientContext** - **Wnode.Flags** - **LogFileMode** - **LogFileNameOffset** - **LoggerNameOffset** 作成するログファイルの種類に応じて、**MaximumFileSize** の値を指定する必要がある場合もある。_Properties_ パラメータの設定方法およびセッションの動作の詳細については、注釈セクションを参照のこと。**Windows 10 バージョン 1703 以降:** プロセス間シナリオでのパフォーマンス向上のため、システムワイドなプライベートロガーの開始時に **StartTrace** にフィルタリング情報を渡せるようになった。フィルタリング情報を含めるには、新しい [EVENT_TRACE_PROPERTIES_V2](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties_v2) 構造体を渡す必要がある。詳細については [Configuring and Starting a Private Logger Session](/windows/win32/etw/configuring-and-starting-a-private-logger-session) を参照のこと。

(プラグイン / モジュール : advapi32.dll)

解説

StartTrace 関数はイベントトレースセッションを開始する。(Unicode)

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS となる。関数が失敗した場合、戻り値は
[システムエラーコード](/windows/win32/debug/system-error-codes)
のいずれかとなる。以下は代表的なエラーとその原因である。- **ERROR_BAD_LENGTH** 次のいずれかが発生している: -
_Properties_ の **Wnode.BufferSize** メンバが不正なサイズを指定している。- _Properties_
に _InstanceName_ のコピーを保持するための十分な領域が割り当てられていない。-
**ERROR_INVALID_PARAMETER** 次のいずれかが発生している: - _Properties_ が
**NULL**。- _TraceHandle_ が **NULL**。- _Properties_ の
**LogFileNameOffset** メンバが不正。- _Properties_ の **LoggerNameOffset**
メンバが不正。- _Properties_ の **LogFileMode** メンバが不正なフラグの組み合わせを指定している。-
**Wnode.Guid** メンバが **SystemTraceControlGuid** だが、_InstanceName_
パラメータが **KERNEL_LOGGER_NAME** でない。- **ERROR_ALREADY_EXISTS** 同じ名前または
GUID を持つセッションがすでに実行中である。- **ERROR_BAD_PATHNAME**
次のいずれかの理由でこのエラーが発生する可能性がある: - 別のセッションがすでに _Properties_ 構造体の
**LogFileNameOffset** メンバで指定されたファイル名を使用している。- **LogFileMode** と
**LogFileNameOffset** の両方が 0 である。- **ERROR_DISK_FULL**
ログファイル用のドライブに十分な空き領域がない。これは次の場合に発生する: - **MaximumFileSize** が 0
以外で、ログファイル用に **MaximumFileSize** バイトが利用可能でない - ドライブがシステムドライブで、追加の 200
MB が利用可能でない - **MaximumFileSize** が 0 で、追加の 200 MB が利用可能でない
より多くの空き領域のあるドライブを選ぶか、（使用している場合は）**MaximumFileSize** で指定するサイズを減らすこと。-
**ERROR_ACCESS_DENIED** 管理者特権を持つユーザ、Performance Log Users
グループのユーザ、LocalSystem / LocalService / NetworkService
として実行中のサービスのみがイベントトレースセッションを制御できる。制限付きユーザにトレースセッション制御権限を付与するには、Performance
Log Users グループに追加すること。管理者特権を持つユーザおよび LocalSystem として実行中のサービスのみが NT
カーネルロガーセッションを制御できる。ユーザが Performance Log Users
グループのメンバである場合、指定したフォルダにログファイルを作成する権限がない場合がある。-
**ERROR_NO_SYSTEM_RESOURCES** 次のいずれかが発生している: - ログセッションが
**EVENT_TRACE_SYSTEM_LOGGER_MODE** フラグを使用していて、システムロガーの最大数 (8) に達した。-
システム上のログセッションの最大数に達した。ログセッションが停止されるまで新しいロガーを作成することはできない。ほとんどのシステムでは、ログセッションの最大数は
64
である。`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers`
の **REG_DWORD** キーを編集することで、システムのログセッションの最大数を変更できる。設定可能な値は 32 ～ 256
（両端含む）。変更を反映するには再起動が必要。ロガーはシステムリソースを使用する。これらのスロットが埋まる場合、システム上のロガー数を増やすとパフォーマンスコストがかかる。この制限はシステムリソースの過剰使用を防ぐために存在する。>
[!Important] >
この制限は特定のシナリオを有効にするためにシステム管理者が手動でのみ調整すべきである。EtwMaxLoggers
設定はプログラムやドライバによって自動的に変更してはならない。Windows 10 バージョン 1709
より前では、これは非プライベートロガーに対して 64 ロガーの固定上限である。

[備考]
イベントトレースコントローラがこの関数を呼び出す。セッションは、セッションが停止されるか、コンピュータが再起動されるか、I/O
エラーが発生するか、非循環ログで最大ファイルサイズに達するまでアクティブなままである。イベントトレースセッションを停止するには、_ControlCode_
パラメータを **EVENT_TRACE_CONTROL_STOP** に設定して
[ControlTrace](/windows/win32/api/evntrace/nf-evntrace-controltracew)
関数を呼び出す。同じセッション GUID（`Properties.Wnode.Guid`
で指定）を持つセッションを複数開始することはできない。ほとんどの場合、ETW システムがセッション用の新しい GUID
を生成できるように、`Properties.Wnode.Guid` をすべて 0 （つまり
**GUID_NULL**）に設定する。プライベートロガーセッションを指定するには、_Properties_ の
**Wnode.Guid** メンバをプロバイダの制御 GUID に設定する。プライベートロガーセッションの制御 GUID
ではない。プロバイダは **StartTrace** を呼び出す前にその GUID
を登録している必要がある。この関数はグローバルロガーセッション（廃止予定）の開始には使用しない。グローバルロガーセッションの開始の詳細については、[Configuring
and Starting the Global Logger
Session](/windows/win32/etw/configuring-and-starting-the-global-logger-session)
を参照のこと。

情報