[XRay] [docs] Document how to generate flamegraphs from xray traces.
Summary: Updated the XRayExample docs with instructions for using the llvm-xray stacks command. Reviewers: dberris Subscribers: llvm-commits Differential Revision: https://reviews.llvm.org/D39106 llvm-svn: 316192
This commit is contained in:
Keith Wyss
parent
55b9e440a7
commit
b2f894ff22
|
|
@ -262,6 +262,8 @@ supports the following subcommands:
|
|||
only converts to YAML.
|
||||
- ``graph``: Generates a DOT graph of the function call relationships between
|
||||
functions found in an XRay trace.
|
||||
- ``stack``: Reconstructs function call stacks from a timeline of function
|
||||
calls in an XRay trace.
|
||||
|
||||
These subcommands use various library components found as part of the XRay
|
||||
libraries, distributed with the LLVM distribution. These are:
|
||||
|
|
@ -274,7 +276,7 @@ libraries, distributed with the LLVM distribution. These are:
|
|||
associated with edges and vertices.
|
||||
- ``llvm/XRay/InstrumentationMap.h``: A convenient tool for analyzing the
|
||||
instrumentation map in XRay-instrumented object files and binaries. The
|
||||
``extract`` subcommand uses this particular library.
|
||||
``extract`` and ``stack`` subcommands uses this particular library.
|
||||
|
||||
Future Work
|
||||
===========
|
||||
|
|
@ -282,13 +284,17 @@ Future Work
|
|||
There are a number of ongoing efforts for expanding the toolset building around
|
||||
the XRay instrumentation system.
|
||||
|
||||
Trace Analysis
|
||||
--------------
|
||||
Trace Analysis Tools
|
||||
--------------------
|
||||
|
||||
We have more subcommands and modes that we're thinking of developing, in the
|
||||
following forms:
|
||||
|
||||
- ``stack``: Reconstruct the function call stacks in a timeline.
|
||||
- Work is in progress to integrate with or develop tools to visualize findings
|
||||
from an XRay trace. Particularly, the ``stack`` tool is being expanded to
|
||||
output formats that allow graphing and exploring the duration of time in each
|
||||
call stack.
|
||||
- With a large instrumented binary, the size of generated XRay traces can
|
||||
quickly become unwieldy. We are working on integrating pruning techniques and
|
||||
heuristics for the analysis tools to sift through the traces and surface only
|
||||
relevant information.
|
||||
|
||||
More Platforms
|
||||
--------------
|
||||
|
|
|
|||
|
|
@ -195,6 +195,70 @@ Given the above two files we can re-build by providing those two files as
|
|||
arguments to clang as ``-fxray-always-instrument=always-instrument.txt`` or
|
||||
``-fxray-never-instrument=never-instrument.txt``.
|
||||
|
||||
The XRay stack tool
|
||||
-------------------
|
||||
|
||||
Given a trace, and optionally an instrumentation map, the ``llvm-xray stack``
|
||||
command can be used to analyze a call stack graph constructed from the function
|
||||
call timeline.
|
||||
|
||||
The simplest way to use the command is simply to output the top stacks by call
|
||||
count and time spent.
|
||||
|
||||
::
|
||||
|
||||
$ llvm-xray stack xray-log.llc.5rqxkU -instr_map ./bin/llc
|
||||
|
||||
Unique Stacks: 3069
|
||||
Top 10 Stacks by leaf sum:
|
||||
|
||||
Sum: 9633790
|
||||
lvl function count sum
|
||||
#0 main 1 58421550
|
||||
#1 compileModule(char**, llvm::LLVMContext&) 1 51440360
|
||||
#2 llvm::legacy::PassManagerImpl::run(llvm::Module&) 1 40535375
|
||||
#3 llvm::FPPassManager::runOnModule(llvm::Module&) 2 39337525
|
||||
#4 llvm::FPPassManager::runOnFunction(llvm::Function&) 6 39331465
|
||||
#5 llvm::PMDataManager::verifyPreservedAnalysis(llvm::Pass*) 399 16628590
|
||||
#6 llvm::PMTopLevelManager::findAnalysisPass(void const*) 4584 15155600
|
||||
#7 llvm::PMDataManager::findAnalysisPass(void const*, bool) 32088 9633790
|
||||
|
||||
..etc..
|
||||
|
||||
In the default mode, identical stacks on different threads are independently
|
||||
aggregated. In a multithreaded program, you may end up having identical call
|
||||
stacks fill your list of top calls.
|
||||
|
||||
To address this, you may specify the ``-aggregate-threads`` or
|
||||
``-per-thread-stacks`` flags. ``-per-thread-stacks`` treats the thread id as an
|
||||
implicit root in each call stack tree, while ``-aggregate-threads`` combines
|
||||
identical stacks from all threads.
|
||||
|
||||
Flame Graph Generation
|
||||
----------------------
|
||||
|
||||
The ``llvm-xray stack`` tool may also be used to generate flamegraphs for
|
||||
visualizing your instrumented invocations. The tool does not generate the graphs
|
||||
themselves, but instead generates a format that can be used with Brendan Gregg's
|
||||
FlameGraph tool, currently available on `github
|
||||
<https://github.com/brendangregg/FlameGraph>`_.
|
||||
|
||||
To generate output for a flamegraph, a few more options are necessary.
|
||||
|
||||
- ``-all-stacks`` - Emits all of the stacks instead of just the top stacks.
|
||||
- ``-stack-format`` - Choose the flamegraph output format 'flame'.
|
||||
- ``-aggregation-type`` - Choose the metric to graph.
|
||||
|
||||
You may pipe the command output directly to the flamegraph tool to obtain an
|
||||
svg file.
|
||||
|
||||
::
|
||||
|
||||
$llvm-xray stack xray-log.llc.5rqxkU -instr_map ./bin/llc -stack-format=flame -aggregation-type=time -all-stacks | \
|
||||
/path/to/FlameGraph/flamegraph.pl > flamegraph.svg
|
||||
|
||||
If you open the svg in a browser, mouse events allow exploring the call stacks.
|
||||
|
||||
Further Exploration
|
||||
-------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue