StartTraceA 関数 (evntrace.h)

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

構文

ULONG WMIAPI StartTraceA(
            CONTROLTRACE_ID         *TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

パラメーター

TraceId

[in] InstanceName

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

この関数は、指定したセッション名を 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 またはその他の システム プロバイダーからイベントを受信するには、次のいずれかが当てはまる必要があります。

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

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

• 同じシステムでアクティブなシステム ロガーは 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 を使用する例については、「イベント トレース セッションの構成と開始」を参照してください。

要件

こちらもご覧ください

ControlTrace

EVENT_TRACE_PROPERTIES