Files
WiVRn/docs/profiling.md
T

7.8 KiB

Profiling WiVRn

Performance analysis for WiVRn: Perfetto tracing. For general debugging see docs/debugging.md.

Quick start

Build with tracing (server-tracing preset = server + WIVRN_USE_PERFETTO=ON):

cmake --preset server-tracing
cmake --build build-server-tracing

Self-contained in-process trace (no daemon, no script):

WIVRN_TRACING=inprocess build-server-tracing/server/wivrn-server

Connect the HMD, stream, disconnect. Each session writes a wivrn-<timestamp>-<pid>.pftrace in cwd; open it in https://ui.perfetto.dev.

System-backend capture via the daemon + wrapper:

WIVRN_TRACING=system wivrn-server     # one shell, with a client streaming
tools/perfetto/wivrn_capture.py       # WiVRn-only; --full adds Monado + ftrace

WIVRN_USE_PERFETTO defaults OFF; even built ON, tracing is inert until WIVRN_TRACING is set. The Perfetto amalgamated SDK must be installed where CMake looks (/usr/share/perfetto/sdk, override with -DPERFETTO_SDK_DIR=<dir>); no automatic fetch.

HMD profiling

adb shell setprop persist.traced.enable 1

Then use the Perfetto UI → connect device. See the Android tracing quickstart.

Backends — WIVRN_TRACING

WIVRN_TRACING enables tracing and selects how it is collected. Unset/off = disabled; unknown values warn and stay off.

Value Behavior
system Connect to an external traced daemon; an external consumer owns the session. The only mode that gives a unified system-wide capture. Use tools/perfetto/wivrn_capture.py.
inprocess wivrn-server runs the service itself and writes a self-contained .pftrace. No daemon, no sudo. WiVRn track events only — no ftrace/system data.
system+inprocess Both, independently → two separate traces (not merged).

In-process options:

  • WIVRN_TRACING_FILE — output path. A trace is written on each client disconnect and at server shutdown, so one run can produce several files. Unset → timestamped wivrn-<timestamp>-<pid>.pftrace in cwd. An explicit value expands %t (timestamp)/%p (pid) and gains a -2, -3, … suffix rather than overwriting. Written from the per-session child, so use an absolute path if unsure; parent dirs are created.
  • WIVRN_TRACING_BUFFER_KB — ring buffer size in KiB (default 65536).

A headset must be streaming during the capture window. Confirm setup by raising Monado's log level (default warn hides the lines):

XRT_LOG=info WIVRN_TRACING=system wivrn-server
# → wivrn::trace: producer socket /run/user/<uid>/wivrn-perfetto-producer.sock
# → wivrn::trace: init complete

Perfetto's default socket is root-only, so WiVRn (and the wrapper) use $XDG_RUNTIME_DIR/wivrn-perfetto-{producer,consumer}.sock (fallback /tmp). Override via PERFETTO_PRODUCER_SOCK_NAME.

Capturing — wivrn_capture.py

A wrapper around tracebox (downloaded on first run): starts the tracing services, waits for the wivrn-server producer, captures, and tears down. If no producer connects within 20s it aborts rather than write an empty trace — start wivrn-server with WIVRN_TRACING=system, stream, retry.

tools/perfetto/wivrn_capture.py                       # default: WiVRn-only, no ftrace, no sudo
tools/perfetto/wivrn_capture.py --full                # + every producer + broad ftrace (needs sudo)
tools/perfetto/wivrn_capture.py --full --cpu-only     # full producers, ftrace stripped (no sudo)
tools/perfetto/wivrn_capture.py --duration-ms 5000 -o my.pftrace
tools/perfetto/wivrn_capture.py -c custom.pbtx        # any Perfetto config

--cpu-only strips any linux.ftrace block from the config. The wrapper auto-detects ftrace in the config and only then starts traced_probes + uses sudo.

Default vs --full

