docs/XRay.rst

   1 ====================
   2 XRay Instrumentation
   3 ====================
   4
   5 :Version: 1 as of 2016-11-08
   6
   7 .. contents::
   8    :local:
   9
  10
  11 Introduction
  12 ============
  13
  14 XRay is a function call tracing system which combines compiler-inserted
  15 instrumentation points and a runtime library that can dynamically enable and
  16 disable the instrumentation.
  17
  18 More high level information about XRay can be found in the `XRay whitepaper`_.
  19
  20 This document describes how to use XRay as implemented in LLVM.
  21
  22 XRay in LLVM
  23 ============
  24
  25 XRay consists of three main parts:
  26
  27 - Compiler-inserted instrumentation points.
  28 - A runtime library for enabling/disabling tracing at runtime.
  29 - A suite of tools for analysing the traces.
  30
  31   **NOTE:** As of February 27, 2017 , XRay is only available for the following
  32   architectures running Linux: x86_64, arm7 (no thumb), aarch64, powerpc64le,
  33   mips, mipsel, mips64, mips64el.
  34
  35 The compiler-inserted instrumentation points come in the form of nop-sleds in
  36 the final generated binary, and an ELF section named ``xray_instr_map`` which
  37 contains entries pointing to these instrumentation points. The runtime library
  38 relies on being able to access the entries of the ``xray_instr_map``, and
  39 overwrite the instrumentation points at runtime.
  40
  41 Using XRay
  42 ==========
  43
  44 You can use XRay in a couple of ways:
  45
  46 - Instrumenting your C/C++/Objective-C/Objective-C++ application.
  47 - Generating LLVM IR with the correct function attributes.
  48
  49 The rest of this section covers these main ways and later on how to customise
  50 what XRay does in an XRay-instrumented binary.
  51
  52 Instrumenting your C/C++/Objective-C Application
  53 ------------------------------------------------
  54
  55 The easiest way of getting XRay instrumentation for your application is by
  56 enabling the ``-fxray-instrument`` flag in your clang invocation.
  57
  58 For example:
  59
  60 ::
  61
  62   clang -fxray-instrument ..
  63
  64 By default, functions that have at least 200 instructions will get XRay
  65 instrumentation points. You can tweak that number through the
  66 ``-fxray-instruction-threshold=`` flag:
  67
  68 ::
  69
  70   clang -fxray-instrument -fxray-instruction-threshold=1 ..
  71
  72 You can also specifically instrument functions in your binary to either always
  73 or never be instrumented using source-level attributes. You can do it using the
  74 GCC-style attributes or C++11-style attributes.
  75
  76 .. code-block:: c++
  77
  78     [[clang::xray_always_intrument]] void always_instrumented();
  79
  80     [[clang::xray_never_instrument]] void never_instrumented();
  81
  82     void alt_always_instrumented() __attribute__((xray_always_intrument));
  83
  84     void alt_never_instrumented() __attribute__((xray_never_instrument));
  85
  86 When linking a binary, you can either manually link in the `XRay Runtime
  87 Library`_ or use ``clang`` to link it in automatically with the
  88 ``-fxray-instrument`` flag. Alternatively, you can statically link-in the XRay
  89 runtime library from compiler-rt -- those archive files will take the name of
  90 `libclang_rt.xray-{arch}` where `{arch}` is the mnemonic supported by clang
  91 (x86_64, arm7, etc.).
  92
  93 LLVM Function Attribute
  94 -----------------------
  95
  96 If you're using LLVM IR directly, you can add the ``function-instrument``
  97 string attribute to your functions, to get the similar effect that the
  98 C/C++/Objective-C source-level attributes would get:
  99
 100 .. code-block:: llvm
 101
 102     define i32 @always_instrument() uwtable "function-instrument"="xray-always" {
 103       ; ...
 104     }
 105
 106     define i32 @never_instrument() uwtable "function-instrument"="xray-never" {
 107       ; ...
 108     }
 109
 110 You can also set the ``xray-instruction-threshold`` attribute and provide a
 111 numeric string value for how many instructions should be in the function before
 112 it gets instrumented.
 113
 114 .. code-block:: llvm
 115
 116     define i32 @maybe_instrument() uwtable "xray-instruction-threshold"="2" {
 117       ; ...
 118     }
 119
 120 XRay Runtime Library
 121 --------------------
 122
 123 The XRay Runtime Library is part of the compiler-rt project, which implements
 124 the runtime components that perform the patching and unpatching of inserted
 125 instrumentation points. When you use ``clang`` to link your binaries and the
 126 ``-fxray-instrument`` flag, it will automatically link in the XRay runtime.
 127
 128 The default implementation of the XRay runtime will enable XRay instrumentation
 129 before ``main`` starts, which works for applications that have a short
 130 lifetime. This implementation also records all function entry and exit events
 131 which may result in a lot of records in the resulting trace.
 132
 133 Also by default the filename of the XRay trace is ``xray-log.XXXXXX`` where the
 134 ``XXXXXX`` part is randomly generated.
 135
 136 These options can be controlled through the ``XRAY_OPTIONS`` environment
 137 variable, where we list down the options and their defaults below.
 138
 139 +-------------------+-----------------+---------------+------------------------+
 140 | Option            | Type            | Default       | Description            |
 141 +===================+=================+===============+========================+
 142 | patch_premain     | ``bool``        | ``false``     | Whether to patch       |
 143 |                   |                 |               | instrumentation points |
 144 |                   |                 |               | before main.           |
 145 +-------------------+-----------------+---------------+------------------------+
 146 | xray_naive_log    | ``bool``        | ``true``      | Whether to install     |
 147 |                   |                 |               | the naive log          |
 148 |                   |                 |               | implementation.        |
 149 +-------------------+-----------------+---------------+------------------------+
 150 | xray_logfile_base | ``const char*`` | ``xray-log.`` | Filename base for the  |
 151 |                   |                 |               | XRay logfile.          |
 152 +-------------------+-----------------+---------------+------------------------+
 153 | xray_fdr_log      | ``bool``        | ``false``     | Wheter to install the  |
 154 |                   |                 |               | Flight Data Recorder   |
 155 |                   |                 |               | (FDR) mode.            |
 156 +-------------------+-----------------+---------------+------------------------+
 157
 158
 159 If you choose to not use the default logging implementation that comes with the
 160 XRay runtime and/or control when/how the XRay instrumentation runs, you may use
 161 the XRay APIs directly for doing so. To do this, you'll need to include the
 162 ``xray_interface.h`` from the compiler-rt ``xray`` directory. The important API
 163 functions we list below:
 164
 165 - ``__xray_set_handler(void (*entry)(int32_t, XRayEntryType))``: Install your
 166   own logging handler for when an event is encountered. See
 167   ``xray/xray_interface.h`` for more details.
 168 - ``__xray_remove_handler()``: Removes whatever the installed handler is.
 169 - ``__xray_patch()``: Patch all the instrumentation points defined in the
 170   binary.
 171 - ``__xray_unpatch()``: Unpatch the instrumentation points defined in the
 172   binary.
 173
 174 There are some requirements on the logging handler to be installed for the
 175 thread-safety of operations to be performed by the XRay runtime library:
 176
 177 - The function should be thread-safe, as multiple threads may be invoking the
 178   function at the same time. If the logging function needs to do
 179   synchronisation, it must do so internally as XRay does not provide any
 180   synchronisation guarantees outside from the atomicity of updates to the
 181   pointer.
 182 - The pointer provided to ``__xray_set_handler(...)`` must be live even after
 183   calls to ``__xray_remove_handler()`` and ``__xray_unpatch()`` have succeeded.
 184   XRay cannot guarantee that all threads that have ever gotten a copy of the
 185   pointer will not invoke the function.
 186
 187 Flight Data Recorder Mode
 188 -------------------------
 189
 190 XRay supports a logging mode which allows the application to only capture a
 191 fixed amount of memory's worth of events. Flight Data Recorder (FDR) mode works
 192 very much like a plane's "black box" which keeps recording data to memory in a
 193 fixed-size circular queue of buffers, and have the data available
 194 programmatically until the buffers are finalized and flushed. To use FDR mode
 195 on your application, you may set the ``xray_fdr_log`` option to ``true`` in the
 196 ``XRAY_OPTIONS`` environment variable (while also optionally setting the
 197 ``xray_naive_log`` to ``false``).
 198
 199 When FDR mode is on, it will keep writing and recycling memory buffers until
 200 the logging implementation is finalized -- at which point it can be flushed and
 201 re-initialised later. To do this programmatically, we follow the workflow
 202 provided below:
 203
 204 .. code-block:: c++
 205
 206   // Patch the sleds, if we haven't yet.
 207   auto patch_status = __xray_patch();
 208
 209   // Maybe handle the patch_status errors.
 210
 211   // When we want to flush the log, we need to finalize it first, to give
 212   // threads a chance to return buffers to the queue.
 213   auto finalize_status = __xray_log_finalize();
 214   if (finalize_status != XRAY_LOG_FINALIZED) {
 215     // maybe retry, or bail out.
 216   }
 217
 218   // At this point, we are sure that the log is finalized, so we may try
 219   // flushing the log.
 220   auto flush_status = __xray_log_flushLog();
 221   if (flush_status != XRAY_LOG_FLUSHED) {
 222     // maybe retry, or bail out.
 223   }
 224
 225 The default settings for the FDR mode implementation will create logs named
 226 similarly to the naive log implementation, but will have a different log
 227 format. All the trace analysis tools (and the trace reading library) will
 228 support all versions of the FDR mode format as we add more functionality and
 229 record types in the future.
 230
 231   **NOTE:** We do not however promise perpetual support for when we update the
 232   log versions we support going forward. Deprecation of the formats will be
 233   announced and discussed on the developers mailing list.
 234
 235 XRay allows for replacing the default FDR mode logging implementation using the
 236 following API:
 237
 238 - ``__xray_set_log_impl(...)``: This function takes a struct of type
 239   ``XRayLogImpl``, which is defined in ``xray/xray_log_interface.h``, part of
 240   the XRay compiler-rt installation.
 241 - ``__xray_log_init(...)``: This function allows for initializing and
 242   re-initializing an installed logging implementation. See
 243   ``xray/xray_log_interface.h`` for details, part of the XRay compiler-rt
 244   installation.
 245
 246 Trace Analysis Tools
 247 --------------------
 248
 249 We currently have the beginnings of a trace analysis tool in LLVM, which can be
 250 found in the ``tools/llvm-xray`` directory. The ``llvm-xray`` tool currently
 251 supports the following subcommands:
 252
 253 - ``extract``: Extract the instrumentation map from a binary, and return it as
 254   YAML.
 255 - ``account``: Performs basic function call accounting statistics with various
 256   options for sorting, and output formats (supports CSV, YAML, and
 257   console-friendly TEXT).
 258 - ``convert``: Converts an XRay log file from one format to another. Currently
 259   only converts to YAML.
 260 - ``graph``: Generates a DOT graph of the function call relationships between
 261   functions found in an XRay trace.
 262
 263 These subcommands use various library components found as part of the XRay
 264 libraries, distributed with the LLVM distribution. These are:
 265
 266 - ``llvm/XRay/Trace.h`` : A trace reading library for conveniently loading
 267   an XRay trace of supported forms, into a convenient in-memory representation.
 268   All the analysis tools that deal with traces use this implementation.
 269 - ``llvm/XRay/Graph.h`` : A semi-generic graph type used by the graph
 270   subcommand to conveniently represent a function call graph with statistics
 271   associated with edges and vertices.
 272 - ``llvm/XRay/InstrumentationMap.h``: A convenient tool for analyzing the
 273   instrumentation map in XRay-instrumented object files and binaries. The
 274   ``extract`` subcommand uses this particular library.
 275
 276 Future Work
 277 ===========
 278
 279 There are a number of ongoing efforts for expanding the toolset building around
 280 the XRay instrumentation system.
 281
 282 Trace Analysis
 283 --------------
 284
 285 We have more subcommands and modes that we're thinking of developing, in the
 286 following forms:
 287
 288 - ``stack``: Reconstruct the function call stacks in a timeline.
 289
 290 More Platforms
 291 --------------
 292
 293 We're looking forward to contributions to port XRay to more architectures and
 294 operating systems.
 295
 296 .. References...
 297
 298 .. _`XRay whitepaper`: http://research.google.com/pubs/pub45287.html
 299