共用方式為

建立感興趣區域的檔案

  • 發行項

相關區域檔案是包含下列節點的有效 XML 檔案：

  • InstrumentationManifest

  • 檢測

  • 區域

  • RegionsRoot，這是所有已定義區域的容器

  • 一或多個 區域 節點

注意

在區域的定義中，XML 宣告中的 版本 屬性是選擇性的，例如 version='1.0' 。

下列範例是定義簡單區域的完整 Interest 檔案區域。 範例之後會描述 Region 內屬性和節點的說明。

<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<?Copyright (c) Microsoft Corporation. All rights reserved.?>
<InstrumentationManifest>
   <Instrumentation>
      <Regions>
         <RegionRoot Guid="{EFA7A927-BAE3-48F6-92E1-000000000000}"
                     Name="Sample Region File Root"
                     FriendlyName="Root">
            <Region Guid="{d8d639a0-cf4c-45fb-976a-000111000100}"
                    Name="FastStartup-Suspend-UserSession-Shutdown"
                    FriendlyName="User Session Shutdown">
               <Start>
                  <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="301" Version="0" />
               </Start>
               <Stop>
                  <Event Provider="{331c3b3a-2005-44c2-ac5e-77220c37d6b4}" Id="22" Version="0" />
               </Stop>
            </Region>
         </RegionRoot>
      </Regions>
   </Instrumentation>
</InstrumentationManifest>

定義區域

區域定義包含 [區域 ] 節點中的下列屬性：

  • guid (區域所需的 GUID) 。

  • 名稱 (需要) ，這是區域的唯一名稱。 Name的建議格式為 Root-GrandparentName-ParentName-RegionName 。

  • FriendlyName (選擇性) ，這是區域的替代名稱。

區欄位型別

您可以根據區域啟動和停止的方式，建立下列類型的區域：

以事件為基礎的區域

最常見的區欄位型別是事件所定義的開始和停止點。

若要將事件指定為開始或停止點，您需要提供下列屬性：

  • 提供者，指定事件的提供者識別碼。

  • 識別碼，指定事件識別碼的不帶正負號簡短。

  • Version，指定事件版本的不帶正負號字元。

此外，您可以藉由新增一或多個 PayloadIdentifier 節點來進一步精簡您的定義。 這些標籤包含兩個字串屬性 FieldName 和 FieldValue，指定事件必須包含的欄位。 在使用承載欄位識別事件中，會進一步說明PayloadIdentifier標籤。

範例

以下是這種類型的區域的基本範例：

<Region Guid="{d8d639a0-cf4c-45fb-976a-000111000100}"
        Name="FastStartup-Suspend-UserSession-Shutdown"
        FriendlyName="User Session Shutdown">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="301" Version="0" />
   </Start>
   <Stop>
      <Event Provider="{331c3b3a-2005-44c2-ac5e-77220c37d6b4}" Id="22" Version="0" />
   </Stop>
</Region>

在下列範例中，只有當指定的事件包含名為 StartOrStop 且值為 Stop 的欄位時，區域才會結束：

<Region Guid="{d8d639a0-cf4c-45fb-976a-000111000100}"
        Name="FastStartup-Suspend-UserSession-Shutdown"
        FriendlyName="User Session Shutdown">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="301" Version="0" />
   </Start>
   <Stop>
      <Event Provider="{331c3b3a-2005-44c2-ac5e-77220c37d6b4}" Id="22" Version="0" />
      <PayloadIdentifier FieldName="StartOrStop" FieldValue="Stop" />
   </Stop>
</Region>

根據持續時間的區域

許多 ETW 事件都會定義為具有持續時間承載欄位的單一停止事件。 我們可以藉由從停止事件時間減去持續時間來計算起點。

[持續時間] 標籤可用於[開始] 或 [停止]標籤內，以指定要從中抓取持續時間資訊的承載欄位。 如果您定義起點的持續時間，則持續時間會從停止點減去。 同樣地，如果您定義停止點的持續時間，就會將持續時間新增至起點。

Duration節點可以有下列屬性：

  • 提供者，指定包含承載欄位之事件的提供者識別碼。

  • 識別碼，指定包含承載欄位之事件的識別碼不帶正負號的簡短。

  • Version，指定包含承載欄位之事件的版本不帶正負號字元。

  • Duration，指定承載欄位名稱的字串。

  • 乘數。 WPA 需要持續時間以奈秒為單位。 預設乘數為 1000000 (1 百萬) ，這會將毫秒轉換成奈秒。

