[XRay] [docs] Document how to generate flamegraphs from xray traces.

[kpw]

Summary

Updated the XRayExample docs with instructions for using the llvm-xray stacks
command.

[dberris]

LGTM

Lovely stuff -- thanks @kpw!

docs/XRay.rst

- ``extract``: Extract the instrumentation map from a binary, and return it as
   YAML.
 - ``account``: Performs basic function call accounting statistics with various
   options for sorting, and output formats (supports CSV, YAML, and
   console-friendly TEXT).
 - ``convert``: Converts an XRay log file from one format to another. Currently
   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 functions
+  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:
 
 - ``llvm/XRay/Trace.h`` : A trace reading library for conveniently loading
   an XRay trace of supported forms, into a convenient in-memory representation.
   All the analysis tools that deal with traces use this implementation.
 - ``llvm/XRay/Graph.h`` : A semi-generic graph type used by the graph
   subcommand to conveniently represent a function call graph with statistics
   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
 ===========
 
 There are a number of ongoing efforts for expanding the toolset building around
 the XRay instrumentation system.
 
-Trace Analysis
---------------
+Trace Analysis Tools
+--------------------
+
+- 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.
+
 
-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.
 
 More Platforms
 --------------
 
 We're looking forward to contributions to port XRay to more architectures and
 operating systems.
 
 .. References...
 
 .. _`XRay whitepaper`: http://research.google.com/pubs/pub45287.html
 

docs/XRayExample.rst

::
   # never-instrument.txt
   # never instrument functions that match the following filters:
   fun:__cxx_*
 
 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
 -------------------
 
 The ``llvm-xray`` tool has a few other subcommands that are in various stages
 of being developed. One interesting subcommand that can highlight a few
 interesting things is the ``graph`` subcommand. Given for example the following
 toy program that we build with XRay instrumentation, we can see how the
 generated graph may be a helpful indicator of where time is being spent for the