Frequently Asked Questions - microsoft/MSO-Scripts GitHub Wiki

Q: What exactly is MSO-Scripts?

A: It is a script-set which greatly facilitates capturing, analyzing, and attributing
application and system resource usage via Event Tracing for Windows (ETW).
It also includes a viewer add-in for analyzing network connections and activity.

Q: What are the system requirements for using MSO-Scripts?

A1: To capture a trace requires:

Any version of Windows 11+, 10, 8.1, 8.0, 7
Windows Performance Recorder (WPR) (pre-installed on Windows 10, 11+; otherwise available in the Windows 8.1 WPT/ADK)
Any PowerShell v2+ (pre-installed on Windows)
A Windows account with Administrator privilege level

A2: To view / analyze a trace requires:

Any version of Windows 11+, 10, 8.1
The Windows Performance Analyzer (WPA)
Any PowerShell v2+ (pre-installed on Windows)

Q: What types of applications does it work with?

A: MSO-Scripts was specially designed to work with Microsoft Office and Windows.
In fact, it works well with any application type:

Native: C++ / C / Assembly
Managed: C# / Common Language Runtime
JavaScript: Chromium/V8 / Chakra

Q: How do I get started?

Either download and unzip a recent Release, or clone the Repository (select <> Code on the main page).
For analysis, also get the Windows Performance Analyzer (WPA)
Or run: winget install "Windows Performance Analyzer"
Or download and install the Windows Performance Toolkit (WPT) from the appropriate version of the Windows ADK
Capture and analyze your first CPU trace:
- MSO-Scripts\TraceCPU Start
  Exercise the application/scenario.
- MSO-Scripts\TraceCPU Stop
- MSO-Scripts\TraceCPU View Launches the Windows Performance Analyzer

Important

If the PowerShell script does not run, you can instead run the Batch script: MSO-Scripts\TraceCPU.BAT ...
See below: What if I can't run PowerShell scripts in my environment?

See the Wiki: TraceCPU
See also: WPA - Performance and Diagnostics

Q: What if I can't run PowerShell scripts in my environment?

A: PowerShell's Execution Policy, Mark of the Web, and Session Language Mode are safety features which help prevent the execution of potentially malicious scripts.

Within PowerShell, always run scripts using a path: <path>\TraceCPU Status
Even if it's in the current folder, run: .\TraceCPU Status
OR Try running the corresponding batch/CMD script: cmd /c <path>\TraceCPU.BAT Status
OR Set a temporary Execution Policy. Run: PowerShell -EP unrestricted <path>\TraceCPU.ps1 Status
OR Use (as allowed by your IT Administrator): PowerShell's Set-ExecutionPolicy
OR If Powershell reports "Security warning: Run only scripts that you trust..." then see Mark of the Web, below.
OR If Powershell reports "TraceCPU.ps1 is not digitally signed. You cannot run this script..." then see Mark of the Web, below.
OR Review the PowerShell Session Language Mode. Required: FullLanguage or RestrictedLanguage
OR Run the raw WPR commands:
- Run the MSO-Scripts commands with the -verbose option on a non-locked-down device,
  noting the underlying WPR -Start and -Stop commands:
  TraceCPU Start -verbose
  TraceCPU Stop -verbose
- Copy the referenced .WPRP (XML) files to the locked-down device.
- Run the WPR commands in the locked-down environment (Admin CMD).
  WPR.exe is pre-installed on Windows 10/11+.
- Copy the resulting .ETL trace file back to the first device and run:
  TraceCPU View -Path "<path>\<trace>.etl"

Tip

The "Mark of the Web" (MotW) is how Windows identifies files downloaded from the internet as being potentially unsafe.

For PowerShell, attempting to run MotW script files results in:
Security warning: Run only scripts that you trust...
Or if the current Execution Policy is 'RemoteSigned' then you will get:
TraceCPU.ps1 is not digitally signed. You cannot run this script on the current system.
MotW is implemented as an NTFS alternate stream named Zone.Identifier, eg.:
TraceCPU.ps1:ZoneIdentifier
To remove the "Mark of the Web":
- Run the corresponding batch script: MSO-Scripts\TraceCPU.BAT Status
- OR use PowerShell's Unblock-File command: Unblock-File *.ps1 -v