[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

docs/XRay.rst

@@ -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
 --------------

docs/XRayExample.rst

@@ -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
 -------------------