如果您定義起點的持續時間，則持續時間會從停止點減去。 同樣地，如果您定義停止點的持續時間，就會將持續時間新增至起點。

範例

下列範例會定義在另一個區域啟動時停止的區域。 若要計算起點，我們會從停止點減去持續時間。 持續時間位於 [HiberHiberFileTime 承載] 欄位中。 然後，我們會將持續時間乘以 1，000，000，將它轉換成奈秒，並從停止點減去它。

<Region Guid="{7D6BA3F6-BC04-4776-8A7F-93CF7F4E2B6D}"
   Name="FastStartup-Suspend-WriteHiberFile"
   FriendlyName="Subscribers for Create Session">
   <Region Guid="{93783B2C-A67F-49cb-89BC-BF305D7E2CEA}"
         Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers-Child"
         FriendlyName="Hiberfile Write">
      <Start>
         <Duration Provider="{331c3b3a-2005-44c2-ac53-77220c37d6b4}" 
                   Id="117"
                   Version="0"
                   Duration="HiberHiberFileTime"
                   Multiplier="1000000" />
      </Start>
      <Stop>
         <Region RegionGuid="{EC1BB2D9-4AA8-4d82-84AA-6042FF4CFBE3}" />
      </Stop>
   </Region>
</Region>

以其他區域為基礎的區域

您可以使用[開始] 或 [停止] 節點內的[區域] 節點，定義其啟動和停止點由其他區域所定義的區域。 這個區域節點有一個強制屬性 RegionGuid，指定目的地區域的 GUID。

根據預設，其起點根據另一個區域的區域會在起點區域停止時開始。 同樣地，其停止點是以另一個區域為基礎的區域會在停止點區域啟動時停止。 您可以將選擇性屬性 Endpoint新增至 [區域] 節點，以覆寫此預設行為。 端點可以有 或 Stop 的值 Start ，並指定要用於啟動或停止事件的區域端點。

範例

下欄區域定義包含其他區域所定義的開始和停止點：

<Region Guid="{93783B2C-A67F-49cb-89BC-BF305D7E2CEA}"
        Name="FastStartup-Suspend-HiberInitTime"
        FriendlyName="Hiberfile Initialization">
   <Start>
      <Region RegionGuid="{5E81D74C-0CCC-43f9-8119-953F827BCD12}" />
   </Start>
   <Stop>
      <Region RegionGuid="{7D6BA3F6-BC04-4776-8A7F-93CF7F4E2B6D}" />
   </Stop>
</Region>

屬於其他區域容器的區域

包含其他區域的區域稱為 容器。 容器會在包含區域的第一個實例啟動時啟動，而且會在最後一個實例停止時停止。 這些區域沒有任何其他屬性。

RegionRoot 是您定義之所有區域的容器。 因此， RegionRoot 會在區域的第一個實例啟動時啟動，並在區域的最後一個實例停止時停止。

若要定義容器區域，只要定義沒有起點或停止點的區域即可。

範例

在下列範例中， 建立會話的訂閱者 是 建立會話之訂閱者子系的容器。 請注意， 建立會話的訂閱者 沒有起點或停止點。 它會在子領域的第一個實例啟動時啟動，並在子領域的最後一個實例停止時停止。

<Region Guid="{A75D8F5D-E8F8-40b8-B453-5CC70DEAC06F}"
   Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers"
   FriendlyName="Subscribers for Create Session">
   <Region Guid="{93783B2C-A67F-49cb-89BC-BF305D7E2CEA}"
           Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers-Child"
           FriendlyName="Child of Subscribers for Create Session">
      <Start>
         <Region RegionGuid="{5E81D74C-0CCC-43f9-8119-953F827BCD12}" />
      </Start>
      <Stop>
         <Region RegionGuid="{7D6BA3F6-BC04-4776-8A7F-93CF7F4E2B6D}" 
                 Endpoint="Stop" />
      </Stop>
   </Region>
</Region>

使用承載欄位來識別事件

事件識別碼屬性通常 (進程識別碼、執行緒識別碼和活動識別碼) 不足以識別特定案例。 例如，當服務啟動時，會引發一般事件，而該事件可能無法識別啟動的服務。 發生這種情況時，您必須依賴 承載欄位 以取得其他資訊。 在此情況下，其中一個其他欄位應該包含服務名稱。 您可以使用此資訊進一步指定區域開始和停止點。

