StartTraceA 関数 (evntrace.h)

  • [アーティクル]

StartTrace 関数は、イベント トレース セッションを登録して開始します。

重要

クロスプロセス イベント トレース セッションは、限られたシステム リソースです。 開発者は、顧客のマシンでイベント トレース セッションを開始しないようにする必要があります。 イベント トレース セッションが必要な場合は、可能な限り最小のスコープに制限する必要があります。可能な限り少数のセッションを使用し、可能な場合はインプロセスのみのセッションを使用します (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC)、シナリオに特に収集が必要な場合にのみトレースを開始し、シナリオが完了したらすぐにトレースを停止し、セッションで使用されるメモリの量を制限します。 不要なイベントを収集しないように、厳密なイベント フィルターを使用します。

構文

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

パラメーター

[out] TraceHandle

ControlTrace などの API で後続に使用するために、イベント トレース セッションへのハンドルを受け取ります。

関数が失敗した場合は、このハンドルを使用しないでください。 セッション ハンドルをINVALID_HANDLE_VALUEと比較しないでください。 セッション ハンドルが無効な場合、セッション ハンドルは 0 です。

[in] InstanceName

イベント トレース セッションの名前を含む Null で終わる文字列。 セッション名は 1,024 文字に制限され、大文字と小文字は区別されず、一意である必要があります。

重要

セッションの所有権と使用状況をセッション名から判断できるように、セッションのわかりやすい名前を使用します。 GUID やその他の非決定的または説明的でない値は使用しないでください。 セッション名を一意にするためにランダムな数字を追加しないでください。 ETW セッションは限られたリソースであるため、コンポーネントが複数のセッションを開始しないようにする必要があります。 コンポーネントの開始時にコンポーネントのセッションが既に実行されている場合、コンポーネントは、2 つ目のセッションを作成するのではなく、孤立したセッションをクリーンアップする必要があります。

この関数は、指定したセッション名を Properties の LoggerNameOffset メンバーが指すオフセットにコピーします。

[in, out] Properties

セッションの動作を指定する EVENT_TRACE_PROPERTIES 構造体へのポインター。 設定する構造体の主要なメンバーを次に示します。

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • 　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　LogFileNameOffset
  • LoggerNameOffset

作成するログ ファイルの種類によっては、 MaximumFileSize の値を指定する必要がある場合もあります。 Properties パラメーターの設定とセッションの動作の詳細については、「解説」セクションを参照してください。

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

戻り値

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

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

  • ERROR_BAD_LENGTH

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

    • Properties の Wnode.BufferSize メンバーは、正しくないサイズを指定します。
    • プロパティ には、 InstanceName のコピーを保持するための十分な領域が割り当てされていません。

  • ERROR_INVALID_PARAMETER

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

    • プロパティ は 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

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

    ユーザーがパフォーマンス ログ ユーザー グループのメンバーである場合、指定したフォルダーにログ ファイルを作成する権限がない可能性があります。

  • ERROR_NO_SYSTEM_RESOURCES

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

    • ログ 記録セッションでは 、EVENT_TRACE_SYSTEM_LOGGER_MODE フラグが使用され、システム ロガーの最大数 (8) に達しました。

    • システム上のログ セッションの最大数に達しました。 ログ セッションが停止されるまで、新しいロガーを作成することはできません。 ほとんどのシステムでは、ログ セッションの最大数は 64 です。

      システムのログ セッションの最大数を変更するには、 でHKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggersREG_DWORD キーを編集します。 許容される値は 32 から 256 です。値は 32 ~ 256 です。 変更を有効にするには、再起動が必要です。

      ロガーではシステム リソースが使用されることに注意してください。 システム上のロガーの数を増やすと、それらのスロットがいっぱいになるとパフォーマンス コストが発生します。 この制限は、システム リソースの過剰な使用を防ぐために存在します。

      重要

      制限は、特定のシナリオを有効にするためにシステム管理者が手動で調整する必要があります。 EtwMaxLoggers 設定は、プログラムまたはドライバーによって自動的に変更することはできません。

      Windows 10 バージョン 1709 より前のバージョンでは、これは非プライベート ロガーの場合は 64 個のロガーの固定上限です。

