llvm/docs/XRay.rst - third_party/llvm-project - Git at Google

 ====================
 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 customize
 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 (or contain a loop) will
 get XRay instrumentation points. You can tweak that number through the
 ``-fxray-instruction-threshold=`` flag:

 ::

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

 The loop detection can be disabled with ``-fxray-ignore-loops`` 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.

 .. 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.


 Minimizing Binary Size
 ----------------------

 XRay supports several different instrumentation points including ``function-entry``,
 ``function-exit``, ``custom``, and ``typed`` points. These can be enabled individually
 using the ``-fxray-instrumentation-bundle=`` flag. For example if you only wanted to
 instrument function entry and custom points you could specify:

 ::

   clang -fxray-instrument -fxray-instrumentation-bundle=function-entry,custom ...

 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:

 ::

   clang -fxray-instrument -fxray-function-groups=4

 A subset will be chosen arbitrarily based on a hash of the function name. To sample a
 different subset you can specify ``-fxray-selected-function-group=`` with a group number
 in the range of 0 to ``xray-function-groups`` - 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 ``__xray_patch_function()`` method.

 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
	====================
	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 customize
	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 (or contain a loop) will
	get XRay instrumentation points. You can tweak that number through the
	``-fxray-instruction-threshold=`` flag:

	::

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

	The loop detection can be disabled with ``-fxray-ignore-loops`` 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.

	.. 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.


	Minimizing Binary Size
	----------------------

	XRay supports several different instrumentation points including ``function-entry``,
	``function-exit``, ``custom``, and ``typed`` points. These can be enabled individually
	using the ``-fxray-instrumentation-bundle=`` flag. For example if you only wanted to
	instrument function entry and custom points you could specify:

	::

	clang -fxray-instrument -fxray-instrumentation-bundle=function-entry,custom ...

	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:

	::

	clang -fxray-instrument -fxray-function-groups=4

	A subset will be chosen arbitrarily based on a hash of the function name. To sample a
	different subset you can specify ``-fxray-selected-function-group=`` with a group number
	in the range of 0 to ``xray-function-groups`` - 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 ``__xray_patch_function()`` method.

	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