Aspect default (wivrn_trace_cfg.pbtx) --full (wivrn_full_trace_cfg.pbtx)
track_event WiVRn categories only every category, every producer
ftrace none sched + freq + idle + IRQs + vblank
Buffers 64 MiB (track_event) 64 MiB track_event + 256 MiB system
sudo no yes (ftrace)
Use for encoder-pipeline questions "something outside WiVRn is doing X"

--full isolates track_event in its own buffer so the high-rate ftrace stream can't evict the WiVRn/Monado slices, and defaults to a 5 s window (override with --duration-ms). If a trace is too big to load, drop the irq/* events from a copy of the config.

Manual capture

Drive Perfetto yourself against WiVRn's default socket pair:

SOCK_DIR="${XDG_RUNTIME_DIR:-/tmp}"
export PERFETTO_PRODUCER_SOCK_NAME="$SOCK_DIR/wivrn-perfetto-producer.sock"
export PERFETTO_CONSUMER_SOCK_NAME="$SOCK_DIR/wivrn-perfetto-consumer.sock"

traced --background                                    # add sudo + traced_probes for ftrace configs
WIVRN_TRACING=system wivrn-server                      # in another shell, streaming
perfetto -c tools/perfetto/wivrn_trace_cfg.pbtx --txt -o trace.pftrace

For ftrace configs, run traced/traced_probes under sudo -E and add --set-socket-permissions "$USER:0660:$USER:0660" to traced.

Summaries

tools/perfetto/pftrace_summary.py prints per-slice stats, or a side-by-side diff for two traces:

tools/perfetto/pftrace_summary.py nvenc.pftrace                 # one trace
tools/perfetto/pftrace_summary.py nvenc.pftrace vulkan.pftrace  # diff with Δmean

Tracing Monado too

Monado's own u_trace (built on percetto) can join the same session. Build with WIVRN_TRACE_MONADO=ON (requires WIVRN_USE_PERFETTO=ON):

cmake --preset server-tracing-monado
cmake --build build-server-tracing-monado

WIVRN_TRACING=system wivrn-server     # also sets Monado's XRT_TRACING for you
tools/perfetto/wivrn_capture.py --full
  • System backend + --full only. Monado's percetto can't write in-process, and the default config allowlists only wivrn_* categories.
  • percetto must be available at configure time (pkg-config, or -DPercetto_ROOT_DIR=<path>); Monado does not fetch it. Missing → XRT_HAVE_PERCETTO specified but not available.
  • Links a second Perfetto SDK copy (percetto's); both feed one traced. Leave off unless you need Monado spans.

Adding instrumentation

Include utils/wivrn_trace.h; no #ifdef at call sites.

// CPU span (RAII; ends at scope exit)
wivrn::trace::scope s(wivrn::trace::cpu_track::encoder, stream_idx, frame_index, "my_span");

// CPU instant
wivrn::trace::cpu_instant(wivrn::trace::cpu_track::compositor, "my_event", 0, 0);

// CPU begin/end pair (lifetime spans multiple calls)
wivrn::trace::cpu_begin(wivrn::trace::cpu_track::network, stream_idx, frame_idx, "Send");
wivrn::trace::cpu_end  (wivrn::trace::cpu_track::network, stream_idx, frame_idx, "Send");

// GPU span: bracket work with a gpu_timestamp_pool's cmd_begin/cmd_end, emit after the fence
if (auto s = pool.collect(slot))
        wivrn::trace::gpu_slice(wivrn::trace::gpu_track::nvenc_copy,
                                "my_gpu_span", s->begin_ns, s->end_ns, s->frame_index, stream);

GPU begin/end come from the pool already in host-monotonic ns (via VK_EXT_calibrated_timestamps). A disabled pool (no timestamp bits, or WIVRN_TRACING unset) returns nullopt. name must outlive the emit (a literal is fine). Place the span at the operation's semantic start, not the function top.

cpu_track category track
encoder wivrn_encoder WiVRn encoder
compositor wivrn_compositor WiVRn compositor
network wivrn_network WiVRn network