llvm.org GIT mirror llvm / 4dea1f2
[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 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@316192 91177308-0d34-0410-b5e6-96231b3b80d8 Keith Wyss 1 year, 9 months ago
2 changed file(s) with 78 addition(s) and 8 deletion(s). Raw diff Collapse all Expand all
261261 only converts to YAML.
262262 - ``graph``: Generates a DOT graph of the function call relationships between
263263 functions found in an XRay trace.
264 - ``stack``: Reconstructs function call stacks from a timeline of function
265 calls in an XRay trace.
264266
265267 These subcommands use various library components found as part of the XRay
266268 libraries, distributed with the LLVM distribution. These are:
273275 associated with edges and vertices.
274276 - ``llvm/XRay/InstrumentationMap.h``: A convenient tool for analyzing the
275277 instrumentation map in XRay-instrumented object files and binaries. The
276 ``extract`` subcommand uses this particular library.
278 ``extract`` and ``stack`` subcommands uses this particular library.
277279
278280 Future Work
279281 ===========
281283 There are a number of ongoing efforts for expanding the toolset building around
282284 the XRay instrumentation system.
283285
284 Trace Analysis
285 --------------
286
287 We have more subcommands and modes that we're thinking of developing, in the
288 following forms:
289
290 - ``stack``: Reconstruct the function call stacks in a timeline.
286 Trace Analysis Tools
287 --------------------
288
289 - Work is in progress to integrate with or develop tools to visualize findings
290 from an XRay trace. Particularly, the ``stack`` tool is being expanded to
291 output formats that allow graphing and exploring the duration of time in each
292 call stack.
293 - With a large instrumented binary, the size of generated XRay traces can
294 quickly become unwieldy. We are working on integrating pruning techniques and
295 heuristics for the analysis tools to sift through the traces and surface only
296 relevant information.
291297
292298 More Platforms
293299 --------------
194194 arguments to clang as ``-fxray-always-instrument=always-instrument.txt`` or
195195 ``-fxray-never-instrument=never-instrument.txt``.
196196
197 The XRay stack tool
198 -------------------
199
200 Given a trace, and optionally an instrumentation map, the ``llvm-xray stack``
201 command can be used to analyze a call stack graph constructed from the function
202 call timeline.
203
204 The simplest way to use the command is simply to output the top stacks by call
205 count and time spent.
206
207 ::
208
209 $ llvm-xray stack xray-log.llc.5rqxkU -instr_map ./bin/llc
210
211 Unique Stacks: 3069
212 Top 10 Stacks by leaf sum:
213
214 Sum: 9633790
215 lvl function count sum
216 #0 main 1 58421550
217 #1 compileModule(char**, llvm::LLVMContext&) 1 51440360
218 #2 llvm::legacy::PassManagerImpl::run(llvm::Module&) 1 40535375
219 #3 llvm::FPPassManager::runOnModule(llvm::Module&) 2 39337525
220 #4 llvm::FPPassManager::runOnFunction(llvm::Function&) 6 39331465
221 #5 llvm::PMDataManager::verifyPreservedAnalysis(llvm::Pass*) 399 16628590
222 #6 llvm::PMTopLevelManager::findAnalysisPass(void const*) 4584 15155600
223 #7 llvm::PMDataManager::findAnalysisPass(void const*, bool) 32088 9633790
224
225 ..etc..
226
227 In the default mode, identical stacks on different threads are independently
228 aggregated. In a multithreaded program, you may end up having identical call
229 stacks fill your list of top calls.
230
231 To address this, you may specify the ``-aggregate-threads`` or
232 ``-per-thread-stacks`` flags. ``-per-thread-stacks`` treats the thread id as an
233 implicit root in each call stack tree, while ``-aggregate-threads`` combines
234 identical stacks from all threads.
235
236 Flame Graph Generation
237 ----------------------
238
239 The ``llvm-xray stack`` tool may also be used to generate flamegraphs for
240 visualizing your instrumented invocations. The tool does not generate the graphs
241 themselves, but instead generates a format that can be used with Brendan Gregg's
242 FlameGraph tool, currently available on `github
243 `_.
244
245 To generate output for a flamegraph, a few more options are necessary.
246
247 - ``-all-stacks`` - Emits all of the stacks instead of just the top stacks.
248 - ``-stack-format`` - Choose the flamegraph output format 'flame'.
249 - ``-aggregation-type`` - Choose the metric to graph.
250
251 You may pipe the command output directly to the flamegraph tool to obtain an
252 svg file.
253
254 ::
255
256 $llvm-xray stack xray-log.llc.5rqxkU -instr_map ./bin/llc -stack-format=flame -aggregation-type=time -all-stacks | \
257 /path/to/FlameGraph/flamegraph.pl > flamegraph.svg
258
259 If you open the svg in a browser, mouse events allow exploring the call stacks.
260
197261 Further Exploration
198262 -------------------
199263