llvm.org GIT mirror llvm / f70da78
[XRay][Docs] Add documentation for XRay in LLVM Summary: This is the initial version of the documentation for how to use XRay as it stands in LLVM, Clang, and compiler-rt. We leave some room for later expansion mentioining what is work in progress and what could be expected moving forward. We also give a high level overview of future work that's both ongoing and planned. Reviewers: echristo, dblaikie, chandlerc Subscribers: mehdi_amini, llvm-commits Differential Revision: https://reviews.llvm.org/D26386 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@286319 91177308-0d34-0410-b5e6-96231b3b80d8 Dean Michael Berris 2 years ago
2 changed file(s) with 223 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 ====================
1 XRay Instrumentation
2 ====================
3
4 :Version: 1 as of 2016-11-08
5
6 .. contents::
7 :local:
8
9
10 Introduction
11 ============
12
13 XRay is a function call tracing system which combines compiler-inserted
14 instrumentation points and a runtime library that can dynamically enable and
15 disable the instrumentation.
16
17 More high level information about XRay can be found in the `XRay whitepaper`_.
18
19 This document describes how to use XRay as implemented in LLVM.
20
21 XRay in LLVM
22 ============
23
24 XRay consists of three main parts:
25
26 - Compiler-inserted instrumentation points.
27 - A runtime library for enabling/disabling tracing at runtime.
28 - A suite of tools for analysing the traces.
29
30 **NOTE:** As of the time of this writing, XRay is only available for x86_64
31 and arm7 32-bit (no-thumb) Linux.
32
33 The compiler-inserted instrumentation points come in the form of nop-sleds in
34 the final generated binary, and an ELF section named ``xray_instr_map`` which
35 contains entries pointing to these instrumentation points. The runtime library
36 relies on being able to access the entries of the ``xray_instr_map``, and
37 overwrite the instrumentation points at runtime.
38
39 Using XRay
40 ==========
41
42 You can use XRay in a couple of ways:
43
44 - Instrumenting your C/C++/Objective-C/Objective-C++ application.
45 - Generating LLVM IR with the correct function attributes.
46
47 The rest of this section covers these main ways and later on how to customise
48 what XRay does in an XRay-instrumented binary.
49
50 Instrumenting your C/C++/Objective-C Application
51 ------------------------------------------------
52
53 The easiest way of getting XRay instrumentation for your application is by
54 enabling the ``-fxray-instrument`` flag in your clang invocation.
55
56 For example:
57
58 ::
59
60 clang -fxray-instrument ..
61
62 By default, functions that have at least 200 instructions will get XRay
63 instrumentation points. You can tweak that number through the
64 ``-fxray-instruction-threshold=`` flag:
65
66 ::
67
68 clang -fxray-instrument -fxray-instruction-threshold=1 ..
69
70 You can also specifically instrument functions in your binary to either always
71 or never be instrumented using source-level attributes. You can do it using the
72 GCC-style attributes or C++11-style attributes.
73
74 .. code-block:: c++
75
76 [[clang::xray_always_intrument]] void always_instrumented();
77
78 [[clang::xray_never_instrument]] void never_instrumented();
79
80 void alt_always_instrumented() __attribute__((xray_always_intrument));
81
82 void alt_never_instrumented() __attribute__((xray_never_instrument));
83
84 When linking a binary, you can either manually link in the `XRay Runtime
85 Library`_ or use ``clang`` to link it in automatically with the
86 ``-fxray-instrument`` flag.
87
88 LLVM Function Attribute
89 -----------------------
90
91 If you're using LLVM IR directly, you can add the ``function-instrument``
92 string attribute to your functions, to get the similar effect that the
93 C/C++/Objective-C source-level attributes would get:
94
95 .. code-block:: llvm
96
97 define i32 @always_instrument() uwtable "function-instrument"="xray-always" {
98 // ...
99 }
100
101 define i32 @never_instrument() uwtable "function-instrument"="xray-never" {
102 // ...
103 }
104
105 You can also set the ``xray-instruction-threshold`` attribute and provide a
106 numeric string value for how many instructions should be in the function before
107 it gets instrumented.
108
109 .. code-block:: llvm
110
111 define i32 @maybe_instrument() uwtable "xray-instruction-threshold"="2" {
112 // ...
113 }
114
115 XRay Runtime Library
116 --------------------
117
118 The XRay Runtime Library is part of the compiler-rt project, which implements
119 the runtime components that perform the patching and unpatching of inserted
120 instrumentation points. When you use ``clang`` to link your binaries and the
121 ``-fxray-instrument`` flag, it will automatically link in the XRay runtime.
122
123 The default implementation of the XRay runtime will enable XRay instrumentation
124 before ``main`` starts, which works for applications that have a short
125 lifetime. This implementation also records all function entry and exit events
126 which may result in a lot of records in the resulting trace.
127
128 Also by default the filename of the XRay trace is ``xray-log.XXXXXX`` where the
129 ``XXXXXX`` part is randomly generated.
130
131 These options can be controlled through the ``XRAY_OPTIONS`` environment
132 variable, where we list down the options and their defaults below.
133
134 +-------------------+-----------------+---------------+------------------------+
135 | Option | Type | Default | Description |
136 +===================+=================+===============+========================+
137 | patch_premain | ``bool`` | ``true`` | Whether to patch |
138 | | | | instrumentation points |
139 | | | | before main. |
140 +-------------------+-----------------+---------------+------------------------+
141 | xray_naive_log | ``bool`` | ``true`` | Whether to install |
142 | | | | the naive log |
143 | | | | implementation. |
144 +-------------------+-----------------+---------------+------------------------+
145 | xray_logfile_base | ``const char*`` | ``xray-log.`` | Filename base for the |
146 | | | | XRay logfile. |
147 +-------------------+-----------------+---------------+------------------------+
148
149 If you choose to not use the default logging implementation that comes with the
150 XRay runtime and/or control when/how the XRay instrumentation runs, you may use
151 the XRay APIs directly for doing so. To do this, you'll need to include the
152 ``xray_interface.h`` from the compiler-rt ``xray`` directory. The important API
153 functions we list below:
154
155 - ``__xray_set_handler(void (*entry)(int32_t, XRayEntryType))``: Install your
156 own logging handler for when an event is encountered. See
157 ``xray/xray_interface.h`` for more details.
158 - ``__xray_remove_handler()``: Removes whatever the installed handler is.
159 - ``__xray_patch()``: Patch all the instrumentation points defined in the
160 binary.
161 - ``__xray_unpatch()``: Unpatch the instrumentation points defined in the
162 binary.
163
164
165 Trace Analysis Tools
166 --------------------
167
168 We currently have the beginnings of a trace analysis tool in LLVM, which can be
169 found in the ``tools/llvm-xray`` directory. The ``llvm-xray`` tool currently
170 supports the following subcommands:
171
172 - ``extract``: Extract the instrumentation map from a binary, and return it as
173 YAML.
174
175
176 Future Work
177 ===========
178
179 There are a number of ongoing efforts for expanding the toolset building around
180 the XRay instrumentation system.
181
182 Flight Data Recorder Mode
183 -------------------------
184
185 The `XRay whitepaper`_ mentions a mode for when events are kept in memory, and
186 have the traces be dumped on demand through a triggering API. This work is
187 currently ongoing.
188
189 Trace Analysis
190 --------------
191
192 There are a few more subcommands making its way to the ``llvm-xray`` tool, that
193 are currently under review:
194
195 - ``convert``: Turns an XRay trace from one format to another. Currently
196 supporting conversion from the binary XRay log to YAML.
197 - ``account``: Do function call accounting based on data in the XRay log.
198
199 We have more subcommands and modes that we're thinking of developing, in the
200 following forms:
201
202 - ``stack``: Reconstruct the function call stacks in a timeline.
203 - ``convert``: Converting from one version of the XRay log to another (higher)
204 version, and converting to other trace formats (i.e. Chrome Trace Viewer,
205 pprof, etc.).
206 - ``graph``: Generate a function call graph with relative timings and distributions.
207
208 More Platforms
209 --------------
210
211 Since XRay is only currently available in x86_64 and arm7 32-bit (no-thumb)
212 running Linux, we're looking to supporting more platforms (architectures and
213 operating systems).
214
215 .. References...
216
217 .. _`XRay whitepaper`: http://research.google.com/pubs/pub45287.html
218
272272 MIRLangRef
273273 Coroutines
274274 GlobalISel
275 XRay
275276
276277 :doc:`WritingAnLLVMPass`
277278 Information on how to write LLVM transformations and analyses.
392393
393394 :doc:`GlobalISel`
394395 This describes the prototype instruction selection replacement, GlobalISel.
396
397 :doc:`XRay`
398 High-level documentation of how to use XRay in LLVM.
395399
396400 Development Process Documentation
397401 =================================