Skip to content

Commit 9a48dbe

Browse files
andrewleaderCopilot
andrewleader
and
Copilot
authored
Add capturing WinML logs (#1117)
* Add capturing logs * Log updates * Fix file name * Log finalization * Include WindowsAppSDK.ML Version * Apply suggestions from code review Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Copilot <[email protected]>
1 parent d9a8034 commit 9a48dbe

2 files changed

Lines changed: 253 additions & 0 deletions

File tree

‎docs/TOC.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,8 @@ items:
109109
href: ./new-windows-ml/model-catalog/model-catalog-source.md
110110
- name: Deploy your app
111111
href: ./new-windows-ml/distributing-your-app.md
112+
- name: Capture logs
113+
href: ./new-windows-ml/logs.md
112114
- name: Migrate to Windows ML
113115
href: ./new-windows-ml/migrate-to-windows-ml.md
114116
- name: Tutorial

‎docs/new-windows-ml/logs.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
---
2+
title: Capture Windows ML logs
3+
description: Learn how to capture and analyze Windows ML diagnostic logs using Event Tracing for Windows (ETW) to debug model loading, execution provider selection, and inference issues.
4+
ms.date: 02/23/2026
5+
ms.topic: how-to
6+
---
7+
8+
# Capture Windows ML logs
9+
10+
This guide walks you through capturing Windows ML diagnostic data using Event Tracing for Windows (ETW) and generating rundown logs. These logs are useful for:
11+
12+
- Debugging model loading and inference issues
13+
- Understanding execution provider (EP) selection and behavior
14+
- Identifying driver and hardware compatibility issues
15+
- Sharing detailed diagnostic data with the Windows ML team
16+
17+
## Prerequisites
18+
19+
- **Administrator privileges** (required only for Windows Performance Toolkit installation)
20+
- **PowerShell 5.1 or later**
21+
- **Windows 10 version 1903 or later** (recommended)
22+
- An application using Windows ML, or a test case to trace
23+
24+
## Step 1: Download the required files
25+
26+
Download the following files from the [WindowsML/capture-logs](https://github.com/microsoft/WindowsAppSDK-Samples/tree/main/Samples/WindowsML/capture-logs) folder on GitHub:
27+
28+
| File | Description |
29+
|------|-------------|
30+
| [`Get-WinMLRundown.ps1`](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/WindowsML/capture-logs/Get-WinMLRundown.ps1) | PowerShell script for generating rundown logs |
31+
| [`WinML.wprp`](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/WindowsML/capture-logs/WinML.wprp) | WPR profile for capturing Windows ML diagnostic data |
32+
| [`WindowsMLProfile.wpaProfile`](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/WindowsML/capture-logs/WindowsMLProfile.wpaProfile) | WPA profile for processing ETL files |
33+
34+
> [!TIP]
35+
> To download a file from GitHub, click its link to open the file, then click the **download** button near the top-right of the file view.
36+
37+
Save all three files to the same folder. You'll run commands from this folder in the following steps.
38+
39+
## Step 2: Install Windows Performance Toolkit
40+
41+
The Windows Performance Toolkit is part of the Windows SDK for Windows 11, and contains `wpaexporter.exe`, which is required to process ETL files.
42+
43+
1. Download the latest version of the [Windows SDK for Windows 11](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
44+
45+
2. Install the Windows SDK, ensuring that the **Windows Performance Toolkit** feature is selected.
46+
47+
3. Verify installation by checking that `wpaexporter.exe` exists at one of the following paths:
48+
- `%ProgramFiles%\Windows Kits\10\Windows Performance Toolkit\wpaexporter.exe`
49+
- `%ProgramFiles(x86)%\Windows Kits\10\Windows Performance Toolkit\wpaexporter.exe`
50+
51+
## Step 3: Open PowerShell as Administrator
52+
53+
Open PowerShell as Administrator (required for ETW operations) and navigate to the folder containing the required files.
54+
55+
## Step 4: Start ETW tracing with WPR
56+
57+
> [!NOTE]
58+
> If you already have an ETL file, skip to [Step 7: Generate rundown logs](#step-7-generate-rundown-logs).
59+
60+
Use Windows Performance Recorder (WPR) with the Windows ML-specific profile to capture diagnostic data.
61+
62+
Start tracing with the Windows ML profile:
63+
64+
```powershell
65+
wpr -start .\WinML.wprp -filemode
66+
```
67+
68+
## Step 5: Run your application
69+
70+
With tracing active, run your application that uses Windows ML, or your test scenario.
71+
72+
> [!IMPORTANT]
73+
> Keep the tracing session as short as possible to minimize ETL file size and processing time.
74+
75+
## Step 6: Stop ETW tracing
76+
77+
Stop the tracing session and save the ETL file:
78+
79+
```powershell
80+
wpr -stop winml_trace.etl
81+
```
82+
83+
This creates `winml_trace.etl` in the current directory containing all captured events.
84+
85+
## Step 7: Generate rundown logs
86+
87+
Process the ETL file to generate human-readable rundown logs:
88+
89+
```powershell
90+
.\Get-WinMLRundown.ps1 -EtlFilePath "winml_trace.etl" -WpaProfilePath ".\WindowsMLProfile.wpaProfile" -OutputFolder ".\rundown_output"
91+
```
92+
93+
> [!NOTE]
94+
> If you get an error that the script cannot be run because it is not digitally signed, change the execution policy for the current PowerShell session and then re-run the command above:
95+
>
96+
> ```powershell
97+
> Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
98+
> ```
99+
100+
### Script parameters
101+
102+
| Parameter | Description |
103+
|-----------|-------------|
104+
| `-EtlFilePath` | Path to the ETL file captured in Step 6. |
105+
| `-WpaProfilePath` | Path to the WPA profile (use the provided `WindowsMLProfile.wpaProfile` file). |
106+
| `-OutputFolder` | Directory where the rundown log will be created. |
107+
108+
### Output files
109+
110+
The script generates output in the specified `-OutputFolder` directory (for example, `rundown_output`):
111+
112+
- **`rundown_output\WinmlRundown.log`** - Main rundown log with categorized diagnostic data.
113+
- **Temporary CSV files** - Automatically cleaned up after processing.
114+
115+
## Understanding the rundown log
116+
117+
The generated `WinmlRundown.log` contains organized diagnostic data grouped by process.
118+
119+
### Process organization
120+
121+
Each section begins with a process header:
122+
123+
```
124+
Process: YourApplication.exe (12345)
125+
----------------------------------------
126+
```
127+
128+
### Event categories
129+
130+
#### ONNX Runtime version
131+
132+
```
133+
Onnx Version (2024/01/15 10:30:45.123):
134+
Runtime Version = 1.23.2
135+
Is Redist = true
136+
Framework Name = WinAI
137+
```
138+
139+
Shows the ONNX Runtime version and configuration. Indicates whether the redistributable version is in use and identifies the framework.
140+
141+
#### WindowsAppSDK.ML Version
142+
143+
```
144+
WindowsAppSDK.ML Version (2024/01/15 10:30:45.100):
145+
Version = 2.0.0
146+
```
147+
148+
Shows the Windows App SDK Windows ML version used by the application. Duplicate entries with the same version are suppressed
149+
150+
#### Driver info
151+
152+
```
153+
Driver Info (2024/01/15 10:30:45.200):
154+
Device Class = GPU
155+
Driver Name =
156+
Driver Version =
157+
```
158+
159+
Hardware and driver information for GPU/NPU devices. This is critical for diagnosing execution provider compatibility and hardware-specific issues.
160+
161+
#### Session creation
162+
163+
```
164+
Session Creation (2024/01/15 10:30:45.456):
165+
Schema Version = 0
166+
Session ID = 1
167+
IR Version = 8
168+
ORT Programming Projection = 1
169+
Using FP16 = false
170+
Model Weight Type = Float32
171+
Model Graph Hash = abc123...
172+
Model Weight Hash = def456...
173+
EP ID = CPUExecutionProvider
174+
```
175+
176+
Shows model loading and session initialization details, including execution provider selection, model characteristics (precision, weight type), and unique identifiers for debugging.
177+
178+
#### EP auto selection
179+
180+
```
181+
EP Auto Selection (2024/01/15 10:30:45.500):
182+
Schema Version = 0
183+
Session ID = 1
184+
Selection Policy = PREFER_NPU
185+
Requested EP = CPUExecutionProvider
186+
Available EP = DmlExecutionProvider, CPUExecutionProvider
187+
```
188+
189+
Shows the execution provider selection process, including what was requested versus what's available. The selection policy determines prioritization.
190+
191+
#### Registered providers
192+
193+
```
194+
Registered Providers (2024/01/15 10:30:45.100):
195+
PackageFamilyName =
196+
```
197+
198+
Lists available execution provider packages. Useful for diagnosing missing EP installations.
199+
200+
#### Error events
201+
202+
```
203+
====================WINML ONNX ERROR===================
204+
WinML ONNX Error (2024/01/15 10:30:46.000):
205+
Schema Version = 1
206+
HRESULT = 0x80070057
207+
Session ID = 42
208+
Error Code = INVALID_ARGUMENT
209+
Error Category = SYSTEM
210+
Error Message = Invalid input tensor dimensions
211+
File = ModelBinding.cpp
212+
Function = BindInput
213+
Line = 245
214+
```
215+
216+
Provides detailed error information with source code context, HRESULT codes, and system-level error details.
217+
218+
## Troubleshooting
219+
220+
### "wpaexporter.exe not found"
221+
222+
Follow the installation steps in [Step 2](#step-2-install-windows-performance-toolkit) to install Windows Performance Toolkit. Verify installation by checking the paths shown in that step. Ensure you ran PowerShell as Administrator during installation.
223+
224+
### "Access denied" when starting WPR
225+
226+
Run PowerShell as Administrator. ETW operations require elevated privileges.
227+
228+
### Script is not digitally signed
229+
230+
If you get an error that `Get-WinMLRundown.ps1` cannot be run because it is not digitally signed, change the execution policy for the current PowerShell session:
231+
232+
```powershell
233+
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
234+
```
235+
236+
Then, try running [Step 7](#step-7-generate-rundown-logs) again.
237+
238+
### Large ETL files
239+
240+
Keep tracing sessions short. The `-filemode` parameter is used to write traces directly to disk.
241+
242+
## Tips
243+
244+
- **Minimize trace duration**: Start tracing just before running your scenario and stop immediately after.
245+
- **Use specific scenarios**: Focus on reproducing specific issues rather than general application usage.
246+
- **Clean environment**: Close unnecessary applications to reduce noise in traces.
247+
248+
## See also
249+
250+
- [Troubleshoot execution provider download issues](execution-provider-errors.md)
251+
- [Get started with Windows ML](get-started.md)

0 commit comments

Comments
 (0)