reference, declarationdefinition
definition → references, declarations, derived classes, virtual overrides
reference to multiple definitions → definitions
unreferenced
    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
====================
XRay Instrumentation
====================

:Version: 1 as of 2016-11-08

.. contents::
   :local:


Introduction
============

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.

More high level information about XRay can be found in the `XRay whitepaper`_.

This document describes how to use XRay as implemented in LLVM.

XRay in LLVM
============

XRay consists of three main parts:

- Compiler-inserted instrumentation points.
- A runtime library for enabling/disabling tracing at runtime.
- A suite of tools for analysing the traces.

  **NOTE:** 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.

The compiler-inserted instrumentation points come in the form of nop-sleds in
the final generated binary, and an ELF section named ``xray_instr_map`` which
contains entries pointing to these instrumentation points. The runtime library
relies on being able to access the entries of the ``xray_instr_map``, and
overwrite the instrumentation points at runtime.

Using XRay
==========

You can use XRay in a couple of ways:

- Instrumenting your C/C++/Objective-C/Objective-C++ application.
- Generating LLVM IR with the correct function attributes.

The rest of this section covers these main ways and later on how to customise
what XRay does in an XRay-instrumented binary.

Instrumenting your C/C++/Objective-C Application
------------------------------------------------

The easiest way of getting XRay instrumentation for your application is by
enabling the ``-fxray-instrument`` flag in your clang invocation.

For example:

::

  clang -fxray-instrument ...

By default, functions that have at least 200 instructions will get XRay
instrumentation points. You can tweak that number through the
``-fxray-instruction-threshold=`` flag:

::

  clang -fxray-instrument -fxray-instruction-threshold=1 ...

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.

.. code-block:: c++

    [[clang::xray_always_instrument]] void always_instrumented();

    [[clang::xray_never_instrument]] void never_instrumented();

    void alt_always_instrumented() __attribute__((xray_always_instrument));

    void alt_never_instrumented() __attribute__((xray_never_instrument));

When linking a binary, you can either manually link in the `XRay Runtime
Library`_ or use ``clang`` to link it in automatically with the
``-fxray-instrument`` flag. Alternatively, you can statically link-in the XRay
runtime library from compiler-rt -- those archive files will take the name of
`libclang_rt.xray-{arch}` where `{arch}` is the mnemonic supported by clang
(x86_64, arm7, etc.).

LLVM Function Attribute
-----------------------

If you're using LLVM IR directly, you can add the ``function-instrument``
string attribute to your functions, to get the similar effect that the
C/C++/Objective-C source-level attributes would get:

.. code-block:: llvm

    define i32 @always_instrument() uwtable "function-instrument"="xray-always" {
      ; ...
    }

    define i32 @never_instrument() uwtable "function-instrument"="xray-never" {
      ; ...
    }

You can also set the ``xray-instruction-threshold`` attribute and provide a
numeric string value for how many instructions should be in the function before
it gets instrumented.

.. code-block:: llvm

    define i32 @maybe_instrument() uwtable "xray-instruction-threshold"="2" {
      ; ...
    }

Special Case File
-----------------

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:

.. code-block:: bash

    # Comments are supported
    [always]
    fun:always_instrument
    fun:log_arg1=arg1 # Log the first argument for the function

    [never]
    fun:never_instrument

These files can be provided through the ``-fxray-attr-list=`` flag to clang.
You may have multiple files loaded through multiple instances of the flag.

XRay Runtime Library
--------------------

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 ``clang`` to link your binaries and the
``-fxray-instrument`` flag, it will automatically link in the XRay runtime.

The default implementation of the XRay runtime will enable XRay instrumentation
before ``main`` 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.

Also by default the filename of the XRay trace is ``xray-log.XXXXXX`` where the
``XXXXXX`` part is randomly generated.

These options can be controlled through the ``XRAY_OPTIONS`` environment
variable, where we list down the options and their defaults below.

