Files
WiVRn/docs/debugging.md
Jonathan Steffan b9c8a54d92 Add WiVRn-native Perfetto via Perfetto SDK
Optional server profiling built on the Perfetto SDK. Adds CPU spans
(compositor, encoder, network), GPU encode/copy slices from Vulkan timestamp
queries (Vulkan/NVENC/VAAPI), and headset feedback markers from dump_time.

WIVRN_TRACING enables tracing and selects the backend (system, inprocess, or
both); WIVRN_USE_PERFETTO gates it at build time and compiles it out otherwise.
WIVRN_TRACE_MONADO additionally drives Monado's percetto tracing from the same
switch so WiVRn and Monado land on one timeline.

Tooling: server-tracing[-monado] presets and a CI build, two Perfetto configs
(WiVRn-only and full-system), a wivrn_capture.py capture wrapper, a pftrace
summary script, and docs/profiling.md.
2026-07-01 21:04:08 +02:00

13 KiB

Debugging WiVRn

This guide covers debugging techniques for WiVRn, including log collection, crash analysis, performance profiling, and common troubleshooting scenarios.

Table of Contents


Prerequisites

ADB Setup

The Android Debug Bridge (ADB) is required for debugging the HMD client. Connect your headset to your PC via a USB data cable and authorize the connection when prompted in the HMD.

Clean Installation

When debugging, ensure the HMD client matches the server version. Perform a clean reinstall:

# Find and uninstall existing installation
WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb uninstall ${WIVRN_PKG}

# Install the debug APK
adb install /path/to/wivrn-standard-debug.apk

Collecting Logs

HMD Client Logs

The primary method to collect logs from the HMD is through ADB logcat.

Watch for crashes (FATAL priority):

adb logcat '*:F'

Record ERROR and above:

adb logcat '*:E' | tee -a errors-$(date "+%Y-%m-%d-%H").log

WiVRn-only logs (verbose):

adb logcat '*:S' WiVRn:V

Watch WiVRn client logs:

adb logcat | grep WiVRn

Watch Android system logs related to WiVRn:

adb logcat | grep wivrn

Server Logs

Start the server with debug logging enabled:

XRT_LOG=debug XRT_COMPOSITOR_LOG=debug wivrn-server

To also dump video frames for analysis:

XRT_LOG=debug XRT_COMPOSITOR_LOG=debug WIVRN_DUMP_VIDEO=/tmp/video-dump wivrn-server

The video dump can be played back with mpv or other media players to verify what video was being sent to the HMD.

There will be multiple files in the directory, one for each video stream per codec. For example, /tmp/video-dump-0.h264.


Starting Components for Debugging

HMD Client

The package name varies by build variant:

  • org.meumeu.wivrn - for app store builds
  • org.meumeu.wivrn.github - for GitHub release builds
  • org.meumeu.wivrn.local - for locally built APK
  • org.meumeu.wivrn.github.testing - for CI runs
  • org.meumeu.wivrn.github.nightly - for APK repo

Find your installed package with:

adb shell pm list packages | grep wivrn

Start via ADB:

WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb shell am start ${WIVRN_PKG}/org.meumeu.wivrn.MainActivity

Connect to a specific server:

Replace ADDRESS=localhost with the address of the server you want to connect to.

WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
ADDRESS=localhost
adb shell am start -a android.intent.action.VIEW -d "wivrn://${ADDRESS}" ${WIVRN_PKG}

Stop the client:

WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb shell am force-stop ${WIVRN_PKG}

Server

Start the server with debug logging:

XRT_LOG=debug XRT_COMPOSITOR_LOG=debug wivrn-server

The server will publish itself on the network via mDNS/Zeroconf for discovery by the HMD client.

XR Applications

Basic OpenXR application:

xrgears

To run Steam games via OpenVR, make sure to add the Steam launch options presented by the server output or in the dashboard. This is required to configure the OpenVR runtime correctly.

Some games have options to control window behavior. Try adding -windowed or -window -w 1280 -h 1024 to the game launch options to allow moving/resizing the local render window. Each game may have different options, check the game's documentation.

Note: Games linked to OpenVR require OpenComposite or xrizer to translate calls to OpenXR.


Crash Debugging

Server Crashes

Systemd

Core dumps are managed by systemd-coredump.

View the most recent crash:

coredumpctl info

Start a debugger on the most recent crash:

coredumpctl -1 debug

Inside GDB/LLDB:

# Select frame 2
f 2

# View local variables
info locals

# Print backtrace
bt

Non-Systemd Systems

On systems without systemd-coredump, core dumps are handled by the kernel directly.

Check where core dumps are written:

cat /proc/sys/kernel/core_pattern

To set a simple core pattern:

sudo sysctl -w kernel.core_pattern=/tmp/core.%e.%p.%t

This writes cores to /tmp/ with the format core.<executable>.<pid>.<timestamp>.

Analyze a core dump with GDB:

gdb /usr/bin/wivrn-server /tmp/core.wivrn-server.12345.1706234567

Inside GDB:

# Print backtrace
bt

# View all threads
info threads

# Switch to thread 2
thread 2

# Print backtrace for all threads
thread apply all bt

HMD Client Crashes

Copy the traceback from the HMD logs using logcat:

adb logcat '*:F' | grep -A 50 wivrn

