qemu

FORK: QEMU emulator
git clone https://git.neptards.moe/neptards/qemu.git
Log | Files | Refs | Submodules | LICENSE

qemu-trace-stap.rst (3845B)

      1 =========================
      2 QEMU SystemTap trace tool
      3 =========================
      4 
      5 Synopsis
      6 --------
      7 
      8 **qemu-trace-stap** [*GLOBAL-OPTIONS*] *COMMAND* [*COMMAND-OPTIONS*] *ARGS*...
      9 
     10 Description
     11 -----------
     12 
     13 The ``qemu-trace-stap`` program facilitates tracing of the execution
     14 of QEMU emulators using SystemTap.
     15 
     16 It is required to have the SystemTap runtime environment installed to use
     17 this program, since it is a wrapper around execution of the ``stap``
     18 program.
     19 
     20 Options
     21 -------
     22 
     23 .. program:: qemu-trace-stap
     24 
     25 The following global options may be used regardless of which command
     26 is executed:
     27 
     28 .. option:: --verbose, -v
     29 
     30   Display verbose information about command execution.
     31 
     32 The 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|
     50   binary:
     51 
     52   .. parsed-literal::
     53 
     54     $ qemu-trace-stap list |qemu_system|
     55 
     56   To filter the list to only cover probes related to QEMU's cryptographic
     57   subsystem, in a binary outside ``$PATH``
     58 
     59   .. parsed-literal::
     60 
     61     $ qemu-trace-stap list /opt/qemu/|version|/bin/|qemu_system| '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|
     94   as found on ``$PATH``, displaying all I/O related probes:
     95 
     96   .. parsed-literal::
     97 
     98     $ qemu-trace-stap run |qemu_system| 'qio*'
     99 
    100   To monitor only the QEMU process with PID 1732
    101 
    102   .. parsed-literal::
    103 
    104     $ qemu-trace-stap run --pid=1732 |qemu_system| '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   .. parsed-literal::
    111 
    112     $ qemu-trace-stap -v run /opt/qemu/|version|/bin/|qemu_system| 'qio*'
    113 
    114 See 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.