注釈

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

セッションは、セッションが停止するか、コンピューターが再起動されるか、I/O エラーが発生するか、非循環ログの最大ファイル サイズに達するまでアクティブなままになります。 イベント トレース セッションを停止するには、 ControlTrace 関数を呼び出し、 ControlCode パラメーターを EVENT_TRACE_CONTROL_STOP に設定します。

同じセッション GUID を使用して複数のセッションを開始することはできません (で指定)。Properties.Wnode.Guid ほとんどの場合、ETW システムがセッションの新しい GUID を生成できるようにするには、すべてゼロ (つまりGUID_NULL) に設定Properties.Wnode.Guidします。

プライベート ロガー セッションを指定するには、プライベート ロガー セッションのコントロール GUID ではなく、プロバイダーのコントロール GUID に Properties のWnode.Guid メンバーを設定します。 StartTrace を呼び出す前に、プロバイダーが GUID を登録している必要があります。

この関数は、グローバル ロガー セッションを開始するために使用しません (非推奨)。 グローバル ロガー セッションの開始の詳細については、「グローバル ロガー セッションの 構成と開始」を参照してください。

システム ロガー

ロガーをシステム ロガーにし、 SystemTraceProvider またはその他の システム プロバイダーからイベントを受信するには、次のいずれかが true である必要があります。

  • プロパティ メンバー LogFileMode には、EVENT_TRACE_SYSTEM_LOGGER_MODE フラグが含まれています (推奨)。
  • Properties メンバー Wnode.Guid は SystemTraceControlGuid または GlobalLoggerGuid に設定されています (非推奨 - これらの GUID を使用しようとする他のコンポーネントと競合するため、新しいコードには使用しないでください)。
  • InstanceName は KERNEL_LOGGER_NAME に設定されています (非推奨 - この名前を使用しようとする他のコンポーネントと競合するため、新しいコードには使用しないでください)。

注意

 システム ロガーは、トレースに含める必要がある SystemTraceProvider イベントを示すために、EVENT_TRACE_PROPERTIES構造体の EnableFlags メンバーを設定する必要があります。

システム ロガーは特別なカーネル イベントを受け取るため、追加の制限が適用されます。

  • 同じシステムでアクティブなシステム ロガーは 8 個までです。
  • システム ロガーを Windows Server コンテナー内に作成することはできません。
  • システム ロガーは 、EVENT_TRACE_USE_PAGED_MEMORY フラグを使用できません。
  • Windows 10バージョン 1703 より前では、システム ロガーで同時に使用できる異なるクロックタイプは 2 つまでです。 たとえば、あるアクティブ なシステム ロガーが "CPU サイクル カウンター" クロックタイプを使用していて、別のアクティブなシステム ロガーが "クエリ パフォーマンス カウンター" クロックタイプを使用している場合、3 番目のクロックタイプのアクティブ化が必要になるため、"システム時間" クロックタイプを使用してシステムロガーを起動しようとすると失敗します。 この制限のため、システム ロガーでは "システム時刻" クロックの種類を使用しないことを強くお勧めします。
  • Windows 10 バージョン 1703 以降では、クロックの種類の制限が削除されました。 3 つのクロック タイプすべてをシステム ロガーで同時に使用できるようになりました。

NT カーネル ロガー セッション (非推奨) を指定するには、InstanceName を KERNEL_LOGGER_NAME に設定し、Properties の Wnode.Guid メンバーを SystemTraceControlGuid に設定します。 GUID を SystemTraceControlGuid として指定しない場合、ETW は GUID 値をオーバーライドし、 SystemTraceControlGuid に設定します。

例

StartTrace を使用する例については、「イベント トレース セッションの構成と開始」を参照してください。

注意

evntrace.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして StartTrace を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント Windows Vista [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ |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 上の Advapi32.lib
[DLL] Windows 8.1 および Windows Server 2012 R2 でのSechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista でのAdvapi32.dll

関連項目

ControlTrace

EVENT_TRACE_PROPERTIES