# Benchmark Metrics on WSL2 On WSL2, the benchmark automatically launches Windows Python through WSL interoperability for GPU activity and hardware power/bandwidth collection. The Makefile detects WSL2 automatically; native Linux collection remains unchanged. This helper does not change Docker Compose arguments, pipeline execution, or stream-density calculations. ## Prerequisites Follow the [hardware metrics setup guide](./wsl-hardware-metrics.md) for complete Windows/WSL checks, native Windows PCM installation, optional GPU power setup, permissions, and per-machine configuration. Install Python 3 on Windows and install the host dependencies in PowerShell: ```powershell python -m pip install psutil pywin32 ``` The Makefile defaults to `WINDOWS_PYTHON ?= python.exe`. Override it only when `python.exe` is not on WSL's `PATH` or you need a specific interpreter, using the interpreter's WSL executable path: ```makefile WINDOWS_PYTHON ?= /mnt/c/Users//AppData/Local/Programs/Python/Python311/python.exe ``` The collector and dependency setup use that executable directly. There is no automatic discovery or launcher fallback. The default `python.exe` requires a real installation on WSL's `PATH`, not the Microsoft Store placeholder. Windows Python must be able to read the repository through its `wslpath -w` path. Linux virtual environment dependencies are still installed by the Makefile targets. GPU activity requires Windows GPU Engine performance counters exposed by the graphics driver. PDH queries use English names through `AddEnglishCounter`. Package power and DRAM bandwidth require supported native Windows PCM and its driver. Optional GPU watts require Python.NET, Libre Hardware Monitor, and an explicit GPU power sensor/adapter selection. CPU package watts are never used as GPU watts. Missing hardware measurements remain `NA` in `windows_metrics.json` and are retained as `NA` in the consolidated WSL `metrics.csv`. ## Commands Run these commands from the repository root in WSL: ```bash make benchmark CAMERA_STREAM=camera_to_workload_asc_object_detection_classification.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_classification_gpu.json make consolidate-metrics ``` For stream density, pass an explicit supported configuration pair as well: ```bash make benchmark-stream-density CAMERA_STREAM=camera_to_workload_asc_object_detection_classification.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_classification_gpu.json ``` Use a CPU or GPU configuration pair for WSL2; do not use the default configurations, `_npu`, `_gpu-npu`, or `_hetero` configurations, which include unsupported NPU workloads. The Makefile detects and exports `WSL2` automatically on a Microsoft kernel. Keep optional collector settings exported in the same WSL shell. `RESULTS_DIR` defaults to the repository's `benchmark` directory. If overridden, use the same absolute directory for benchmarking and consolidation. `benchmark-quickstart` includes consolidation; ordinary `benchmark` does not. `run-lp` alone does not start the benchmark collector. No new Windows telemetry plotting integration is provided. ## Output | File | Contents | | --- | --- | | `windows_metrics.json` | Final hardware summary, source metadata, and adapter mapping | | `windows_metrics.log` | Windows worker diagnostics | | `windows_pcm_raw.log` | CSV-formatted native Windows PCM samples, when available | | `windows_pcm.log` | PCM stdout/stderr, when launched | | `windows_gpu_power_sensors.json` | Optional one-time GPU power sensor discovery | | `metrics.csv` | Consolidated metrics, generated by `make consolidate-metrics` (also part of quickstart) | Benchmark outputs above are saved in a timestamped run directory under `RESULTS_DIR`; `make benchmark` prints the exact path as `Running benchmark in:`. The one-time sensor discovery file, `windows_gpu_power_sensors.json`, is written directly to the repository's `benchmark/` directory by its setup command, not to the timestamped run directory. There is no `windows-metrics` JSONL capture directory. The helper does not generate fake qmassa or NPU files. CPU, memory utilization, disk, FPS, latency, and application log extraction retain their existing input paths; this helper supplies only hardware GPU, power, and bandwidth measurements. ## Reported measurements | CSV field | Source or meaning | | --- | --- | | `GPU_ Compute[CCS] Utilization %` | Windows Compute engine counterpart | | `GPU_ Render/3D[RCS] Utilization %` | Windows 3D engine counterpart | | `GPU_ Video[VCS] Utilization %` | Busiest available Video Decode/Encode engine | | `GPU_ VideoEnhance[VECS] Utilization %` | Windows Video Processing counterpart | | `GPU_ Blitter Copy Engine %` | Windows Copy engine counterpart | | `GPU_ GPU Power (W)` | Explicitly selected GPU power sensor, when configured and available | | `S Power Draw W` | PCM package energy divided by elapsed sample time | | `S Memory Bandwidth Usage MB/s` | PCM READ + WRITE converted from GB/s to MB/s | | `NPU Utilization %` | `NA`; NPU utilization is unavailable under WSL2 | GPU labels preserve CSV compatibility, but Windows measurements are not identical to Intel hardware counters. Process values are summed per physical engine, capped at 100%, and the busiest engine per category is used for each sample. Measurements are host-wide, including unrelated Windows applications. GPU indices start at 1 and are recorded in the JSON adapter mapping. They need not match Task Manager indices or Linux Direct Rendering Manager (DRM) card numbers. A configured GPU-power adapter is assigned `GPU_1`. Verify sensor/adapter association on each host, especially after reboot or driver changes. Unavailable measurements are `NA` in the diagnostic JSON and remain `NA` in the WSL CSV. Valid zero readings are retained as zero. The WSL consolidator ignores old Linux NPU, PCM, power/bandwidth, qmassa, and Intel® XPU Manager inputs to avoid stale hardware results. Native Linux parsing is unchanged. ## Automatic lifecycle and failures After successful Docker Compose startup, the benchmark launches the worker; sampling starts after the configured warm-up. Before Docker Compose teardown, closing worker stdin requests shutdown and finalizes the summary. A timeout forces worker termination. Normal interpreter exit also requests cleanup; abrupt host/process termination is not a validated shutdown path. Each start resets previous collector results. Stream-density collection follows the existing shared Docker Compose lifecycle, including auxiliary starts through that helper. The summary represents the latest collected run, not a best-density capture or an average across iterations. There is no per-scenario archive or automatic best-iteration selection. The density algorithm is unchanged. Collector failures are warned about and do not interrupt benchmark execution. The existing Makefile prerequisite step can still fail if Windows Python or dependency installation is unavailable. Inspect `windows_metrics.log` and `windows_pcm.log` when hardware rows are missing from the CSV or remain `NA` in the JSON. ## Validation Linux tests cover WSL guards, native no-op behavior, GPU aggregation, optional GPU power sensor filtering, missing values, PCM units, and mocked lifecycle failures. ### Windows/WSL2 validation All workloads ran successfully on both CPU and GPU on an Intel® Core™ Ultra Series 2 Windows host running WSL2. The Windows metrics collector also ran successfully during benchmarking. No source edits should normally be needed on another supported host. Installed paths, GPU sensor/adapter identifiers, permissions, and hardware support require per-machine setup. Follow the [prerequisite and verification guide](./wsl-hardware-metrics.md) before relying on the measurements.