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 标记指定要启用的关键字、堆栈和池标记。有关所有受支持的关键字和堆栈的列表，请参阅堆栈和关键字（在 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 属性指定以下名称之一：

注册的 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 标记用于指定要启用的关键字。与系统提供程序不同，事件提供程序没有定义的文本常数。因此，事件提供程序具有十六进制值。但语法与系统提供程序的语法相同。如果未指定关键字，则默认值为 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>

示例

下面的示例定义了两个事件提供程序。

<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 (in SystemProvider)

堆叠

PoolTag