+-------------------+-----------------+---------------+------------------------+
| Option            | Type            | Default       | Description            |
+===================+=================+===============+========================+
| patch_premain     | ``bool``        | ``false``     | Whether to patch       |
|                   |                 |               | instrumentation points |
|                   |                 |               | before main.           |
+-------------------+-----------------+---------------+------------------------+
| xray_mode         | ``const char*`` | ``""``        | Default mode to        |
|                   |                 |               | install and initialize |
|                   |                 |               | before ``main``.       |
+-------------------+-----------------+---------------+------------------------+
| xray_logfile_base | ``const char*`` | ``xray-log.`` | Filename base for the  |
|                   |                 |               | XRay logfile.          |
+-------------------+-----------------+---------------+------------------------+
| verbosity         | ``int``         | ``0``         | Runtime verbosity      |
|                   |                 |               | level.                 |
+-------------------+-----------------+---------------+------------------------+


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
``xray_log_interface.h`` from the compiler-rt ``xray`` directory. The important API
functions we list below:

- ``__xray_log_register_mode(...)``: Register a logging implementation against
  a string Mode identifier. The implementation is an instance of
  ``XRayLogImpl`` defined in ``xray/xray_log_interface.h``.
- ``__xray_log_select_mode(...)``: Select the mode to install, associated with
  a string Mode identifier. Only implementations registered with
  ``__xray_log_register_mode(...)`` can be chosen with this function.
- ``__xray_log_init_mode(...)``: This function allows for initializing and
  re-initializing an installed logging implementation. See
  ``xray/xray_log_interface.h`` for details, part of the XRay compiler-rt
  installation.

Once a logging implementation has been initialized, it can be "stopped" by
finalizing the implementation through the ``__xray_log_finalize()`` function.
The finalization routine is the opposite of the initialization. When finalized,
an implementation's data can be cleared out through the
``__xray_log_flushLog()`` function. For implementations that support in-memory
processing, these should register an iterator function to provide access to the
data via the ``__xray_log_set_buffer_iterator(...)`` which allows code calling
the ``__xray_log_process_buffers(...)`` function to deal with the data in
memory.

All of this is better explained in the ``xray/xray_log_interface.h`` header.

Basic Mode
----------

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 ``xray_mode=xray-basic`` in the ``XRAY_OPTIONS``
environment variable. Combined with ``patch_premain=true`` this can allow for
tracing applications from start to end.

Like all the other modes installed through ``__xray_log_select_mode(...)``, the
implementation can be configured through the ``__xray_log_init_mode(...)``
function, providing the mode string and the flag options. Basic-mode specific
defaults can be provided in the ``XRAY_BASIC_OPTIONS`` environment variable.

Flight Data Recorder Mode
-------------------------

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 ``xray_mode`` variable to ``xray-fdr`` in
the ``XRAY_OPTIONS`` environment variable. Additional options to the FDR mode
implementation can be provided in the ``XRAY_FDR_OPTIONS`` environment
variable. Programmatic configuration can be done by calling
``__xray_log_init_mode("xray-fdr", <configuration string>)`` once it has been
selected/installed.

When the buffers are flushed to disk, the result is a binary trace format
described by `XRay FDR format <XRayFDRFormat.html>`_

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:

.. code-block:: c++

  // Patch the sleds, if we haven't yet.
  auto patch_status = __xray_patch();

  // Maybe handle the patch_status errors.

  // When we want to flush the log, we need to finalize it first, to give
  // threads a chance to return buffers to the queue.
  auto finalize_status = __xray_log_finalize();
  if (finalize_status != XRAY_LOG_FINALIZED) {
    // maybe retry, or bail out.
  }

  // At this point, we are sure that the log is finalized, so we may try
  // flushing the log.
  auto flush_status = __xray_log_flushLog();
  if (flush_status != XRAY_LOG_FLUSHED) {
    // maybe retry, or bail out.
  }

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.

  **NOTE:** 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.

Trace Analysis Tools
--------------------

We currently have the beginnings of a trace analysis tool in LLVM, which can be
found in the ``tools/llvm-xray`` directory. The ``llvm-xray`` tool currently
supports the following subcommands:

- ``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. We can
  convert from binary XRay traces (both basic and FDR mode) to YAML,
  `flame-graph <https://github.com/brendangregg/FlameGraph>`_ friendly text
  formats, as well as `Chrome Trace Viewer (catapult)
  <https://github.com/catapult-project/catapult>` formats.
- ``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 function
  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`` 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 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.

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