QTRACE(1)

NAME
qtrace - start and stop instruction tracing in a QEMU host VM

SYNOPSIS
qtrace exec command [...]
qtrace start
qtrace stop

DESCRIPTION
The qtrace utility starts and stops logging of instruction traces in a QEMU host virtual machine. The kernel may be configured to execute in one of two modes using the sysctl(8) hw.qemu_trace_perthread: when disabled, tracing is global (across all processes) and can be controlled using the “start” and “stop” commands, or used with “exec”; when enabled, tracing is per-thread, and is enabled and disabled for hierarchies of processes using only the “exec” command.

The “start” and “stop” commands start and stop global tracing when run.

The “exec” command forks a child, starts logging, calls execvp(3) to run the command and its arguments and stops logging when the child exits.

When the hw.qemu_trace_perthread sysctl(8) is enabled, the kernel will enable and disable tracing during context swiching, turning on tracing only for threads that have been specifically marked to be traced. In this mode, other processes and threads in the system will not be traced, reducing potential noise in the resulting log.

Due to the volume of output in an instruction trace, file I/O may be backlogged for tens of second (or more) after tracing ends so make sure it has stopped before examining the output.

IMPLEMENTATION NOTES
Logging is triggered through special nop instructions and is a virtual machine property so the results of running qtrace in multiple login are apt of be confusing.

SEE ALSO
execvp(3), sysctl(8)

AUTHORS
This software and this manual page were developed by SRI International and the University of Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) (“CTSRD”), as part of the DARPA CRASH research programme.