若要使用承載欄位作為其他事件識別碼，請將一或多個 PayloadIdentifier 節點新增至 啟動 或 停止 節點。

PayloadIdentifier節點具有下列屬性：

  • FieldName (必要) 承載欄位的名稱。

  • FieldValue (必要) 承載值。

  • FieldValueRelationship (選擇性) 。 使用 IsEqual 指定事件必須包含承載值。 使用 DoesNotContain 指定事件不得包含承載值。 如果未指定此屬性，預設值為 IsEqual。

注意

承載欄位會區分大小寫，而且 XML 定義必須完全符合承載值。 例如，如果承載欄位具有 的值 00000 ，區域定義也必須指定 00000 為承載值。

範例

下列範例包含起始點和停止點的 PayloadIdentifier 節點：

<Region Guid="{AB719FB1-D863-4305-AE8E-F21281899A85}"
        Name="FastStartup-ConsoleSessionDisconnect"
        FriendlyName="Console Session Disconnect">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="801" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="8" />
      <PayloadIdentifier FieldName="Key" FieldValue="00000" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="802" Version="0" />
      <PayloadIdentifier FieldName="Event"
                         FieldValue="20"
                         FieldValueRelationship="DoesNotContain" />
   </Stop>
</Region>

比對區域的事件

WPA 會比對啟動事件，並停止事件，以形成稱為 事件比對的進程中的區域。 在事件層級，WPA 會根據提供者識別碼、事件識別碼、事件版本，以及任何其他指定的承載欄位，嘗試比對單一啟動或停止事件。

比對也可以延伸至區域層級，其中可以指定必須同時由開始點和停止點符合的準則。 在區域層級，您可以要求這兩個點都有相符的執行緒識別碼、進程識別碼和活動識別碼。 此外，您也可以在區域層級定義承載準則。

您可以在[區域] 節點內加入[比對] 節點，以使用區域層級比對。 Match節點包含子節點Event，可以具有下列屬性的任何組合：

  • TID="true" – 需要相符的執行緒識別碼

  • PID="true" – 需要比對進程識別碼

  • AID="true" – 需要比對活動識別碼

事件節點可以有選擇性的 Payload子節點，其中包含FieldName屬性。 此節點需要啟動和停止節點都包含指定 FieldName的相符承載值。

或者， Payload 節點也可以包含選擇性屬性 TargetFieldName。 如果指定這個屬性， 則 FieldName 只會對應至起始節點中的承載欄位，而 TargetFieldName 則對應至停止節點中的承載欄位。

範例

下列範例會在啟動事件包含承載欄位 SubscriberName時形成區域，其值符合停止節點中承載欄位 Client的值。 啟動和停止事件也必須有相符的執行緒識別碼。

<Region Guid="{A75D8F5D-E8F8-40b8-B453-5CCC70DEAC06F}"
        Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers"
        FriendlyName="Subscribers for Create Session">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="805" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="806" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Stop>
   <Match>
      <Event TID="true">
         <Payload FieldName="SubscriberName" TargetFieldName="Client" />
      </Event>
   </Match>
</Region>

根據條件篩選區域

WPA 可以包含或排除以條件為基礎的區域，或 觸發程式，它可以是事件或其他區域。 觸發程式是在 Filter 元素中指定，而包含 Filter 的區域則是 目標。

如果觸發程式是 區域， 則 Filter 必須包含區域識別碼。

如果觸發程式是事件，則 Filter必須包含具有 ETW 提供者ProviderId的Event元素，以及下列一或多個屬性：識別碼、版本、OpCode和Type。

[區欄位型別] 中稍早會說明識別碼和版本。 OpCode 是您選擇的任何值。 類型 會根據下表所述的條件來指定篩選目的地區域的模式，包括或排除目的地區域。

濾波器類型 描述
外 找到觸發事件或區域時，排除目的地區域。
前哨 在最近觸發事件或區域之後發生目標時，排除目的地區域。
OutPrev 在第一個觸發事件或區域之前發生目標時，排除目的地區域。
位於 只有在找到觸發事件或區域時，才包含目的地區域。
InPost 只有在最近觸發事件或區域之後發生目的地區域時，才包含目的地區域。
InPrev 只有在第一個觸發事件或區域之前發生目的地區域時，才包含目的地區域。

父子關聯性

您可以定義另一個區域內的區域，以建立父子關聯性。 若要讓區域成為父代，其開始時間必須早于或等於子領域的開始時間。 它也必須有晚于或等於子領域停止時間的停止時間。 如果不符合這些條件，則無法形成父子關聯性。

