docs/tools/qemu-trace-stap.rst

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