qemu-trace-stap.rst (3791B)
1========================= 2QEMU SystemTap trace tool 3========================= 4 5Synopsis 6-------- 7 8**qemu-trace-stap** [*GLOBAL-OPTIONS*] *COMMAND* [*COMMAND-OPTIONS*] *ARGS*... 9 10Description 11----------- 12 13The ``qemu-trace-stap`` program facilitates tracing of the execution 14of QEMU emulators using SystemTap. 15 16It is required to have the SystemTap runtime environment installed to use 17this program, since it is a wrapper around execution of the ``stap`` 18program. 19 20Options 21------- 22 23.. program:: qemu-trace-stap 24 25The following global options may be used regardless of which command 26is executed: 27 28.. option:: --verbose, -v 29 30 Display verbose information about command execution. 31 32The following commands are valid: 33 34.. option:: list BINARY PATTERN... 35 36 List all the probe names provided by *BINARY* that match 37 *PATTERN*. 38 39 If *BINARY* is not an absolute path, it will be located by searching 40 the directories listed in the ``$PATH`` environment variable. 41 42 *PATTERN* is a plain string that is used to filter the results of 43 this command. It may optionally contain a ``*`` wildcard to facilitate 44 matching multiple probes without listing each one explicitly. Multiple 45 *PATTERN* arguments may be given, causing listing of probes that match 46 any of the listed names. If no *PATTERN* is given, the all possible 47 probes will be listed. 48 49 For example, to list all probes available in the ``qemu-system-x86_64`` 50 binary: 51 52 :: 53 54 $ qemu-trace-stap list qemu-system-x86_64 55 56 To filter the list to only cover probes related to QEMU's cryptographic 57 subsystem, in a binary outside ``$PATH`` 58 59 :: 60 61 $ qemu-trace-stap list /opt/qemu/4.0.0/bin/qemu-system-x86_64 'qcrypto*' 62 63.. option:: run OPTIONS BINARY PATTERN... 64 65 Run a trace session, printing formatted output any time a process that is 66 executing *BINARY* triggers a probe matching *PATTERN*. 67 68 If *BINARY* is not an absolute path, it will be located by searching 69 the directories listed in the ``$PATH`` environment variable. 70 71 *PATTERN* is a plain string that matches a probe name shown by the 72 *LIST* command. It may optionally contain a ``*`` wildcard to 73 facilitate matching multiple probes without listing each one explicitly. 74 Multiple *PATTERN* arguments may be given, causing all matching probes 75 to be monitored. At least one *PATTERN* is required, since stap is not 76 capable of tracing all known QEMU probes concurrently without overflowing 77 its trace buffer. 78 79 Invocation of this command does not need to be synchronized with 80 invocation of the QEMU process(es). It will match probes on all 81 existing running processes and all future launched processes, 82 unless told to only monitor a specific process. 83 84 Valid command specific options are: 85 86 .. program:: qemu-trace-stap-run 87 88 .. option:: --pid=PID, -p PID 89 90 Restrict the tracing session so that it only triggers for the process 91 identified by *PID*. 92 93 For example, to monitor all processes executing ``qemu-system-x86_64`` 94 as found on ``$PATH``, displaying all I/O related probes: 95 96 :: 97 98 $ qemu-trace-stap run qemu-system-x86_64 'qio*' 99 100 To monitor only the QEMU process with PID 1732 101 102 :: 103 104 $ qemu-trace-stap run --pid=1732 qemu-system-x86_64 'qio*' 105 106 To monitor QEMU processes running an alternative binary outside of 107 ``$PATH``, displaying verbose information about setup of the 108 tracing environment: 109 110 :: 111 112 $ qemu-trace-stap -v run /opt/qemu/4.0.0/qemu-system-x86_64 'qio*' 113 114See also 115-------- 116 117:manpage:`qemu(1)`, :manpage:`stap(1)` 118 119.. 120 Copyright (C) 2019 Red Hat, Inc. 121 122 This program is free software; you can redistribute it and/or modify 123 it under the terms of the GNU General Public License as published by 124 the Free Software Foundation; either version 2 of the License, or 125 (at your option) any later version.