[llvm] r316192 - [XRay] [docs] Document how to generate flamegraphs from xray traces.
Keith Wyss via llvm-commits
llvm-commits at lists.llvm.org
Thu Oct 19 15:35:10 PDT 2017
Author: kpw
Date: Thu Oct 19 15:35:09 2017
New Revision: 316192
URL: http://llvm.org/viewvc/llvm-project?rev=316192&view=rev
Log:
[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
Modified:
llvm/trunk/docs/XRay.rst
llvm/trunk/docs/XRayExample.rst
Modified: llvm/trunk/docs/XRay.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/XRay.rst?rev=316192&r1=316191&r2=316192&view=diff
==============================================================================
--- llvm/trunk/docs/XRay.rst (original)
+++ llvm/trunk/docs/XRay.rst Thu Oct 19 15:35:09 2017
@@ -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 dis
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
---------------
-
-We have more subcommands and modes that we're thinking of developing, in the
-following forms:
+Trace Analysis Tools
+--------------------
-- ``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
--------------
Modified: llvm/trunk/docs/XRayExample.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/XRayExample.rst?rev=316192&r1=316191&r2=316192&view=diff
==============================================================================
--- llvm/trunk/docs/XRayExample.rst (original)
+++ llvm/trunk/docs/XRayExample.rst Thu Oct 19 15:35:09 2017
@@ -195,6 +195,70 @@ Given the above two files we can re-buil
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
-------------------
More information about the llvm-commits
mailing list