若要指定父區域的其他準則，請使用Match節點內的父節點。 父節點的屬性和子節點與區域層級比對中使用的事件節點相同。 您可以指定父區域和子領域必須具有相同的執行緒識別碼、進程識別碼、活動識別碼，以及任意數目的相符承載欄位。

使用承載欄位時，如果您只指定 FieldName 屬性，則父區域和子領域都必須具有該欄位的相符承載值。 如果您也指定 TargetFieldName 屬性， 則 TargetFieldName 屬性會套用至父代和子系，這表示子領域必須具有 FieldName 欄位的承載值，且符合父代中 TargetFieldName 欄位的承載值。

如果子系有多個可能的父系，則會選擇具有最早開始時間的父系。

範例

下列範例會定義父系的準則。 父代必須具有相符的執行緒識別碼，而子系中欄位的承載值 SubscriberName 必須符合父系中欄位的值 Client 。

<Region Guid="{A75D8F5D-E8F8-40b8-B453-5CC70DEAC06F}"
        Name="FastStartup-Suspend-Winlogon-CreateSession-Subscribers"
        FriendlyName="Subscribers for Create Session">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="805" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="806" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="0" />
   </Stop>
   <Match>
      <Event TID="true">
         <Payload FieldName="SubscriberName" TargetFieldName="Client" />
      </Event>
      <Parent TID="true">
         <Payload FieldName="SubscriberName" TargetFieldName="Client" />
      </Parent>
   </Match>
</Region>

自我巢狀區域

自我巢狀 是可優化父子式關聯性的選擇性功能。

自我巢狀區域是其持續時間完全包含在同層級區域的持續時間內。 這個區域實際上會成為其長期同層級的子系。

例如，假設下欄區域已啟用自我巢狀：

  • 父區域 A

  • 子領域 B1，從時間 0 開始，並在時間 6 停止

  • 子領域 B2，從時間 2 開始，並在時間 5 停止

  • 子領域 B3，從時間 3 開始，並在時間 4 停止

在此範例中，B2 會變成 B1 的子領域，B3 會變成 B2 的子領域。 建立這種類型的父子關聯性時，會選擇最接近子系開始時間的父系。

若要啟用自我巢狀，請在Match節點內新增SelfNest節點。

SelfNest節點沒有必要的參數。 不過，您可以使用用來建立一般父子關聯性的相同比對參數。 如需詳細資訊，請參閱本主題稍早的 父子關聯性 。

範例

下列範例會定義只叫用自我巢狀的 Match 標記：

<Match>
   <SelfNest />
</Match>

下列範例會定義更複雜的自我巢狀案例，此案例需要比對執行緒識別碼和承載欄位：

<Match>
   <SelfNest TID="true">
      <Payload FieldName="SubscriberName" />
   </SelfNest>
</Match>

實例名稱

您可以使用 命名 節點，將唯一名稱指派給相符區域的每個實例。 當您擁有大量相同區域的實例，或需要根據其他準則分類區域時，命名會很有用。 實例名稱可以根據承載欄位或其他區域的關聯性。

您可以使用命名節點內的 PayloadBased 節點，根據承載值 來命名 實例。 PayloadBased節點有一個必要屬性NameField，指定您要當做實例名稱使用其值的承載欄位。 這些承載欄位可以位於區域的開始或停止點。

以下是具有承載型 命名 節點的區域範例：

<Region Guid="{9261872F-D3A7-4d80-BDE3-8479CC920639}"
        Name="FastStartup-Suspend-Winlogon-EndShell-CallSubscriber"
        FriendlyName="Call Subscriber for End Shell">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="811" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="13" />
   </Start>
   <Stop>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="812" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="13" />
   </Stop>
   <Match>
      <Event PID="true" />
      <Parent PID="true" />
   </Match>
   <Naming>
      <PayloadBased NameField="SubscriberName" />
   </Naming>
</Region>

在上述範例中， 命名 節點指出啟動或停止事件包含名為 的 SubscriberName 承載欄位。 針對所建立之區域的每個實例，實例名稱是相關聯的承載值。

注意

命名區域實例時，WPA 會先檢查起始事件是否有相符的承載欄位。 如果找不到，WPA 會接著搜尋承載欄位的停止事件。 如果任一事件中找不到相符專案，就會將錯誤列印到主控台。

