scripts/qemu-trace-stap.texi

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