OpenXR-Tracing

Windows Trace Logging (ETW) as an OpenXR API layer.

Dependencies

Python: installing from the MS store or winget should be fine.

Python is used to generate most of the code of this project, based on the OpenXR specification; the API specification is an XML file, and the OpenXR SDK source includes Python classes for processing this XML file.

Building

Open "x64 Native Tools Command Prompt for VS 2022" (or "x86 Native Tools ...."); DO NOT use "Developer Powershell for VS xxxx" or "Developer Command Prompt for VS xxxx"
cd /path/to/your/checkout
Fetch submodules: git submodule update --init
Run pwsh ./build.ps1

build.ps1 supports two flags:

-Clang: use clang-cl.exe instead of cl.exe
-SkipCodegen: don't create or update the gen/ directory
-SkipCompile: create or update the gen/ directory, but don't build

Usage

Two API layers are generated:

XR_APILAYER_FREDEMMOTT_OXRTracing
XR_APILAYER_FREDEMMOTT_OXRTracing_Alternate

These are identical, except for the name, which is included in the trace data; this allows tracing both sides of another OpenXR API layer.

Each of these layers has its' own DLL and json file in out\ after building; uou may want to disable the layer when you're not actively using this layer - it has not been optimized for performance.

Enabling the layers

You can manually add the .json file to the registry like any other layer, or use install.ps1 and wrap.ps1 as administrator. You might find list-openxr-layers handy.

With administrator powershell:

install.ps1 -Mode First

Or, last:

install.ps1 -Mode Last

You can also install the layer immediately Before or After another layer:

install.ps1 -Mode Before -RelativeTo C:\Path\To\Other\APILayer.json

You can Enable, Disable, or Remove the layer:

install.ps1 -Mode Disable

You can install both layers, on either side of another layer:

wrap.ps1 -RelativeTo C:\Path\To\Other\APILayer.json

To change the secondary layer (or any other API layer):

install.ps1 -Mode Disable -LayerPath (Get-Item out\APILayer_Alternate.json).FullName

Collecting trace data

To start collecting data, as administrator:

wpr -start OXRTracing.wprp -filemode

To finish collecting data and write an ETL file:

wpr -stop MyTraceFile.etl

If you're looking for an event log rather than profiling information, I recommend Tabnalysis.

Rationale

While the OpenXR SDK source does include a dumping layer:

OpenXR-Tracing produces ETL files; tools for ETL files like Tabnalysis and Windows Performance Analyzer are designed to deal with extremely large amounts of structured data, and work much better than browsers for this
OpenXR-Tracing produces more detailed information, such as:
- both string and handles are shown for XrPath, XrAction, and XrActionSet
- arrays are walked, e.g. composition layers, subaction paths

On the other hand, the layer included with the OpenXR SDK source has some advantages:

OpenXR-Tracing uses Windows-specific features, so can not be used on other platforms
OpenXR-Tracing currently will not handle invalid structs well, and may crash

License

This project is MIT licensed

liaxim/OpenXR-Tracing