有時候，承載中的資訊不是我們想要的唯一資訊。 例如，如果包含的承載中的資訊是裝置識別碼，我們可能會想要將此資訊對應回裝置描述和名稱。 支援的 Type 屬性包括：

  • Device，建立名稱和描述的關聯

  • GUID，將 GUID 與區域產生關聯

  • CLSID，將類別名稱與類別識別碼產生關聯

  • PID，將進程名稱與區域產生關聯

<Naming>
   <PayloadBased NameField="SubscriberName" Type="Device" />
</Naming>

如果可以在開始和停止點中找到承載值，您可以使用選擇性 的 InstanceEndpoint 屬性來指定要使用的點。 InstanceEndpointStart 的可能值為 和 Stop 。

<Naming>
   <PayloadBased NameField="SubscriberName" InstanceEndpoint="Start" />
</Naming>

您也可以根據與其他區域的關聯性來命名區域。 若要與另一個區域產生關聯，請將 RegionBased 節點新增至 命名 節點。 RegionBased節點有四個必要屬性：

  • RegionGuid，相關聯區域的 GUID。

  • Relation，描述您所定義之區域與所關聯之區域之間的關聯性的條件值。 目前唯一支援的關聯性是 IsPresent ，這表示如果追蹤中某個位置找到相關聯的區域，則條件為 true。

  • IfRelationTrue，如果 Relation 所描述的關聯性為 true，則會使用做為實例名稱的字串值。

  • IfRelationFalse，如果 Relation 所描述的關聯性為 false，則會使用做為實例名稱的字串值。

下列範例會定義具有區域型命名的區域。 如果在追蹤中某處找到具有相符 GUID 的區域，則 的每個實例 Launch 都會命名為 Warm 。 否則，每個實例都會命名為 Cold 。

<Region Guid="{C99EFA90-F645-4A24-9576-740351171BD0}"
        Name="WinStoreAppActivationDuration"
        FriendlyName="Launch">
   <Start>
      <Event Provider="{315a8872-923e-4ea2-9889-33cd4754bf64}" Id="5901" Version="0" />
      <PayloadIdentifier FieldName="SqmableContractID" FieldValue="Windows.Launch" />
   </Start>
   <Stop>
      <Event Provider="{315a8872-923e-43a2-9889-33cd4754bf64}" Id="5902" Version="0" />
      <PayloadIdentifier FieldName="SqmableContractID" FieldValue="Windows.Launch" />
   </Stop>
   <Match>
      <Event PID="true" />
   </Match>
   <Naming>
      <RegionBased RegionGuid="{1539A93E-129C-4602-A011-431E7F73A353}" Relation="IsPresent" IfRelationTrue="Warm" IfRelationFalse="Cold" />
   </Naming>
</Region>

注意

您可以將滑鼠停留在感興趣的區域圖形中的區域實例上，以查看 WPA 中的實例名稱。

中繼資料

您可以將其他資訊新增至中繼資料 定義，格式為中繼資料，包含在 中繼資料 節點內。 例如，您可能會在中繼資料中包含說明區域準則的資訊，以便另一位使用者更輕鬆地瞭解區域的目的。 中繼資料只是額外的資料，不會影響區域的處理。

WPA 會將此中繼資料新增至感興趣的區域圖表圖表檢視中的每個區域實例。 若要檢視 WPA 中相符事件的中繼資料，只要展開圖表檢視中的區域，然後捲動至所需的中繼資料即可。 WPA 會將唯一的數位指派給中繼資料，而節點的名稱會顯示為數據行資訊。

範例

下列範例會在區域定義中包含 中繼資料 節點：

<Region Guid="{F466EE67-192C-4772-B13D-052CCD2D70B3}"
        Name="FastStartup-Suspend-Winlogon-Logoff-Subscribers"
        FriendlyName="Subscribers for Logoff">
   <Start>
      <Event Provider="{dbe9b383-7cf3-4331-91cc-a3cb16a3b538}" Id="805" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="3" />
   </Start>
   <Stop>
      <Event Provider="{db39b383-7cf3-4331-91cc-a3cb16a3b538}" Id="806" Version="0" />
      <PayloadIdentifier FieldName="Event" FieldValue="3" />
   </Stop>
   <Match>
      <Event>
         <Payload FieldName="Event" />
      </Event>
   </Match>
   <Naming>
      <PayloadBased NameField="SubscriberName" />
   </Naming>
   <Metadata>
      <FAS.TestNode>yes</FAS.TestNode>
   </Metadata>
</Region>

感興趣的區域

WPA 功能