OpenHCL Tracing
Using ohcldiag-dev
ohcldiag-dev
offers several methods for collecting
different sorts of traces from OpenHCL.
We suggest starting here, before exploring some of the other options presented on this page.
(Advanced) Enable Linux Kernel Tracing
Sometimes it can be useful to extract additional information from the kernel during runtime. By default the config OpenHCL uses does not support tracing; as such you will need to build a custom kernel with tracing support. First, see the Kernel Development section of the docs to find the repo. To set up a tracing enabled kernel:
- Find
CONFIG_FTRACE
in Microsoft/hcl-dev.config and change it fromCONFIG_FTRACE is not set
toCONFIG_FTRACE=y
. - Build the kernel using the Microsoft/build-hcl-kernel.sh script.
- In the loader json you intend to use, change the
kernel_path
entry to point to your newly built vmlinux. This can usually be found at linux-dom0-hyperv/out/vmlinux. - Build OpenHCL using
cargo xflowey build-igvm --custom-kernel path/to/vmlinux
. - When launching your OpenHCL vm, be sure to Set-VmFirmwareParameters
correctly. The following is an example that enables tracing hyper-v linux
components such as vmbus:
tp_printk=1 trace_event=hyperv
tp_printk=1
tells the kernel to print traces to the kernel log.trace_events=<module>
tells the kernel which module traces to print.
[Hyper-V] Saving traces to the Windows event log
The OpenHCL traces can be saved to the Windows event log on the host. That is not meant to be a production scenario due to resource consumption concerns. By default, only ETW is emitted.
Setting PersistentGel
under the virt. key (HKLM:SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization
)
to 1
(REG_DWORD
) makes the messages being stored to the host event log, too, to make getting traces
easier in the development scenarios. The traces will be stored under the Hyper-V Worker Operational log.
Here is a Powershell one-liner to enable that developer aid:
New-ItemProperty "HKLM:SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization" -Name "PersistentGel" -Value 1 -Type Dword -Force
Note: the key has to be set prior to starting the VM to save the logging messages sent by VTL2 running inside that VM to the Windows event log.
To retrieve the events with Powershell, start with this one-liner and tweak it to your needs:
Get-WinEvent -FilterHashtable @{ LogName='Microsoft-Windows-Hyper-V-Worker-Operational'; ProviderName='Microsoft-Windows-Hyper-V-Chipset' }