diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/manual/manual.txt | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt index a66554ac..d7b0f306 100644 --- a/docs/manual/manual.txt +++ b/docs/manual/manual.txt @@ -1082,6 +1082,101 @@ You should now be able to access the qemu-system-x86_64 Spice binary. :numbered!: +Debugging +========= + +Server side +----------- + +If the virtual machine was started using QEMU directly, SPICE server logs will be output to +your console stdout. +When using libvirt, logs are located in `/var/log/libvirt/qemu/` for the qemu +system instance (`qemu:///system`), and in `~/.cache/libvirt/qemu/log` for the +qemu session instance (`qemu:///session`). + +Client side +----------- + +remote-viewer can be started with `SPICE_DEBUG=1` in the environment, or with +`--spice-debug` in order to get it to output more logs on stdout. `SPICE_DEBUG` +should work with any application using spice-gtk (virt-manager, gnome-boxes, ...). + +Guest side +---------- + +.QXL KMS driver + +On recent Linux kernels using the QXL kms driver, booting the kernel with the +`drm.debug=0xf` parameter. `journalctl -k`/`dmesg` will then contain debug +logs for the QXL kms driver. This can also be changed at runtime by echo'ing +this value to `/sys/module/drm/parameters/debug`. + + +.qxl.guestdebug QEMU parameter + +It's also possible to get some host-side debugging logs from the guest QXL driver. +The driver reads a guestdebug parameter from the rom, which can be set when starting +the VM. Only the Windows QXL driver is using this feature, see `qxl.cmdlog` for +something guest-agnostic. This can be enabled with `-global +qxl-vga.guestdebug=3`, or `-global qxl.guestdebug=3` for secondary devices. + +The corresponding libvirt XML is: + +[source,xml] +------------------------------------------------- +<domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'> + .... + <qemu:commandline> + <qemu:arg value='-global'/> + <qemu:arg value='qxl-vga.guestdebug=3'/> + </qemu:commandline> +</domain> +------------------------------------------------- + +(don't forget to add the +xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0' attribute to the +toplevel `<domain>` node) + + +You can go up to 12 (or more, look for DEBUG_PRINT in the driver), you get really a lot of debug information. Interesting values are: + + * 3 - will give you all the highlevel commands (DrvCopyBits, DrvBitBlt, etc.) + * 6 - will also show QXLGetBitMap + * 11 - will show caching of images (this is a driver cache, not to be confused with the server<->client shared cache). + + +.qxl.cmdlog QEMU parameter + +This will dump all the commands passing through the ringbuffer on the device +side. It is driver and hence guest agnostic. This can be enabled with +`-global qxl-vga.cmdlog=1`, or `-global qxl.cmdlog=1` for secondary devices. +See the section above for the libvirt XML to use. + + +Agent +~~~~~ + +On Linux, `journalctl -t spice-vdagentd -t spice-vdagent` will display the agent log messages. +spice-vdagent can also be restarted by hand with the `-d` argument in order to display more logs. + +Recording/replaying SPICE server traffic +---------------------------------------- + +Since spice-server 0.12.6, it's possible to record display traffic sent by the +SPICE server in order to replay it afterwards for a client without needing to +start a VM. This is achieved by setting the environment variable +`SPICE_WORKER_RECORD_FILENAME` to the filename to write the traffic to before starting +QEMU. + +Once the recording session is done, the `spice-server-replay` tool can be used +to replay the previously recorded SPICE session, for example: + +[source,sh] +------------------------------------------------- +spice-server-replay -p 5900 -c "remote-viewer spice://localhost:5900" recorded-session.spice +------------------------------------------------- + + [appendix] Manual authors ============== |