[llvm] r331503 - [XRay][compiler-rt+docs] Introduce __xray_log_init_mode(...).
Dean Michael Berris via llvm-commits
llvm-commits at lists.llvm.org
Thu May 3 23:01:12 PDT 2018
Author: dberris
Date: Thu May 3 23:01:12 2018
New Revision: 331503
URL: http://llvm.org/viewvc/llvm-project?rev=331503&view=rev
Log:
[XRay][compiler-rt+docs] Introduce __xray_log_init_mode(...).
Summary:
This addresses http://llvm.org/PR36790.
The change Deprecates a number of functions and types in
`include/xray/xray_log_interface.h` to recommend using string-based
configuration of XRay through the __xray_log_init_mode(...) function. In
particular, this deprecates the following:
- `__xray_set_log_impl(...)` -- users should instead use the
`__xray_log_register_mode(...)` and `__xray_log_select_mode(...)` APIs.
- `__xray_log_init(...)` -- users should instead use the
`__xray_log_init_mode(...)` function, which also requires using the
`__xray_log_register_mode(...)` and `__xray_log_select_mode(...)`
functionality.
- `__xray::FDRLoggingOptions` -- in following patches, we'll be
migrating the FDR logging implementations (and tests) to use the
string-based configuration. In later stages we'll remove the
`__xray::FDRLoggingOptions` type, and ask users to migrate to using the
string-based configuration mechanism instead.
- `__xray::BasicLoggingOptions` -- same as `__xray::FDRLoggingOptions`,
we'll be removing this type later and instead rely exclusively on the
string-based configuration API.
We also update the documentation to reflect the new advice and remove
some of the deprecated notes.
Reviewers: eizan, kpw, echristo, pelikan
Reviewed By: kpw
Subscribers: llvm-commits
Differential Revision: https://reviews.llvm.org/D46173
Modified:
llvm/trunk/docs/XRay.rst
Modified: llvm/trunk/docs/XRay.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/XRay.rst?rev=331503&r1=331502&r2=331503&view=diff
==============================================================================
--- llvm/trunk/docs/XRay.rst (original)
+++ llvm/trunk/docs/XRay.rst Thu May 3 23:01:12 2018
@@ -171,20 +171,6 @@ variable, where we list down the options
| xray_logfile_base | ``const char*`` | ``xray-log.`` | Filename base for the |
| | | | XRay logfile. |
+-------------------+-----------------+---------------+------------------------+
-| xray_naive_log | ``bool`` | ``false`` | **DEPRECATED:** Use |
-| | | | xray_mode=xray-basic |
-| | | | instead. Whether to |
-| | | | install the basic log |
-| | | | the naive log |
-| | | | implementation. |
-+-------------------+-----------------+---------------+------------------------+
-| xray_fdr_log | ``bool`` | ``false`` | **DEPRECATED:** Use |
-| | | | xray_mode=xray-fdr |
-| | | | instead. Whether to |
-| | | | install the Flight |
-| | | | Data Recorder |
-| | | | (FDR) mode. |
-+-------------------+-----------------+---------------+------------------------+
| verbosity | ``int`` | ``0`` | Runtime verbosity |
| | | | level. |
+-------------------+-----------------+---------------+------------------------+
@@ -193,30 +179,45 @@ variable, where we list down the options
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_interface.h`` from the compiler-rt ``xray`` directory. The important API
+``xray_log_interface.h`` from the compiler-rt ``xray`` directory. The important API
functions we list below:
-- ``__xray_set_handler(void (*entry)(int32_t, XRayEntryType))``: Install your
- own logging handler for when an event is encountered. See
- ``xray/xray_interface.h`` for more details.
-- ``__xray_remove_handler()``: Removes whatever the installed handler is.
-- ``__xray_patch()``: Patch all the instrumentation points defined in the
- binary.
-- ``__xray_unpatch()``: Unpatch the instrumentation points defined in the
- binary.
-
-There are some requirements on the logging handler to be installed for the
-thread-safety of operations to be performed by the XRay runtime library:
-
-- The function should be thread-safe, as multiple threads may be invoking the
- function at the same time. If the logging function needs to do
- synchronisation, it must do so internally as XRay does not provide any
- synchronisation guarantees outside from the atomicity of updates to the
- pointer.
-- The pointer provided to ``__xray_set_handler(...)`` must be live even after
- calls to ``__xray_remove_handler()`` and ``__xray_unpatch()`` have succeeded.
- XRay cannot guarantee that all threads that have ever gotten a copy of the
- pointer will not invoke the function.
+- ``__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
-------------------------
@@ -226,9 +227,12 @@ fixed amount of memory's worth of events
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_fdr_log`` option to ``true`` in the
-``XRAY_OPTIONS`` environment variable (while also optionally setting the
-``xray_naive_log`` to ``false``).
+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>`_
@@ -260,34 +264,15 @@ provided below:
}
The default settings for the FDR mode implementation will create logs named
-similarly to the naive log implementation, but will have a different log
+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 however promise perpetual support for when we update the
- log versions we support going forward. Deprecation of the formats will be
+ **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.
-XRay allows for replacing the default FDR mode logging implementation using the
-following API:
-
-- ``__xray_set_log_impl(...)``: This function takes a struct of type
- ``XRayLogImpl``, which is defined in ``xray/xray_log_interface.h``, part of
- the XRay compiler-rt installation.
-- ``__xray_log_register_mode(...)``: Register a logging implementation against
- a string Mode. 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. Only implementations registered with
- ``__xray_log_register_mode(...)`` can be chosen with this function. When
- successful, has the same effects as calling ``__xray_set_log_impl(...)`` with
- the registered logging implementation.
-- ``__xray_log_init(...)``: 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.
-
Trace Analysis Tools
--------------------
@@ -301,7 +286,7 @@ supports the following subcommands:
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 naive and FDR mode) to YAML,
+ 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.
More information about the llvm-commits
mailing list