diff --git a/docs/conceptual/how-omnitrace-works.rst b/docs/conceptual/how-omnitrace-works.rst index d3667a6d4..7bfb13520 100644 --- a/docs/conceptual/how-omnitrace-works.rst +++ b/docs/conceptual/how-omnitrace-works.rst @@ -196,7 +196,7 @@ Callback APIs and dynamic symbol interception can be utilized with either tool. Binary instrumentation ----------------------------------- -Binary instrumentation allows you to record deterministic measurements for +Binary instrumentation lets you record deterministic measurements for every single invocation of a given function. Binary instrumentation effectively adds instructions to the target application to collect the required information. It therefore has the potential to cause performance @@ -218,8 +218,8 @@ Statistical sampling Statistical call-stack sampling periodically interrupts the application at regular intervals using operating system interrupts. -Sampling is typically less numerically accurate and specific, but allows the -target program to run nearly at full speed. +Sampling is typically less numerically accurate and specific, but the +target program runs at nearly full speed. In contrast to the data derived from binary instrumentation, the resulting data is not exact but is instead a statistical approximation. However, sampling often provides a more accurate picture of the application @@ -280,7 +280,7 @@ which contain fewer than 1024 instructions. However, recording every single invocation of the function can be extremely useful for detecting anomalies, such as profiles that show minimum or maximum values much smaller or larger -than the average or a high standard deviation. In this case, traces allow you to +than the average or a high standard deviation. In this case, the traces help you identify exactly when and where those instances deviated from the norm. Compare the level of detail in the following traces. In the top image, every instance of the ``fib`` function is instrumented, while in the bottom image, diff --git a/docs/how-to/configuring-runtime-options.rst b/docs/how-to/configuring-runtime-options.rst index d4d458249..8160cc729 100644 --- a/docs/how-to/configuring-runtime-options.rst +++ b/docs/how-to/configuring-runtime-options.rst @@ -9,7 +9,7 @@ Configuring runtime options The ``omnitrace.cfg`` file maintains a list of the `Omnitrace `_ runtime options. To create this configuration file and view the current runtime options, use the ``omnitrace-avail`` executable. -The ``omnitrace-avail`` executable +The omnitrace-avail executable ======================================== The ``omnitrace-avail`` executable provides information about the runtime settings, @@ -123,7 +123,7 @@ Here is a sample configuration for hardware counters: # using perf identifiers OMNITRACE_PAPI_EVENTS = perf::INSTRUCTIONS perf::CACHE-REFERENCES perf::CACHE-MISSES -``OMNITRACE_PAPI_EVENTS`` +OMNITRACE_PAPI_EVENTS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to collect the majority of hardware counters via PAPI, ensure the ``/proc/sys/kernel/perf_event_paranoid`` @@ -171,7 +171,7 @@ PAPI components from different namespaces: installed with the prefix ``omnitrace-`` with underscores replaced with hypens, for example ``papi_avail`` becomes ``omnitrace-papi-avail``. -``OMNITRACE_ROCM_EVENTS`` +OMNITRACE_ROCM_EVENTS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Omnitrace reads the ROCm events from the ``${ROCM_PATH}/lib/rocprofiler/metrics.xml`` @@ -202,7 +202,7 @@ The following example: OMNITRACE_ROCM_EVENTS = GPUBusy SQ_WAVES:device=0 SQ_INSTS_VALU:device=1 -``omnitrace-avail`` examples +omnitrace-avail examples ----------------------------------- The following examples demonstrate how to use ``omnitrace-avail`` to perform several common diff --git a/docs/how-to/configuring-validating-environment.rst b/docs/how-to/configuring-validating-environment.rst index c3b6a9a43..800976345 100644 --- a/docs/how-to/configuring-validating-environment.rst +++ b/docs/how-to/configuring-validating-environment.rst @@ -6,7 +6,7 @@ Configuring and validating the environment **************************************************** -After installing the `Omnitrace `_ application, some additional steps are required to set up +After installing `Omnitrace `_, additional steps are required to set up and validate the environment. .. note:: diff --git a/docs/how-to/instrumenting-rewriting-binary-application.rst b/docs/how-to/instrumenting-rewriting-binary-application.rst index 9777b7a53..c3c3083c1 100644 --- a/docs/how-to/instrumenting-rewriting-binary-application.rst +++ b/docs/how-to/instrumenting-rewriting-binary-application.rst @@ -48,7 +48,7 @@ Here is a comparison of the three modes: application is in one specific dynamic library, see :ref:`binary-rewriting-library-label` for help -The ``omnitrace-instrument`` executable +The omnitrace-instrument executable ======================================== Instrumentation is performed with the ``omnitrace-instrument`` executable. For more details, use the ``-h`` or ``--help`` option to @@ -541,7 +541,7 @@ not satisfy their regular expression. To narrow the scope of the instrumentation to a specific set of libraries and/or functions, use the ``--module-restrict`` and ``--function-restrict`` options. -These options allow you to exclusively select the union of one or more +These options let you exclusively select the union of one or more regular expressions, regardless of whether or not the functions satisfy the previously-mentioned default heuristics. Any function or module that is not within the union of these regular expressions is excluded from instrumentation. diff --git a/docs/how-to/performing-causal-profiling.rst b/docs/how-to/performing-causal-profiling.rst index 16f2ffe7d..d7b345d94 100644 --- a/docs/how-to/performing-causal-profiling.rst +++ b/docs/how-to/performing-causal-profiling.rst @@ -206,7 +206,7 @@ or To make the paranoid level persistent after a reboot, add ``kernel.perf_event_paranoid=`` (where ```` is the desired paranoid level) to the ``/etc/sysctl.conf`` file. -Speed-up prediction variability and the ``omnitrace-causal`` executable +Speed-up prediction variability and the omnitrace-causal executable ----------------------------------------------------------------------- Causal profiling typically requires running the application several times in @@ -541,7 +541,7 @@ Examples -- \ ./lulesh-omni -i 50 -s 200 -r 20 -b 5 -c 5 -p -Using ``omnitrace-causal`` with other launchers like ``mpirun`` +Using omnitrace-causal with other launchers like mpirun ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``omnitrace-causal`` executable is intended to assist with application replay diff --git a/docs/how-to/profiling-python-scripts.rst b/docs/how-to/profiling-python-scripts.rst index c1185f679..f26050c90 100644 --- a/docs/how-to/profiling-python-scripts.rst +++ b/docs/how-to/profiling-python-scripts.rst @@ -19,7 +19,7 @@ be the same size. .. note:: - When using Omnitrace for Python, the Python interpreter major and minor version (e.g. 3.7) + When using Omnitrace with Python programs, the Python interpreter major and minor version (e.g. 3.7) must match the interpreter major and minor version used when compiling the Python bindings. When building Omnitrace, the shared object file ``libpyomnitrace.----.so`` is generated diff --git a/docs/how-to/sampling-call-stack.rst b/docs/how-to/sampling-call-stack.rst index ec1e561bf..e6bc2fdc8 100644 --- a/docs/how-to/sampling-call-stack.rst +++ b/docs/how-to/sampling-call-stack.rst @@ -63,7 +63,7 @@ is not necessary. This is for a number of reasons: performing a binary rewrite of the executable and then using the instrumented executable in lieu of the original executable. ``omnitrace-sample`` is therefore much easier to use with MPI. -The ``omnitrace-sample`` executable +The omnitrace-sample executable ======================================== View the help menu of ``omnitrace-sample`` with the ``-h`` / ``--help`` option: @@ -337,7 +337,7 @@ The following snippets show how ``omnitrace-sample`` runs with various environme OMNITRACE_PROFILE=true ... -An ``omnitrace-sample`` example +An omnitrace-sample example ======================================== Here is the full output from the previous diff --git a/docs/how-to/troubleshooting-omnitrace-linux.rst b/docs/how-to/troubleshooting-omnitrace-linux.rst index 881d341c7..f158b86ef 100644 --- a/docs/how-to/troubleshooting-omnitrace-linux.rst +++ b/docs/how-to/troubleshooting-omnitrace-linux.rst @@ -3,16 +3,21 @@ :keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD **************************************************** -Troubleshooting Omnitrace on Linux +Troubleshooting Omnitrace **************************************************** +This guide explains how to resolve certain issues when installing or running Omnitrace. + +Troubleshooting Omnitrace instrumentation on RHEL +================================================== + RHEL (Red Hat Enterprise Linux) distributions of Linux automatically enable a security feature called SELinux that prevents `Omnitrace `_ from operating successfully. This issue applies to systems running the CentOS 9 operating system using -AMD ROCm Software version 6.1.x alongside an MI300 GPU. +AMD ROCm Software version 6.1.x alongside an AMD Instinct MI300 GPU. Steps to reproduce the issue -======================================== +------------------------------- The problem occurs after the following operations: @@ -43,7 +48,7 @@ Instead of successfully running the binary with call-stack sampling, Omnitrace crashes with a segmentation fault. Temporary and permanent workarounds -======================================== +------------------------------------ A workaround for this problem can be applied permanently or to the current session: diff --git a/docs/how-to/using-omnitrace-api.rst b/docs/how-to/using-omnitrace-api.rst index 59032e2b9..c6d30d539 100644 --- a/docs/how-to/using-omnitrace-api.rst +++ b/docs/how-to/using-omnitrace-api.rst @@ -11,7 +11,7 @@ The following example shows how a program can use the Omnitrace API to analyze a Omnitrace user API example program ======================================== -The Omnitrace API allows you to define custom regions to profile and trace. +You can use the Omnitrace API to define custom regions to profile and trace. The following C++ program demonstrates this technique by calling several functions from the Omnitrace API, such as ``omnitrace_user_push_region`` and ``omnitrace_user_stop_thread_trace``. diff --git a/docs/index.rst b/docs/index.rst index cf8aac692..de5cff8d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,7 +42,7 @@ The documentation is structured as follows: * :doc:`Performing causal profiling <./how-to/performing-causal-profiling>` * :doc:`Understanding the Omnitrace output <./how-to/understanding-omnitrace-output>` * :doc:`Profiling Python scripts <./how-to/profiling-python-scripts>` - * :doc:`Troubleshooting Omnitrace on Linux <./how-to/troubleshooting-omnitrace-linux>` + * :doc:`Troubleshooting Omnitrace <./how-to/troubleshooting-omnitrace-linux>` * :doc:`Using the Omnitrace API <./how-to/using-omnitrace-api>` .. grid-item-card:: Conceptual diff --git a/docs/install/install.rst b/docs/install/install.rst index 8cdc0b31a..84027cdba 100644 --- a/docs/install/install.rst +++ b/docs/install/install.rst @@ -15,8 +15,8 @@ Release links To review and install either the current Omnitrace release or earlier releases, use these links: -* `Latest Omnitrace Release `_ -* `All Omnitrace Releases `_ +* Latest Omnitrace Release: ``_ +* All Omnitrace Releases: ``_ Operating system support ======================================== @@ -31,7 +31,7 @@ Omnitrace is only supported on Linux. The following distributions are tested in * Red Hat 9.0 * Red Hat 9.1 -Other OS distributions might be supported but are not tested. +Other OS distributions might function but are not supported or tested. Identifying the operating system ----------------------------------- diff --git a/docs/reference/development-guide.rst b/docs/reference/development-guide.rst index 0fb79902d..96ad841b2 100644 --- a/docs/reference/development-guide.rst +++ b/docs/reference/development-guide.rst @@ -15,7 +15,7 @@ Executables This section lists the Omnitrace executables. -``omnitrace-avail``: `source/bin/omnitrace-avail `_ +omnitrace-avail: `source/bin/omnitrace-avail `_ ------------------------------------------------------------------------------------------------------------------------------- The ``main`` routine of ``omnitrace-avail`` has three important sections: @@ -24,7 +24,7 @@ The ``main`` routine of ``omnitrace-avail`` has three important sections: * Printing options * Printing hardware counters -``omnitrace-sample``: `source/bin/omnitrace-sample `_ +omnitrace-sample: `source/bin/omnitrace-sample `_ ------------------------------------------------------------------------------------------------------------------------------- * Requires a command-line format of ``omnitrace-sample -- `` @@ -32,7 +32,7 @@ The ``main`` routine of ``omnitrace-avail`` has three important sections: * Adds ``libomnitrace-dl.so`` to ``LD_PRELOAD`` * Is launched by using ``execvpe`` with `` `` and a modified environment -``omnitrace-casual``: `source/bin/omnitrace-causal `_ +omnitrace-casual: `source/bin/omnitrace-causal `_ ------------------------------------------------------------------------------------------------------------------------------- When there is exactly one causal profiling configuration variant (which enables debugging), @@ -45,7 +45,7 @@ the following actions take place for each variant: * the child process launches `` `` using ``execvpe``, which modifies the environment for the variant * the parent process waits for the child process to finish -``omnitrace-instrument``: `source/bin/omnitrace-instrument `_ +omnitrace-instrument: `source/bin/omnitrace-instrument `_ ------------------------------------------------------------------------------------------------------------------------------------------- * Requires a command-line format of ``omnitrace-instrument -- `` @@ -89,12 +89,12 @@ Binary library: `source/lib/binary `_ +libomnitrace: `source/lib/omnitrace `_ -------------------------------------------------------------------------------------------------------------------------------- This is the main library encapsulating all the capabilities. -``libomnitrace-dl``: `source/lib/omnitrace-dl `_ +libomnitrace-dl: `source/lib/omnitrace-dl `_ -------------------------------------------------------------------------------------------------------------------------------- This is a lightweight, front-end library for ``libomnitrace`` which serves three primary purposes: @@ -105,7 +105,7 @@ This is a lightweight, front-end library for ``libomnitrace`` which serves three * Prevents re-entry if ``libomnitrace`` calls an instrumented function internally * Coordinates communication between ``libomnitrace-user`` and ``libomnitrace`` -``libomnitrace-user``: `source/lib/omnitrace-user `_ +libomnitrace-user: `source/lib/omnitrace-user `_ -------------------------------------------------------------------------------------------------------------------------------- * Provides a set of functions and types for the users to add to their code, for example, @@ -375,7 +375,7 @@ the sampler hands the buffer off to its allocator thread and maps a new buffer w before taking the next sample. The allocator thread takes this data and either dynamically stores it in memory or writes it to a file depending on the value of ``OMNITRACE_USE_TEMPORARY_FILES``. -This schema avoids all allocations in the signal handler, allows the data to grow +This schema avoids all allocations in the signal handler, lets the data grow dynamically, avoids potentially slow I/O within the signal handler, and also enables the capability of avoiding I/O altogether. The maximum number of samplers handled by each allocator is governed by the diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 233b44a18..c840bca16 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -39,7 +39,7 @@ subtrees: - file: how-to/profiling-python-scripts.rst title: Profiling Python scripts - file: how-to/troubleshooting-omnitrace-linux.rst - title: Troubleshooting Omnitrace on Linux + title: Troubleshooting Omnitrace - file: how-to/using-omnitrace-api.rst title: Using the Omnitrace API @@ -54,9 +54,6 @@ subtrees: entries: - file: reference/development-guide.rst title: Development guide - - - caption: API - entries: - file: doxygen/html/files title: API library - file: doxygen/html/globals