{"id":274,"date":"2021-01-27T09:24:08","date_gmt":"2021-01-27T17:24:08","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/?p=274"},"modified":"2021-01-27T09:24:08","modified_gmt":"2021-01-27T17:24:08","slug":"controlling-the-event-session-name-with-the-instance-name","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/controlling-the-event-session-name-with-the-instance-name\/","title":{"rendered":"Controlling the event session name with the instance name"},"content":{"rendered":"

The session name, also known as the logger name, is the identifiable name of the event tracing session. When you start a tracing session using programs such as WPR or Xperf<\/a>, you are giving a name to the session either implicitly or explicitly. Most tools require an explicit name to start a trace, but WPR does not. WPR automatically creates a session name using the profile\u2019s collector element if the user does not provide one. Because of this, most users do not realize that they can explicitly set the session name.<\/p>\n

By setting the session name explicitly, you can control multiple tracing sessions. For example, you can start traces named A, B, C and then stop A, B, C or in any order. Starting and stopping multiple traces may seem intuitive but surprisingly not common user scenarios thus hidden in the command line in WPR. Let us find out how to control multiple tracing sessions in WPR and what session names mean in Event Tracing for Windows (ETW).<\/a><\/p>\n

The session name in WPR<\/h4>\n

WPR does not require the user to provide the session name directly via the commandline option. Instead, WPR constructs the session name out of the collector\u2019s name and the instance name. Taking the simplest custom profile<\/a> that we discussed in the previous post as an example, if we start the profile WPR will create the session with the name, \u201cWPR_initiated_WprApp_WPRSimpleEventLogger\u201d.<\/p>\n

The rule is:<\/p>\n

WPR_initiated_ + Instance Name + EventCollector name or \u201cWPR System Collector\u201d<\/pre>\n
In the resulting session name the instance name and Event Collector name are the variables. In case of the SystemCollector, WPR does not use the SystemCollector name and instead uses the hardcoded \u201cWPR System Collector<\/em>\u201d. That is because we want to start a single session for the system provider as we explained in Authoring Custom Profiles Part2<\/a>. Since the Event Collector name comes from the profile file, the instance name is the real variable you can set through the command line.<\/p>\n
The instance name<\/h4>\n
Let us find out how to set the instance name in WPR. The instance name is set through WPR\/WPRUI command line option by adding\u00a0-instancename somename<\/code> at the end of the command.\u00a0WPR -help advanced<\/code> explains the instance name option.<\/p>\n
\"WPR<\/p>\n
As the help text describes, you can just add the\u00a0-instancename<\/code> option to any command and that command will run with the instance name. There are two important things to remember. One is that if you don\u2019t provide the instancename option, then WPR will use the default instance name \u201cWprApp\u201d. This is why you can\u2019t start two traces in a row. If you do, you are practically starting two sessions with the same instance name \u201cWprApp\u201d. WPR starts the first trace successfully but returns E_WPRC_RUNTIME_STATE_PROFILES_RUNNING error for the second trace.<\/p>\n
\"Starting<\/p>\n
The other is that once you start the session with the specific instance name, you must use the same instance name to control or query the tracing session. As in the example below, if you start the trace with the instance name GpuTrace, then you must stop the trace with the same instance name. If you try to stop without giving the instance name, WPR generates E_WPRC_RUNTIME_STATE_PROFILES_NOT_RUNNING error, as you have not started with the default instance name \u201cWprApp\u201d.<\/p>\n
\"Once<\/p>\n
Below is the example of commands that starts multiple traces and controls\/queries the traces.<\/p>\n
e:\\wpt>wpr -start CPU.light -instancename TraceA (Starts trace with CPU.light profile)\r\n\r\ne:\\wpt>wpr -start Handle.light -instancename TraceB (Starts trace with Handle.light profile)\r\n\r\ne:\\wpt>wpr -status -instancename TraceA (Queries the TraceA session status)\r\n\r\ne:\\wpt>wpr -cancel -instancename TraceA (Cancels the TraceA session)\r\n\r\ne:\\wpt>wpr -stop TraceB.etl -instancename TraceB (Saves the TraceB session into the file)<\/pre>\n
Checking the running trace sessions<\/h5>\n
Sometimes it is useful to see currently running trace sessions in the system. Many tools can show running trace sessions, most notably Xperf and Logman. You can query active logging sessions using any of these commands. The Xperf -loggers command shows the providers and other details about each session, thus making very long console output. You would probably want to pipe the console output to the text file to review. Both tools can show a specific session by giving the session name.<\/p>\n
<\/code><\/p>\n
Logman query -ets\r\n\r\nLogman query <session name> -ets\r\n\r\nXperf -loggers\r\n\r\nXperf -loggers <session name><\/pre>\n
Above all, my favorite tool to see the active tracing sessions is the Computer Management control panel app in Windows. You can start the app by typing Computer Management in the Start Menu or compmgmt.msc in the command prompt. You can see the running trace sessions on your system under SystemTools -> Performance ->Event Trace Sessions.<\/span><\/p>\n
\"Computer<\/p>\n
The session name in ETW<\/h4>\n
If you are interested in how the session name is configured at an API level, the session name corresponds to the LoggerNameOffset in EVENT_TRACE_PROPERTIES<\/a> structure. This structure is a required parameter of the StartTrace<\/a> function, which starts the event tracing session. Once the StartTrace function succeeds, ETW returns the handle to the trace session. With this handle, further controlling of the session becomes possible, such as stopping, querying, and flushing.<\/p>\n
Closing<\/h4>\n
In this post, I explained what the session name is in ETW and how to set the session name through WPR with the instancename option. By using the instancename option, I showed examples of commands that start multiple traces and control. Finally, I introduced the tools that can show the running traces on the system. With the tools like XPerf and WPR, controlling ETW sessions should become easier.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
In this post, I explained what the session name is in ETW and how to set the session name through WPR with the instancename option. <\/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":[18,5],"class_list":["post-274","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-event-tracing-for-windows","category-windows-performance-recorder","tag-instancename","tag-wpr"],"acf":[],"blog_post_summary":"
In this post, I explained what the session name is in ETW and how to set the session name through WPR with the instancename option. <\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/posts\/274","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=274"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/posts\/274\/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=274"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/categories?post=274"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/performance-diagnostics\/wp-json\/wp\/v2\/tags?post=274"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}