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).

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)
    [Windows 8.1, 8.0, 7 only: Download and install the Windows Performance Toolkit (WPT) from the Windows 8.1 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 issues a Security warning: Run only scripts that you trust... 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

Q: Where can I learn more about how to use the Windows Performance Analyzer (WPA)?

Q: Are there videos specific to this toolset?

A: Yes - Windows Performance Deep Dive (YouTube)

Q: Are similar tracing/analysis tools available on other platforms?

A: Yes. See these tools for analyzing Android, Linux, and Chromium performance
    Also: PerfCollect (for Linux)

⚠️ **GitHub.com Fallback** ⚠️