Performance Profiling

WiVRn supports timing analysis via CSV dumps and detailed system-wide profiling with Perfetto. See docs/profiling.md for capturing timing data, profiling the HMD client and server, and comparing the Vulkan, NVENC, and VAAPI encoder paths.


USB Tunneling

For debugging network issues or testing with a wired connection, you can tunnel WiVRn over USB.

Set up the tunnel and connect:

WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb reverse tcp:9757 tcp:9757
adb shell am start -a android.intent.action.VIEW -d "wivrn+tcp://localhost:9757" ${WIVRN_PKG}

You are also able to make this connection through the dashboard.


Game Debugging

Proton/Wine Games

Enable additional logging for Windows compatibility layers:

PROTON_LOG=1 WINEDEBUG=vrclient,openxr,steam %command%

OpenComposite

For games using OpenVR, and you are using OpenComposite to translate calls to OpenXR.

The OpenComposite log can be found at $HOME/.local/state/OpenComposite/logs/opencomposite.log.

XRizer

To debug xrizer, you can set the RUST_LOG environment variable to control the log level.

Variable Description Default
RUST_LOG Configures the logging level for Rust applications. Accepts a comma-separated list of directives in the format module::path=level, where level can be error, warn, info, debug, or trace. For example, RUST_LOG=info,my_crate=debug sets the global level to info and the my_crate module to debug. warn

In xrizer, RUST_LOG follows the standard env_logger semantics described above. In addition, xrizer defines the following useful nonstandard logging targets:

Logging Target Description
openvr_calls Logs the name of each OpenVR function as they are called
tracked_property Logs the name and device index of each requested tracked device property

The log is located at $XDG_STATE_HOME/xrizer/xrizer.txt, or $HOME/.local/state/xrizer/xrizer.txt if $XDG_STATE_HOME is not set.


Environment Variables Reference

Compositor Settings

Variable Description Default
XRT_LOG Log level (trace, debug, info, warn, error) warn
XRT_COMPOSITOR_LOG Compositor log level (trace, debug, info, warn, error) info
OXR_VIEWPORT_SCALE_PERCENTAGE Per-application viewport scale (set on application, not server) 100

Debugging

Variable Description
WIVRN_DUMP_VIDEO Path to dump video frames (e.g., /tmp/video-dump)
WIVRN_DUMP_TIMINGS Path to dump timing CSV (e.g., /tmp/wivrn-timings.csv)
WIVRN_LOGLEVEL Log level for the native client
WIVRN_AUTOCONNECT Auto-connect to the first discovered server
WIVRN_TRACING Enable WiVRn Perfetto tracing: system / inprocess. Requires WIVRN_USE_PERFETTO=ON at build time. See docs/profiling.md.

Vulkan

Variable Description
VK_INSTANCE_LAYERS Vulkan validation layers (e.g., VK_LAYER_KHRONOS_validation)

OpenXR

Variable Description
XR_RUNTIME_JSON Path to OpenXR runtime configuration

See also the Monado compositor documentation for additional options.


Configuration Files

OpenXR Runtime Configuration

Active runtime symlink:

ls -la $HOME/.config/openxr/1/active_runtime.json

Should point to /usr/share/openxr/1/openxr_wivrn.json or similar.

Check runtime configuration:

cat /usr/share/openxr/1/openxr_wivrn.json

Example output:

{
    "file_format_version": "1.0.0",
    "runtime": {
        "name": "Monado",
        "library_path": "../../../lib64/wivrn/libopenxr_wivrn.so",
        "MND_libmonado_path": "../../../lib64/wivrn/libmonado_wivrn.so"
    }
}

Verify library dependencies:

pushd /usr/share/openxr/1/
ldd ../../../lib64/wivrn/libopenxr_wivrn.so
popd

WiVRn Server Configuration

See docs/configuration.md.


External Resources

Tools and Documentation

Monado/OpenXR

Gaming

  • OpenComposite - OpenVR to OpenXR translation
  • xrizer - OpenVR to OpenXR translation layer (Rust)

Rust

  • env_logger - Rust logging configuration via RUST_LOG

Android Debugging


Remote Native Debugging (Advanced)

This section covers attaching a native debugger to the HMD client remotely. This requires the Android NDK and familiarity with LLDB/GDB.

Start the client with debugging enabled:

WIVRN_PKG=$(adb shell pm list packages | grep wivrn | cut -d: -f2)
adb shell am start -D ${WIVRN_PKG}/org.meumeu.wivrn.MainActivity

Set up LLDB debugging:

  1. Push the LLDB server to the device:

    adb shell "mkdir -p /data/local/tmp/tools"
    adb push "$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/*/lib/linux/aarch64/lldb-server" /data/local/tmp/tools/
    
  2. Start the LLDB server on the device:

    adb shell /data/local/tmp/tools/lldb-server platform --server --listen '*:5039'
    
  3. Forward the port:

    adb forward tcp:5039 tcp:5039
    
  4. Connect from your host:

    lldb
    (lldb) platform select remote-android
    (lldb) platform connect connect://localhost:5039
    

Resume the app (required for -D flag):

adb forward tcp:12345 jdwp:$(adb shell pidof ${WIVRN_PKG})
jdb -attach localhost:12345

See the Android NDK debugging guide for more details.