{"id":439,"date":"2021-11-08T18:32:40","date_gmt":"2021-11-09T02:32:40","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/?p=439"},"modified":"2021-11-09T09:25:54","modified_gmt":"2021-11-09T17:25:54","slug":"authoring-custom-profile-part3","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/authoring-custom-profile-part3\/","title":{"rendered":"Authoring Custom Profile &#8211; Part 3"},"content":{"rendered":"<p>This is the third post in a series about authoring custom profiles for Windows Performance Recorder (WPR).<\/p>\n<p>In previous posts I have explained;<\/p>\n<ol>\n<li>Part 1 \u2013 Introduced the simplest custom profile as an example, and explained what Profile, Collector, and Provider elements are.<\/li>\n<li>Part 2 \u2013 Developed the simplest custom profile introduced in part 1 and added SystemCollector and SystemProvider.<\/li>\n<\/ol>\n<p>Among many elements of the profile, <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows-hardware\/test\/wpt\/eventprovider\">&lt;EventProvider&gt;<\/a> is the most used element and most configurable. The subjects covered in the previous posts can get us to start capturing the events we want using the default settings. However, there are always reasons that the default settings would not meet the requirements. Let us find out more about the optional attributes that can adjust the properties of the event providers.<\/p>\n<h3>EventProvider<\/h3>\n<p><a href=\"https:\/\/docs.microsoft.com\/en-us\/windows-hardware\/test\/wpt\/eventprovider\">&lt;EventProvider&gt;<\/a> element in WPRP profile represents the configuration of the non-system ETW provider. Since there is only one system provider, everything else belongs to &lt;EventProvider&gt;. The simplest way to listen to a provider is to declare the provider and include the provider id in the &lt;Profile&gt; element as below. Refer to <a href=\"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/authoring-custom-profiles-part-1\/#the-simplest-custom-profile\">the simplest custom profile<\/a> for the full xml.<\/p>\n<p><code><\/code><\/p>\n<pre class=\"prettyprint\">&lt;EventProvider Id=\"<span style=\"color: #ff0000;\">EventProvider_WPRC_TraceLogging<\/span>\" Name=\"B781B9CC-9BCC-486C-A036-D7BF98040A6B\" \/&gt;\r\n\u2026\r\n&lt;Profile Id=\u201dWPrTest.Light.File\u201d \u2026 &gt;\r\n  &lt;Collectors&gt;\r\n    &lt;EventCollectorId Value=\"EventCollector_WPR\"&gt;\r\n      &lt;EventProviders&gt;\r\n        &lt;EventProviderId Value=\"<span style=\"color: #ff0000;\">EventProvider_WPRC_TraceLogging<\/span>\"\/&gt;\r\n      &lt;\/EventProviders&gt;\r\n    &lt;\/EventCollectorId&gt;\r\n  &lt;\/Collectors&gt;\r\n&lt;\/Profile&gt;<\/pre>\n<p><code><\/code><\/p>\n<h4><span style=\"font-size: 18pt;\">EnabeTraceEx2 API<\/span><\/h4>\n<p><a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/win32\/api\/evntrace\/nf-evntrace-enabletraceex2\">EnableTraceEx2<\/a> API is the public API to enable each event provider in a trace session one by one. Essentially, &lt;EventProvider&gt;&#8217;s child elements and attributes set the parameters of this function.<\/p>\n<h4>Required Attributes<\/h4>\n<p>As in the example above, the only thing you need to declare the provider is Id and Name attributes.<\/p>\n<ul>\n<li>Id \u2013 Unique string<\/li>\n<li>Name \u2013 the name of event provider<\/li>\n<\/ul>\n<p>Id is a straightforward unique string to declare the provider. However, Name can be a little more complex. Depending on the type of the event provider, the Name can be one of value below.<\/p>\n<ul>\n<li>Manifested provider \u2013 The registered provider name or GUID<\/li>\n<li>WPP provider \u2013 GUID<\/li>\n<li>Tracelogging provider \u2013 GUID or star(*) + name of the provider, if no GUID exists.<\/li>\n<\/ul>\n<p>To make it easy, I recommend using the descriptive unique string for the Id and GUID for the Name attributes.<\/p>\n<h4>Optional configurations &#8211; attributes and child elements<\/h4>\n<p>If you declare the event provider without any other optional attributes or child elements, WPR will give the default values to the optional configurations. This means, the keyword and level are set to the maximum possible value, and you will get all the events from the provider. The default setting maybe all you need but there is a lot more. You can listen to only certain keywords of event, certain level of the events such as warnings and beyond, collect the stacks for events, request the provider to log its state at certain time, and much more. In fact, EventProvider is the most configurable element in WPR profile schema. Let us find out how to use those commonly used optional configurations.<\/p>\n<h5>Common attributes<\/h5>\n<ul>\n<li>Stack \u2013 when set to true, you can get the stackwalk event along with the provider\u2019s events. Don\u2019t forget to use it with &lt;SystemCollector&gt; with ProcessThread and Loader to resolve symbols.<\/li>\n<li>NonPagedMemory \u2013 indicates that the trace session uses non-paged memory. Though the attribute is for the provider, the property applies to the whole session. You must set this true if the provider is running in kernel such as the driver.<\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/win32\/api\/evntrace\/nf-evntrace-enabletraceex2#parameters\">Level<\/a> \u2013 sets the maximum ETW logging verbosity level that you want the provider to write.<\/li>\n<li>CaptureStateOnly \u2013 used to indicate that the provider is not enabled for the entire tracing time, but only for the specified time such as during the start, save, or on-demand.<\/li>\n<li>Strict \u2013 indicates that the provider is critical, and trace does not start if the provider fails to be enabled, i.e., EnableTraceEx2 returns failure. Use this attribute to make sure the provider is enabled as configured.<\/li>\n<\/ul>\n<h5>Optional child Elements<\/h5>\n<ul>\n<li>Keywords \u2013 64-bit bitmask of keywords that restricts the events that you want the provider to write. If unused, the default value is 0xfffffffffffffffff. This value sets <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/win32\/api\/evntrace\/nf-evntrace-enabletraceex2#parameters\">MatchAnyKeyword<\/a> and <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/win32\/api\/evntrace\/nf-evntrace-enabletraceex2#parameters\">MatchAllKeyword<\/a> value with the same value.<\/li>\n<li>CaptureStateOnStart \u2013 requests the provider to log its state information <strong><em>when the trace starts<\/em><\/strong>, with the specified keyword value within this element. The <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/win32\/api\/evntrace\/nf-evntrace-enabletraceex2#parameters\">ControlCode<\/a> is set to EVENT_CONTROL_CODE_CAPTURE_STATE.<\/li>\n<li>CaptureStateOnSave \u2013 same as above, requests the provider when the trace stops.<\/li>\n<li>CaptureStateOnDemand \u2013 same as above, requests the provider when you execute \u2018WPR -CaptureStateOnDemand\u2019 command.<\/li>\n<\/ul>\n<h4>Examples<\/h4>\n<p>There are many examples of &lt;EventProvider&gt; used in the profile <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows-hardware\/test\/wpt\/eventprovider#example\">in MSDN doc<\/a>.<\/p>\n<h4>Common Failure Codes<\/h4>\n<p>These are common error codes with regards to the &lt;EventProvider&gt; element.<\/p>\n<table>\n<tbody>\n<tr>\n<td>Error name (code)<\/td>\n<td>Reason<\/td>\n<\/tr>\n<tr>\n<td>E_WPRC_EVENT_COLLECTOR_CONTAINS_NO_PROVIDERS<\/p>\n<p>(0xc5580612)<\/td>\n<td>You defined (probably few) providers\u00a0 but none of them are enabled in the trace session for some reason. Common reasons:<\/p>\n<ul>\n<li>NonPagedMemory is not used or set to \u201dfalse\u201d for the kernel mode provider.<\/li>\n<li>Exceeded the number of trace sessions that can enable the provider<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<tr>\n<td>E_WPRC_RUNTIME_STATE_PROVIDER_NOT_RUNNING<\/p>\n<p>(0xC558300C)<\/td>\n<td>You set Strict=\u201dtrue\u201d for the provider and the provider is not running in the session. Possible reasons are the same as above.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3><\/h3>\n<h3>Summary<\/h3>\n<p>WPR enables each event provider that is defined in &lt;EventCollector&gt; individually by using EnableTraceEx2 function. In this article, I explained about &lt;EventProvider&gt; elements and attributes that essentially set the parameters of EnableTraceEx2 function and common error codes. I left out some attributes and elements that are less common. Some of them are the event filtering elements. I hope to introduce them in the future.<\/p>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This blog post explains EventProvider element in WPR profile and its child elements and attributes. Among many elements of the profile, EventProvider is the most used element and most configurable.<\/p>\n","protected":false},"author":39815,"featured_media":77,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[4,3],"tags":[6,5,37],"class_list":["post-439","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-event-tracing-for-windows","category-windows-performance-recorder","tag-windows-performance-recorder","tag-wpr","tag-wprp"],"acf":[],"blog_post_summary":"<p>This blog post explains EventProvider element in WPR profile and its child elements and attributes. Among many elements of the profile, EventProvider is the most used element and most configurable.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/posts\/439","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/users\/39815"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/comments?post=439"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/posts\/439\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/media\/77"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/media?parent=439"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/categories?post=439"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/tags?post=439"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}