1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>XRay Instrumentation — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Debugging with XRay" href="XRayExample.html" />
<link rel="prev" title="Type Metadata" href="TypeMetadata.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="XRayExample.html" title="Debugging with XRay"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="TypeMetadata.html" title="Type Metadata"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="Reference.html" accesskey="U">Reference</a> »</li>
<li class="nav-item nav-item-this"><a href="">XRay Instrumentation</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/XRay.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="xray-instrumentation">
<h1>XRay Instrumentation<a class="headerlink" href="#xray-instrumentation" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Version</dt>
<dd class="field-odd"><p>1 as of 2016-11-08</p>
</dd>
</dl>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id2">Introduction</a></p></li>
<li><p><a class="reference internal" href="#xray-in-llvm" id="id3">XRay in LLVM</a></p></li>
<li><p><a class="reference internal" href="#using-xray" id="id4">Using XRay</a></p>
<ul>
<li><p><a class="reference internal" href="#instrumenting-your-c-c-objective-c-application" id="id5">Instrumenting your C/C++/Objective-C Application</a></p></li>
<li><p><a class="reference internal" href="#llvm-function-attribute" id="id6">LLVM Function Attribute</a></p></li>
<li><p><a class="reference internal" href="#special-case-file" id="id7">Special Case File</a></p></li>
<li><p><a class="reference internal" href="#xray-runtime-library" id="id8">XRay Runtime Library</a></p></li>
<li><p><a class="reference internal" href="#basic-mode" id="id9">Basic Mode</a></p></li>
<li><p><a class="reference internal" href="#flight-data-recorder-mode" id="id10">Flight Data Recorder Mode</a></p></li>
<li><p><a class="reference internal" href="#trace-analysis-tools" id="id11">Trace Analysis Tools</a></p></li>
<li><p><a class="reference internal" href="#minimizing-binary-size" id="id12">Minimizing Binary Size</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#future-work" id="id13">Future Work</a></p>
<ul>
<li><p><a class="reference internal" href="#id1" id="id14">Trace Analysis Tools</a></p></li>
<li><p><a class="reference internal" href="#more-platforms" id="id15">More Platforms</a></p></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>XRay is a function call tracing system which combines compiler-inserted
instrumentation points and a runtime library that can dynamically enable and
disable the instrumentation.</p>
<p>More high level information about XRay can be found in the <a class="reference external" href="http://research.google.com/pubs/pub45287.html">XRay whitepaper</a>.</p>
<p>This document describes how to use XRay as implemented in LLVM.</p>
</div>
<div class="section" id="xray-in-llvm">
<h2><a class="toc-backref" href="#id3">XRay in LLVM</a><a class="headerlink" href="#xray-in-llvm" title="Permalink to this headline">¶</a></h2>
<p>XRay consists of three main parts:</p>
<ul>
<li><p>Compiler-inserted instrumentation points.</p></li>
<li><p>A runtime library for enabling/disabling tracing at runtime.</p></li>
<li><p>A suite of tools for analysing the traces.</p>
<p><strong>NOTE:</strong> As of July 25, 2018 , XRay is only available for the following
architectures running Linux: x86_64, arm7 (no thumb), aarch64, powerpc64le,
mips, mipsel, mips64, mips64el, NetBSD: x86_64, FreeBSD: x86_64 and
OpenBSD: x86_64.</p>
</li>
</ul>
<p>The compiler-inserted instrumentation points come in the form of nop-sleds in
the final generated binary, and an ELF section named <code class="docutils literal notranslate"><span class="pre">xray_instr_map</span></code> which
contains entries pointing to these instrumentation points. The runtime library
relies on being able to access the entries of the <code class="docutils literal notranslate"><span class="pre">xray_instr_map</span></code>, and
overwrite the instrumentation points at runtime.</p>
</div>
<div class="section" id="using-xray">
<h2><a class="toc-backref" href="#id4">Using XRay</a><a class="headerlink" href="#using-xray" title="Permalink to this headline">¶</a></h2>
<p>You can use XRay in a couple of ways:</p>
<ul class="simple">
<li><p>Instrumenting your C/C++/Objective-C/Objective-C++ application.</p></li>
<li><p>Generating LLVM IR with the correct function attributes.</p></li>
</ul>
<p>The rest of this section covers these main ways and later on how to customize
what XRay does in an XRay-instrumented binary.</p>
<div class="section" id="instrumenting-your-c-c-objective-c-application">
<h3><a class="toc-backref" href="#id5">Instrumenting your C/C++/Objective-C Application</a><a class="headerlink" href="#instrumenting-your-c-c-objective-c-application" title="Permalink to this headline">¶</a></h3>
<p>The easiest way of getting XRay instrumentation for your application is by
enabling the <code class="docutils literal notranslate"><span class="pre">-fxray-instrument</span></code> flag in your clang invocation.</p>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">instrument</span> <span class="o">...</span>
</pre></div>
</div>
<p>By default, functions that have at least 200 instructions (or contain a loop) will
get XRay instrumentation points. You can tweak that number through the
<code class="docutils literal notranslate"><span class="pre">-fxray-instruction-threshold=</span></code> flag:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">instrument</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">instruction</span><span class="o">-</span><span class="n">threshold</span><span class="o">=</span><span class="mi">1</span> <span class="o">...</span>
</pre></div>
</div>
<p>The loop detection can be disabled with <code class="docutils literal notranslate"><span class="pre">-fxray-ignore-loops</span></code> to use only the
instruction threshold. You can also specifically instrument functions in your
binary to either always or never be instrumented using source-level attributes.
You can do it using the GCC-style attributes or C++11-style attributes.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">xray_always_instrument</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">always_instrumented</span><span class="p">();</span>
<span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">xray_never_instrument</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">never_instrumented</span><span class="p">();</span>
<span class="kt">void</span> <span class="nf">alt_always_instrumented</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">xray_always_instrument</span><span class="p">));</span>
<span class="kt">void</span> <span class="nf">alt_never_instrumented</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">xray_never_instrument</span><span class="p">));</span>
</pre></div>
</div>
<p>When linking a binary, you can either manually link in the <a class="reference internal" href="#xray-runtime-library">XRay Runtime
Library</a> or use <code class="docutils literal notranslate"><span class="pre">clang</span></code> to link it in automatically with the
<code class="docutils literal notranslate"><span class="pre">-fxray-instrument</span></code> flag. Alternatively, you can statically link-in the XRay
runtime library from compiler-rt – those archive files will take the name of
<cite>libclang_rt.xray-{arch}</cite> where <cite>{arch}</cite> is the mnemonic supported by clang
(x86_64, arm7, etc.).</p>
</div>
<div class="section" id="llvm-function-attribute">
<h3><a class="toc-backref" href="#id6">LLVM Function Attribute</a><a class="headerlink" href="#llvm-function-attribute" title="Permalink to this headline">¶</a></h3>
<p>If you’re using LLVM IR directly, you can add the <code class="docutils literal notranslate"><span class="pre">function-instrument</span></code>
string attribute to your functions, to get the similar effect that the
C/C++/Objective-C source-level attributes would get:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i32</span> <span class="vg">@always_instrument</span><span class="p">()</span> <span class="k">uwtable</span> <span class="s">"function-instrument"</span><span class="p">=</span><span class="s">"xray-always"</span> <span class="p">{</span>
<span class="c">; ...</span>
<span class="p">}</span>
<span class="k">define</span> <span class="k">i32</span> <span class="vg">@never_instrument</span><span class="p">()</span> <span class="k">uwtable</span> <span class="s">"function-instrument"</span><span class="p">=</span><span class="s">"xray-never"</span> <span class="p">{</span>
<span class="c">; ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>You can also set the <code class="docutils literal notranslate"><span class="pre">xray-instruction-threshold</span></code> attribute and provide a
numeric string value for how many instructions should be in the function before
it gets instrumented.</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i32</span> <span class="vg">@maybe_instrument</span><span class="p">()</span> <span class="k">uwtable</span> <span class="s">"xray-instruction-threshold"</span><span class="p">=</span><span class="s">"2"</span> <span class="p">{</span>
<span class="c">; ...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="special-case-file">
<h3><a class="toc-backref" href="#id7">Special Case File</a><a class="headerlink" href="#special-case-file" title="Permalink to this headline">¶</a></h3>
<p>Attributes can be imbued through the use of special case files instead of
adding them to the original source files. You can use this to mark certain
functions and classes to be never, always, or instrumented with first-argument
logging from a file. The file’s format is described below:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Comments are supported</span>
<span class="o">[</span>always<span class="o">]</span>
fun:always_instrument
fun:log_arg1<span class="o">=</span>arg1 <span class="c1"># Log the first argument for the function</span>
<span class="o">[</span>never<span class="o">]</span>
fun:never_instrument
</pre></div>
</div>
<p>These files can be provided through the <code class="docutils literal notranslate"><span class="pre">-fxray-attr-list=</span></code> flag to clang.
You may have multiple files loaded through multiple instances of the flag.</p>
</div>
<div class="section" id="xray-runtime-library">
<h3><a class="toc-backref" href="#id8">XRay Runtime Library</a><a class="headerlink" href="#xray-runtime-library" title="Permalink to this headline">¶</a></h3>
<p>The XRay Runtime Library is part of the compiler-rt project, which implements
the runtime components that perform the patching and unpatching of inserted
instrumentation points. When you use <code class="docutils literal notranslate"><span class="pre">clang</span></code> to link your binaries and the
<code class="docutils literal notranslate"><span class="pre">-fxray-instrument</span></code> flag, it will automatically link in the XRay runtime.</p>
<p>The default implementation of the XRay runtime will enable XRay instrumentation
before <code class="docutils literal notranslate"><span class="pre">main</span></code> starts, which works for applications that have a short
lifetime. This implementation also records all function entry and exit events
which may result in a lot of records in the resulting trace.</p>
<p>Also by default the filename of the XRay trace is <code class="docutils literal notranslate"><span class="pre">xray-log.XXXXXX</span></code> where the
<code class="docutils literal notranslate"><span class="pre">XXXXXX</span></code> part is randomly generated.</p>
<p>These options can be controlled through the <code class="docutils literal notranslate"><span class="pre">XRAY_OPTIONS</span></code> environment
variable, where we list down the options and their defaults below.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 25%" />
<col style="width: 23%" />
<col style="width: 20%" />
<col style="width: 32%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Option</p></th>
<th class="head"><p>Type</p></th>
<th class="head"><p>Default</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>patch_premain</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">bool</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">false</span></code></p></td>
<td><p>Whether to patch
instrumentation points
before main.</p></td>
</tr>
<tr class="row-odd"><td><p>xray_mode</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">""</span></code></p></td>
<td><p>Default mode to
install and initialize
before <code class="docutils literal notranslate"><span class="pre">main</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p>xray_logfile_base</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">xray-log.</span></code></p></td>
<td><p>Filename base for the
XRay logfile.</p></td>
</tr>
<tr class="row-odd"><td><p>verbosity</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">int</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>
<td><p>Runtime verbosity
level.</p></td>
</tr>
</tbody>
</table>
<p>If you choose to not use the default logging implementation that comes with the
XRay runtime and/or control when/how the XRay instrumentation runs, you may use
the XRay APIs directly for doing so. To do this, you’ll need to include the
<code class="docutils literal notranslate"><span class="pre">xray_log_interface.h</span></code> from the compiler-rt <code class="docutils literal notranslate"><span class="pre">xray</span></code> directory. The important API
functions we list below:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">__xray_log_register_mode(...)</span></code>: Register a logging implementation against
a string Mode identifier. The implementation is an instance of
<code class="docutils literal notranslate"><span class="pre">XRayLogImpl</span></code> defined in <code class="docutils literal notranslate"><span class="pre">xray/xray_log_interface.h</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__xray_log_select_mode(...)</span></code>: Select the mode to install, associated with
a string Mode identifier. Only implementations registered with
<code class="docutils literal notranslate"><span class="pre">__xray_log_register_mode(...)</span></code> can be chosen with this function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__xray_log_init_mode(...)</span></code>: This function allows for initializing and
re-initializing an installed logging implementation. See
<code class="docutils literal notranslate"><span class="pre">xray/xray_log_interface.h</span></code> for details, part of the XRay compiler-rt
installation.</p></li>
</ul>
<p>Once a logging implementation has been initialized, it can be “stopped” by
finalizing the implementation through the <code class="docutils literal notranslate"><span class="pre">__xray_log_finalize()</span></code> function.
The finalization routine is the opposite of the initialization. When finalized,
an implementation’s data can be cleared out through the
<code class="docutils literal notranslate"><span class="pre">__xray_log_flushLog()</span></code> function. For implementations that support in-memory
processing, these should register an iterator function to provide access to the
data via the <code class="docutils literal notranslate"><span class="pre">__xray_log_set_buffer_iterator(...)</span></code> which allows code calling
the <code class="docutils literal notranslate"><span class="pre">__xray_log_process_buffers(...)</span></code> function to deal with the data in
memory.</p>
<p>All of this is better explained in the <code class="docutils literal notranslate"><span class="pre">xray/xray_log_interface.h</span></code> header.</p>
</div>
<div class="section" id="basic-mode">
<h3><a class="toc-backref" href="#id9">Basic Mode</a><a class="headerlink" href="#basic-mode" title="Permalink to this headline">¶</a></h3>
<p>XRay supports a basic logging mode which will trace the application’s
execution, and periodically append to a single log. This mode can be
installed/enabled by setting <code class="docutils literal notranslate"><span class="pre">xray_mode=xray-basic</span></code> in the <code class="docutils literal notranslate"><span class="pre">XRAY_OPTIONS</span></code>
environment variable. Combined with <code class="docutils literal notranslate"><span class="pre">patch_premain=true</span></code> this can allow for
tracing applications from start to end.</p>
<p>Like all the other modes installed through <code class="docutils literal notranslate"><span class="pre">__xray_log_select_mode(...)</span></code>, the
implementation can be configured through the <code class="docutils literal notranslate"><span class="pre">__xray_log_init_mode(...)</span></code>
function, providing the mode string and the flag options. Basic-mode specific
defaults can be provided in the <code class="docutils literal notranslate"><span class="pre">XRAY_BASIC_OPTIONS</span></code> environment variable.</p>
</div>
<div class="section" id="flight-data-recorder-mode">
<h3><a class="toc-backref" href="#id10">Flight Data Recorder Mode</a><a class="headerlink" href="#flight-data-recorder-mode" title="Permalink to this headline">¶</a></h3>
<p>XRay supports a logging mode which allows the application to only capture a
fixed amount of memory’s worth of events. Flight Data Recorder (FDR) mode works
very much like a plane’s “black box” which keeps recording data to memory in a
fixed-size circular queue of buffers, and have the data available
programmatically until the buffers are finalized and flushed. To use FDR mode
on your application, you may set the <code class="docutils literal notranslate"><span class="pre">xray_mode</span></code> variable to <code class="docutils literal notranslate"><span class="pre">xray-fdr</span></code> in
the <code class="docutils literal notranslate"><span class="pre">XRAY_OPTIONS</span></code> environment variable. Additional options to the FDR mode
implementation can be provided in the <code class="docutils literal notranslate"><span class="pre">XRAY_FDR_OPTIONS</span></code> environment
variable. Programmatic configuration can be done by calling
<code class="docutils literal notranslate"><span class="pre">__xray_log_init_mode("xray-fdr",</span> <span class="pre"><configuration</span> <span class="pre">string>)</span></code> once it has been
selected/installed.</p>
<p>When the buffers are flushed to disk, the result is a binary trace format
described by <a class="reference external" href="XRayFDRFormat.html">XRay FDR format</a></p>
<p>When FDR mode is on, it will keep writing and recycling memory buffers until
the logging implementation is finalized – at which point it can be flushed and
re-initialised later. To do this programmatically, we follow the workflow
provided below:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Patch the sleds, if we haven't yet.</span>
<span class="k">auto</span> <span class="n">patch_status</span> <span class="o">=</span> <span class="n">__xray_patch</span><span class="p">();</span>
<span class="c1">// Maybe handle the patch_status errors.</span>
<span class="c1">// When we want to flush the log, we need to finalize it first, to give</span>
<span class="c1">// threads a chance to return buffers to the queue.</span>
<span class="k">auto</span> <span class="n">finalize_status</span> <span class="o">=</span> <span class="n">__xray_log_finalize</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">finalize_status</span> <span class="o">!=</span> <span class="n">XRAY_LOG_FINALIZED</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// maybe retry, or bail out.</span>
<span class="p">}</span>
<span class="c1">// At this point, we are sure that the log is finalized, so we may try</span>
<span class="c1">// flushing the log.</span>
<span class="k">auto</span> <span class="n">flush_status</span> <span class="o">=</span> <span class="n">__xray_log_flushLog</span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="n">flush_status</span> <span class="o">!=</span> <span class="n">XRAY_LOG_FLUSHED</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// maybe retry, or bail out.</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The default settings for the FDR mode implementation will create logs named
similarly to the basic log implementation, but will have a different log
format. All the trace analysis tools (and the trace reading library) will
support all versions of the FDR mode format as we add more functionality and
record types in the future.</p>
<blockquote>
<div><p><strong>NOTE:</strong> We do not promise perpetual support for when we update the log
versions we support going forward. Deprecation of the formats will be
announced and discussed on the developers mailing list.</p>
</div></blockquote>
</div>
<div class="section" id="trace-analysis-tools">
<h3><a class="toc-backref" href="#id11">Trace Analysis Tools</a><a class="headerlink" href="#trace-analysis-tools" title="Permalink to this headline">¶</a></h3>
<p>We currently have the beginnings of a trace analysis tool in LLVM, which can be
found in the <code class="docutils literal notranslate"><span class="pre">tools/llvm-xray</span></code> directory. The <code class="docutils literal notranslate"><span class="pre">llvm-xray</span></code> tool currently
supports the following subcommands:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">extract</span></code>: Extract the instrumentation map from a binary, and return it as
YAML.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">account</span></code>: Performs basic function call accounting statistics with various
options for sorting, and output formats (supports CSV, YAML, and
console-friendly TEXT).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">convert</span></code>: Converts an XRay log file from one format to another. We can
convert from binary XRay traces (both basic and FDR mode) to YAML,
<a class="reference external" href="https://github.com/brendangregg/FlameGraph">flame-graph</a> friendly text
formats, as well as <cite>Chrome Trace Viewer (catapult)
<https://github.com/catapult-project/catapult></cite> formats.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">graph</span></code>: Generates a DOT graph of the function call relationships between
functions found in an XRay trace.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stack</span></code>: Reconstructs function call stacks from a timeline of function
calls in an XRay trace.</p></li>
</ul>
<p>These subcommands use various library components found as part of the XRay
libraries, distributed with the LLVM distribution. These are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">llvm/XRay/Trace.h</span></code> : 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.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">llvm/XRay/Graph.h</span></code> : A semi-generic graph type used by the graph
subcommand to conveniently represent a function call graph with statistics
associated with edges and vertices.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">llvm/XRay/InstrumentationMap.h</span></code>: A convenient tool for analyzing the
instrumentation map in XRay-instrumented object files and binaries. The
<code class="docutils literal notranslate"><span class="pre">extract</span></code> and <code class="docutils literal notranslate"><span class="pre">stack</span></code> subcommands uses this particular library.</p></li>
</ul>
</div>
<div class="section" id="minimizing-binary-size">
<h3><a class="toc-backref" href="#id12">Minimizing Binary Size</a><a class="headerlink" href="#minimizing-binary-size" title="Permalink to this headline">¶</a></h3>
<p>XRay supports several different instrumentation points including <code class="docutils literal notranslate"><span class="pre">function-entry</span></code>,
<code class="docutils literal notranslate"><span class="pre">function-exit</span></code>, <code class="docutils literal notranslate"><span class="pre">custom</span></code>, and <code class="docutils literal notranslate"><span class="pre">typed</span></code> points. These can be enabled individually
using the <code class="docutils literal notranslate"><span class="pre">-fxray-instrumentation-bundle=</span></code> flag. For example if you only wanted to
instrument function entry and custom points you could specify:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">instrument</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">instrumentation</span><span class="o">-</span><span class="n">bundle</span><span class="o">=</span><span class="n">function</span><span class="o">-</span><span class="n">entry</span><span class="p">,</span><span class="n">custom</span> <span class="o">...</span>
</pre></div>
</div>
<p>This will omit the other sled types entirely, reducing the binary size. You can also
instrument just a sampled subset of functions using instrumentation groups.
For example, to instrument only a quarter of available functions invoke:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">instrument</span> <span class="o">-</span><span class="n">fxray</span><span class="o">-</span><span class="n">function</span><span class="o">-</span><span class="n">groups</span><span class="o">=</span><span class="mi">4</span>
</pre></div>
</div>
<p>A subset will be chosen arbitrarily based on a hash of the function name. To sample a
different subset you can specify <code class="docutils literal notranslate"><span class="pre">-fxray-selected-function-group=</span></code> with a group number
in the range of 0 to <code class="docutils literal notranslate"><span class="pre">xray-function-groups</span></code> - 1. Together these options could be used
to produce multiple binaries with different instrumented subsets. If all you need is
runtime control over which functions are being traced at any given time it is better
to selectively patch and unpatch the individual functions you need using the XRay
Runtime Library’s <code class="docutils literal notranslate"><span class="pre">__xray_patch_function()</span></code> method.</p>
</div>
</div>
<div class="section" id="future-work">
<h2><a class="toc-backref" href="#id13">Future Work</a><a class="headerlink" href="#future-work" title="Permalink to this headline">¶</a></h2>
<p>There are a number of ongoing efforts for expanding the toolset building around
the XRay instrumentation system.</p>
<div class="section" id="id1">
<h3><a class="toc-backref" href="#id14">Trace Analysis Tools</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><p>Work is in progress to integrate with or develop tools to visualize findings
from an XRay trace. Particularly, the <code class="docutils literal notranslate"><span class="pre">stack</span></code> tool is being expanded to
output formats that allow graphing and exploring the duration of time in each
call stack.</p></li>
<li><p>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.</p></li>
</ul>
</div>
<div class="section" id="more-platforms">
<h3><a class="toc-backref" href="#id15">More Platforms</a><a class="headerlink" href="#more-platforms" title="Permalink to this headline">¶</a></h3>
<p>We’re looking forward to contributions to port XRay to more architectures and
operating systems.</p>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="XRayExample.html" title="Debugging with XRay"
>next</a> |</li>
<li class="right" >
<a href="TypeMetadata.html" title="Type Metadata"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="Reference.html" >Reference</a> »</li>
<li class="nav-item nav-item-this"><a href="">XRay Instrumentation</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
