.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "QEMU-TRACE-STAP" "1" "Dec 16, 2025" "10.1.3" "QEMU"
.SH NAME
qemu-trace-stap \- QEMU SystemTap trace tool
.SH SYNOPSIS
.sp
\fBqemu\-trace\-stap\fP [\fIGLOBAL\-OPTIONS\fP] \fICOMMAND\fP [\fICOMMAND\-OPTIONS\fP] \fIARGS\fP\&...
.SH DESCRIPTION
.sp
The \fBqemu\-trace\-stap\fP program facilitates tracing of the execution
of QEMU emulators using SystemTap.
.sp
It is required to have the SystemTap runtime environment installed to use
this program, since it is a wrapper around execution of the \fBstap\fP
program.
.SH OPTIONS
.sp
The following global options may be used regardless of which command
is executed:
.INDENT 0.0
.TP
.B \-\-verbose, \-v
Display verbose information about command execution.
.UNINDENT
.sp
The following commands are valid:
.INDENT 0.0
.TP
.B list BINARY PATTERN...
List all the probe names provided by \fIBINARY\fP that match
\fIPATTERN\fP\&.
.sp
If \fIBINARY\fP is not an absolute path, it will be located by searching
the directories listed in the \fB$PATH\fP environment variable.
.sp
\fIPATTERN\fP is a plain string that is used to filter the results of
this command. It may optionally contain a \fB*\fP wildcard to facilitate
matching multiple probes without listing each one explicitly. Multiple
\fIPATTERN\fP arguments may be given, causing listing of probes that match
any of the listed names. If no \fIPATTERN\fP is given, the all possible
probes will be listed.
.sp
For example, to list all probes available in the qemu\-system\-x86_64
binary:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
$ qemu\-trace\-stap list qemu\-system\-x86_64
.EE
.UNINDENT
.UNINDENT
.sp
To filter the list to only cover probes related to QEMU\(aqs cryptographic
subsystem, in a binary outside \fB$PATH\fP
.INDENT 7.0
.INDENT 3.5
.sp
.EX
$ qemu\-trace\-stap list /opt/qemu/10.1.3/bin/qemu\-system\-x86_64 \(aqqcrypto*\(aq
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B run OPTIONS BINARY PATTERN...
Run a trace session, printing formatted output any time a process that is
executing \fIBINARY\fP triggers a probe matching \fIPATTERN\fP\&.
.sp
If \fIBINARY\fP is not an absolute path, it will be located by searching
the directories listed in the \fB$PATH\fP environment variable.
.sp
\fIPATTERN\fP is a plain string that matches a probe name shown by the
\fILIST\fP command. It may optionally contain a \fB*\fP wildcard to
facilitate matching multiple probes without listing each one explicitly.
Multiple \fIPATTERN\fP arguments may be given, causing all matching probes
to be monitored. At least one \fIPATTERN\fP is required, since stap is not
capable of tracing all known QEMU probes concurrently without overflowing
its trace buffer.
.sp
Invocation of this command does not need to be synchronized with
invocation of the QEMU process(es). It will match probes on all
existing running processes and all future launched processes,
unless told to only monitor a specific process.
.sp
Valid command specific options are:
.INDENT 7.0
.TP
.B \-\-pid=PID, \-p PID
Restrict the tracing session so that it only triggers for the process
identified by \fIPID\fP\&.
.UNINDENT
.sp
For example, to monitor all processes executing qemu\-system\-x86_64
as found on \fB$PATH\fP, displaying all I/O related probes:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
$ qemu\-trace\-stap run qemu\-system\-x86_64 \(aqqio*\(aq
.EE
.UNINDENT
.UNINDENT
.sp
To monitor only the QEMU process with PID 1732
.INDENT 7.0
.INDENT 3.5
.sp
.EX
$ qemu\-trace\-stap run \-\-pid=1732 qemu\-system\-x86_64 \(aqqio*\(aq
.EE
.UNINDENT
.UNINDENT
.sp
To monitor QEMU processes running an alternative binary outside of
\fB$PATH\fP, displaying verbose information about setup of the
tracing environment:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
$ qemu\-trace\-stap \-v run /opt/qemu/10.1.3/bin/qemu\-system\-x86_64 \(aqqio*\(aq
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBqemu(1)\fP, \fBstap(1)\fP
.SH COPYRIGHT
2025, The QEMU Project Developers
.\" Generated by docutils manpage writer.
.
