2.システムとイベントプロバイダーの定義

[アーティクル]
06/20/2023

Windows Performance Recorder (WPR) の記録プロファイルは、.wprp 拡張子が付いた XML ファイルに保存されます。システムプロバイダーの定義では、.wprp ファイルでシステムのキーワード、スタック、メモリプールタグを指定します。

プロバイダーの定義

.wprp ファイル内の項目は、次の順序で定義する必要があります。

すべてのコレクター
システムプロバイダー
イベントプロバイダー
ヒーププロバイダー (存在する場合)
すべてのプロファイル

状況によっては、プロバイダーはプロファイル定義の前ではなく、その中で定義することもできます。次に例を示します。

<EventCollector Id="Collector1" Name="Sample Event Collector">
   <BufferSize Value="128"/>
   <Buffers Value="64"/>
</EventCollector>

<Profile Id="Sample.Verbose.File" Name="Sample" Description="Sample profile" DetailLevel="Verbose" LoggingMode="File">
   <Collectors>
      <EventCollectorId Value="Collector1">
         <EventProviders>
            <EventProvider Id="EventProvider_Microsoft-Windows-Kernel-Power" Name="Microsoft-Windows-Kernel-Power" NonPagedMemory="true">
               <Keywords>
                  <Keyword Value="0x4"/>
               </Keywords>
            </EventProvider>
         </EventProviders>
      </EventCollectorId>
   </Collectors>
</Profile>

システムプロバイダー

システムプロバイダーの定義で必須の属性は、Id だけです。内部 XML タグでは、有効にするキーワード、スタック、プールタグを指定します。すべてのサポートされているキーワードとスタックの一覧については、「Stack」と「Keyword (SystemProvider 内)」を参照してください。

次のコードは、システムプロバイダー定義の例です。

<SystemProvider
  Id="system-provider">
  <Keywords>
    <Keyword
      Value="ProcessThread"/>
    <Keyword
      Value="Loader"/>
    <Keyword
      Value="CSwitch"/>
  </Keywords>
  <Stacks>
    <Stack
      Value="ThreadCreate"/>
    <Stack
      Value="ReadyThread"/>
    <Stack
      Value="CSwitch"/>
  </Stacks>
  <PoolTags>
    <PoolTag
      Value="a*"/>
    <PoolTag
      Value="b*"/>
    <PoolTag
      Value="c*"/>
    <PoolTag
      Value="d*"/>
  </PoolTags>
</SystemProvider>

イベントプロバイダー

イベントプロバイダーの定義では、使用する Windows イベントトレーシング (ETW) プロバイダーと、有効にするキーワードとレベルを指定します。イベントプロバイダーの定義では、Name 属性と Id 属性が必須です。

Name 属性では、次の名前のうち 1 つを指定します。

登録された Crimson プロバイダーの名前。例: "Microsoft-Windows-Search-Core"。
プロバイダーの GUID。例: "49c2c27c-fe2d-40bf-8c4e-c3fb518037e7"。
以前のプロバイダーの名前。例: "IE6"。
特殊な名前。例: "PerfTrack"、"DotNetProvider"。

次のオプションの属性を使用して、プロバイダーのパラメーターを微調整できます。

Stack: プロバイダーがスタックをキャプチャするかどうかを指定します。既定の設定は "false" です。
Level: ETW のログ記録レベルを指定します。既定の設定は 0xFF です。
NonPagedMemory: WPR が、このプロバイダーのバッファーに非ページメモリを使用するかどうかを指定します。既定の設定は "false" です。

警告一部の Windows イベントプロバイダーでは、トレースキャプチャにおいて非ページメモリを使用する必要があります。 NonPagedMemory が必要なイベントプロバイダーの例は、EventProvider_Microsoft-Windows-Win32k です。
CaptureStateOnly: "true" に設定されている場合、WPR がこのプロバイダーを特定のキャプチャ状態でのみ有効にすることを示します。
SID: ログされたイベントの拡張データに、ユーザーのセキュリティ識別子 (SID) が含まれるかどうかを指定します。
TSID: "true" に設定されている場合、ログされたイベントの拡張データにターミナルセッション識別子を指定します。

オプションの内部 XML タグは、有効にするキーワードを指定します。システムプロバイダーとは異なり、イベントプロバイダーには定義された文字列定数はありません。そのため、イベントプロバイダーでは 16 進数の値を使用します。ただし、構文はシステムプロバイダーと同じです。キーワードを指定しない場合、既定値は 0xFFFFFFFFFFFFFFFF です。

ヒープイベントプロバイダー

ヒーププロバイダーの定義は、WPR がヒープイベントをキャプチャするプロセスのプロセス識別子を指定します。必須の属性は Id のみです。子要素 HeapProcessId は必須ではありません。この要素は、分析するプロセスのプロセス Id 属性を指定します。次の例は、その方法を示したものです。

<HeapEventProvider
  Id="Base_Heap_Provider">
</HeapEventProvider>
<HeapEventProvider
  Base="Base_Heap_Provider"
  Id="Derived_Heap_Provider">
  <HeapProcessIds Operation="Set">
    <HeapProcessId Value="2314"/>
  </HeapProcessIds>
</HeapEventProvider>

キャプチャ状態プロバイダー

トレースセッション全体で有効にされる通常のプロバイダーとは異なり、キャプチャ状態プロバイダーは、キャプチャセッションを保存または開始した時にのみ有効になります。次の例は、通常のプロバイダーとキャプチャ状態プロバイダーの両方を示しています。

<EventProvider Id="sample-provider" Name="SampleProvider" NonPagedMemory="true" Level="5">
  <Keywords>
    <Keyword Value="0x98"/> <!-- Provider is enabled with these keywords throughout the tracing session. -->
  </Keywords>
  <CaptureStateOnStart>
    <Keyword Value="0xff4"/> <!-- Provider is enabled with these keywords when tracing is started. -->
  </CaptureStateOnStart>
  <CaptureStateOnSave>
    <Keyword Value="0x118"/> <!-- Provider is enabled with these keywords when tracing is saved. -->
  </CaptureStateOnSave>
</EventProvider>

<EventProvider Id="EventProvider_DWMWin32k_CaptureState" Name="e7ef96be-969f-414f-97d7-3ddb7b558ccc" NonPagedMemory="true" CaptureStateOnly="true" >
  <!-- CaptureStateOnly="true" means provider is not enabled throughout the tracing session. -->
  <CaptureStateOnSave>
    <Keyword Value="0x80000"/> <!-- Provider is enabled with these keywords when tracing is saved. -->
  </CaptureStateOnSave>
</EventProvider>

例

次のコードは、2 つのイベントプロバイダーを定義する例です。

<EventProvider
  Id="Win32K-provider"
  Name="Microsoft-Windows-Win32K"
  NonPagedMemory="true"
  Stack="true">
  <Keywords>
    <Keyword
      Value="0x240000"/>
  </Keywords>
</EventProvider>

<EventProvider
  Id="Search-Core-provider"
  Name="Microsoft-Windows-Search-Core"/>

Keyword (SystemProvider 内)

スタック

PoolTag