Update branding to ROCm Systems Profiler in documentation (#2)
* Update branding in docs
* Rename image used in documentation
* Update names of code samples.
In the code snippets, the "-" is not valid. ex., rocprof-sys_ --> rocprofsys_
* Update ASCII art
* update Doxyfile strip_from_path
* Add a "Formerly known as" message.
* Fixed typo in product name
ROCm Systems Profiler, not ROCm Profiler System
* Add "Omnitrace" back to the metadata keywords
* Update "install via package manager" section
* Update paths to user API files
* Rename configuration and environment settings
* Update Doxyfiles
Update publisher name & ID to "AMD".
Update bundle ID to "rocprofiler-systems"
* Update docs/what-is-rocprof-sys.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/conceptual/data-collection-modes.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/tutorials/video-tutorials.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/conceptual/rocprof-sys-feature-set.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/configuring-runtime-options.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/configuring-validating-environment.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/general-tips-using-rocprof-sys.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/reference/rocprof-sys-glossary.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/reference/development-guide.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/instrumenting-rewriting-binary-application.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/install/quick-start.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Note that videos were recorded using the "Omnitrace" name.
* Rebase and update some file paths
* Update paths to doc images
* Update Omnitrace references in code snippets
* Rename examples still using the "omni" prefix.
* Update docs/how-to/performing-causal-profiling.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/profiling-python-scripts.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/sampling-call-stack.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/how-to/understanding-rocprof-sys-output.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
* Update docs/install/install.rst
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
---------
Co-authored-by: Peter Park <peter.park@amd.com>
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
[ROCm/rocprofiler-systems commit: 032d39f15c]
This commit is contained in:
authored and 
GitHub committed
1 parent
181a782835
commit
d13617cf91
59 files changed
+1340
-10282
No files matched your search
@@ -1,17 +1,17 @@
|
||||
.. meta::
|
||||
:description: Omnitrace documentation and reference
|
||||
:keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
|
||||
:description: ROCm Systems Profiler data collection modes documentation
|
||||
:keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, data collection, tracking, visualization, tool, Instinct, accelerator, AMD
|
||||
|
||||
**********************
|
||||
Data collection modes
|
||||
**********************
|
||||
|
||||
Omnitrace supports several modes of recording trace and profiling data for your application.
|
||||
ROCm Systems Profiler supports several modes of recording trace and profiling data for your application.
|
||||
|
||||
.. note::
|
||||
|
||||
For an explanation of the terms used in this topic, see
|
||||
the :doc:`Omnitrace glossary <../reference/omnitrace-glossary>`.
|
||||
|
||||
For an explanation of the terms used in this topic, see
|
||||
the :doc:`ROCm Systems Profiler glossary <../reference/rocprof-sys-glossary>`.
|
||||
|
||||
+-----------------------------+---------------------------------------------------------+
|
||||
| Mode | Description |
|
||||
@@ -23,61 +23,62 @@ Omnitrace supports several modes of recording trace and profiling data for your
|
||||
| | and records various metrics for the given call stack |
|
||||
+-----------------------------+---------------------------------------------------------+
|
||||
| Callback APIs | Parallelism frameworks such as ROCm, OpenMP, and Kokkos |
|
||||
| | make callbacks into Omnitrace to provide information |
|
||||
| | about the work the API is performing |
|
||||
| | make callbacks into ROCm Systems Profiler to provide |
|
||||
| | information about the work the API is performing |
|
||||
+-----------------------------+---------------------------------------------------------+
|
||||
| Dynamic Symbol Interception | Wrap function symbols defined in a position independent |
|
||||
| | dynamic library/executable, like ``pthread_mutex_lock`` |
|
||||
| | in ``libpthread.so`` or ``MPI_Init`` in the MPI library |
|
||||
+-----------------------------+---------------------------------------------------------+
|
||||
| User API | User-defined regions and controls for Omnitrace |
|
||||
| User API | User-defined regions and controls for ROCm Systems |
|
||||
| | Profiler |
|
||||
+-----------------------------+---------------------------------------------------------+
|
||||
|
||||
The two most generic and important modes are binary instrumentation and statistical sampling.
|
||||
The two most generic and important modes are binary instrumentation and statistical sampling.
|
||||
It is important to understand their advantages and disadvantages.
|
||||
Binary instrumentation and statistical sampling can be performed with the ``omnitrace-instrument``
|
||||
Binary instrumentation and statistical sampling can be performed with the ``rocprof-sys-instrument``
|
||||
executable. For statistical sampling, it's highly recommended to use the
|
||||
``omnitrace-sample`` executable instead if binary instrumentation isn't required or needed.
|
||||
``rocprof-sys-sample`` executable instead if binary instrumentation isn't required or needed.
|
||||
Callback APIs and dynamic symbol interception can be utilized with either tool.
|
||||
|
||||
Binary instrumentation
|
||||
-----------------------------------
|
||||
|
||||
Binary instrumentation lets you 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
|
||||
changes which might, in some cases, lead to inaccurate results. The effect depends on
|
||||
the information being collected and which features are activated in Omnitrace.
|
||||
Binary instrumentation effectively adds instructions to the target application to
|
||||
collect the required information. It therefore has the potential to cause performance
|
||||
changes which might, in some cases, lead to inaccurate results. The effect depends on
|
||||
the information being collected and which features are activated in ROCm Systems Profiler.
|
||||
For example, collecting only the wall-clock timing data
|
||||
has less of an effect than collecting the wall-clock timing, CPU-clock timing,
|
||||
memory usage, cache-misses, and number of instructions that were run. Similarly,
|
||||
collecting a flat profile has less overhead than a hierarchical profile
|
||||
and collecting a trace OR a profile has less overhead than collecting a
|
||||
has less of an effect than collecting the wall-clock timing, CPU-clock timing,
|
||||
memory usage, cache-misses, and number of instructions that were run. Similarly,
|
||||
collecting a flat profile has less overhead than a hierarchical profile
|
||||
and collecting a trace OR a profile has less overhead than collecting a
|
||||
trace AND a profile.
|
||||
|
||||
In Omnitrace, the primary heuristic for controlling the overhead with binary
|
||||
instrumentation is the minimum number of instructions for selecting functions
|
||||
In ROCm Systems Profiler, the primary heuristic for controlling the overhead with binary
|
||||
instrumentation is the minimum number of instructions for selecting functions
|
||||
for instrumentation.
|
||||
|
||||
Statistical sampling
|
||||
-----------------------------------
|
||||
|
||||
Statistical call-stack sampling periodically interrupts the application at
|
||||
Statistical call-stack sampling periodically interrupts the application at
|
||||
regular intervals using operating system interrupts.
|
||||
Sampling is typically less numerically accurate and specific, but the
|
||||
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
|
||||
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
|
||||
However, sampling often provides a more accurate picture of the application
|
||||
execution because it is less intrusive to the target application and has fewer
|
||||
side effects on memory caches or instruction decoding pipelines. Furthermore,
|
||||
side effects on memory caches or instruction decoding pipelines. Furthermore,
|
||||
because sampling does not affect the execution speed as much, is it
|
||||
relatively immune to over-evaluating the cost of small, frequently called
|
||||
relatively immune to over-evaluating the cost of small, frequently called
|
||||
functions or "tight" loops.
|
||||
|
||||
In Omnitrace, the overhead for statistical sampling depends on the
|
||||
sampling rate and whether the samples are taken with respect to the CPU time
|
||||
In ROCm Systems Profiler, the overhead for statistical sampling depends on the
|
||||
sampling rate and whether the samples are taken with respect to the CPU time
|
||||
and/or real time.
|
||||
|
||||
Binary instrumentation vs. statistical sampling example
|
||||
@@ -112,24 +113,24 @@ Consider the following code:
|
||||
return 0;
|
||||
}
|
||||
|
||||
Binary instrumentation of the ``fib`` function will record **every single invocation**
|
||||
Binary instrumentation of the ``fib`` function will record **every single invocation**
|
||||
of the function. For a very small function
|
||||
such as ``fib``, this results in **significant** overhead since this simple function
|
||||
such as ``fib``, this results in **significant** overhead since this simple function
|
||||
takes about 20 instructions, whereas the entry and
|
||||
exit snippets are ~1024 instructions. Therefore, you generally want to avoid
|
||||
exit snippets are ~1024 instructions. Therefore, you generally want to avoid
|
||||
instrumenting functions where the instrumented function has significantly fewer
|
||||
instructions than entry and exit instrumentation. (Note that many of the
|
||||
instructions than entry and exit instrumentation. (Note that many of the
|
||||
instructions in entry and exit functions are either logging functions or
|
||||
depend on the runtime settings and thus might never run). However,
|
||||
depend on the runtime settings and thus might never run). However,
|
||||
due to the number of potential instructions in the entry and exit snippets,
|
||||
the default behavior of ``omnitrace-instrument`` is to only instrument functions
|
||||
the default behavior of ``rocprof-sys-instrument`` is to only instrument functions
|
||||
which contain at least 1024 instructions.
|
||||
|
||||
However, recording every single invocation of the function can be extremely
|
||||
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, the traces help you
|
||||
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,
|
||||
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,
|
||||
the ``fib`` call-stack is derived via sampling.
|
||||
|
||||
|
||||
+21
-26
@@ -1,14 +1,14 @@
|
||||
.. meta::
|
||||
:description: Omnitrace documentation and reference
|
||||
:keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
|
||||
:description: ROCm Systems Profiler feature set documentation and reference
|
||||
:keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, profiler, feature set, use cases, tracking, visualization, tool, Instinct, accelerator, AMD
|
||||
|
||||
***************************************
|
||||
The Omnitrace feature set and use cases
|
||||
The ROCm Systems Profiler feature set and use cases
|
||||
***************************************
|
||||
|
||||
`Omnitrace <https://github.com/ROCm/omnitrace>`_ is designed to be highly extensible.
|
||||
Internally, it leverages the `Timemory performance analysis toolkit <https://github.com/NERSC/timemory>`_
|
||||
to manage extensions, resources, data, and other items. It supports the following features,
|
||||
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ is designed to be highly extensible.
|
||||
Internally, it leverages the `Timemory performance analysis toolkit <https://github.com/NERSC/timemory>`_
|
||||
to manage extensions, resources, data, and other items. It supports the following features,
|
||||
modes, metrics, and APIs.
|
||||
|
||||
Data collection modes
|
||||
@@ -22,11 +22,6 @@ Data collection modes
|
||||
* Statistical sampling: Periodic software interrupts per-thread
|
||||
* Process-level sampling: A background thread records process-, system- and device-level metrics while the application runs
|
||||
* Causal profiling: Quantifies the potential impact of optimizations in parallel code
|
||||
|
||||
.. note::
|
||||
|
||||
Critical trace support was removed in Omnitrace v1.11.0.
|
||||
It was replaced by the causal profiling feature.
|
||||
|
||||
Data analysis
|
||||
========================================
|
||||
@@ -98,40 +93,40 @@ Third-party API support
|
||||
* NVTX
|
||||
* ROCTX
|
||||
|
||||
Omnitrace use cases
|
||||
ROCm Systems Profiler use cases
|
||||
========================================
|
||||
|
||||
When analyzing the performance of an application, do NOT
|
||||
When analyzing the performance of an application, do NOT
|
||||
assume you know where the performance bottlenecks are
|
||||
and why they are happening. Omnitrace is a tool for analyzing the entire
|
||||
and why they are happening. ROCm Systems Profiler is a tool for analyzing the entire
|
||||
application and its performance. It is
|
||||
ideal for characterizing where optimization would have the greatest impact
|
||||
ideal for characterizing where optimization would have the greatest impact
|
||||
on an end-to-end run of the application and for
|
||||
viewing what else is happening on the system during a performance bottleneck.
|
||||
|
||||
When GPUs are involved, there is a tendency to assume that
|
||||
When GPUs are involved, there is a tendency to assume that
|
||||
the quickest path to performance improvement is minimizing
|
||||
the runtime of the GPU kernels. This is a highly flawed assumption.
|
||||
the runtime of the GPU kernels. This is a highly flawed assumption.
|
||||
If you optimize the runtime of a kernel from one millisecond
|
||||
to 1 microsecond (1000x speed-up) but the original application never
|
||||
to 1 microsecond (1000x speed-up) but the original application never
|
||||
spent time waiting for kernels to complete,
|
||||
there would be no statistically significant reduction in the end-to-end
|
||||
there would be no statistically significant reduction in the end-to-end
|
||||
runtime of your application. In other words, it does not matter
|
||||
how fast or slow the code on GPU is if the application has a
|
||||
how fast or slow the code on GPU is if the application has a
|
||||
bottleneck on waiting on the GPU.
|
||||
|
||||
Use Omnitrace to obtain a high-level view of the entire application. Use it
|
||||
Use ROCm Systems Profiler to obtain a high-level view of the entire application. Use it
|
||||
to determine where the performance bottlenecks are and
|
||||
obtain clues to why these bottlenecks are happening. Rather than worrying about kernel
|
||||
performance, start your investigation with Omnitrace, which characterizes the
|
||||
performance, start your investigation with ROCm Systems Profiler, which characterizes the
|
||||
broad picture.
|
||||
|
||||
.. note::
|
||||
|
||||
For insight into the execution of individual kernels on the GPU,
|
||||
use `Omniperf <https://github.com/rocm/omniperf>`_.
|
||||
For insight into the execution of individual kernels on the GPU,
|
||||
use `ROCm Compute Profiler <https://github.com/rocm/rocprofiler-compute>`_.
|
||||
|
||||
In terms of CPU analysis, Omnitrace does not target any specific vendor.
|
||||
In terms of CPU analysis, ROCm Systems Profiler does not target any specific vendor.
|
||||
It works just as well on AMD and non-AMD CPUs.
|
||||
With regard to the GPU, Omnitrace is currently restricted to HIP and HSA APIs
|
||||
With regard to the GPU, ROCm Systems Profiler is currently restricted to HIP and HSA APIs
|
||||
and kernels running on AMD GPUs.
|
||||
Reference in new issue
Block a user