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:
David Galiffi
GitHub
@@ -1,80 +1,80 @@
|
||||
.. meta::
|
||||
:description: Omnitrace documentation and reference
|
||||
:keywords: Omnitrace, ROCm, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
|
||||
:description: ROCm Systems Profiler Python profiling documentation and reference
|
||||
:keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, Python, profiling Python, profiler, tracking, visualization, tool, Instinct, accelerator, AMD
|
||||
|
||||
****************************************************
|
||||
Profiling Python scripts
|
||||
****************************************************
|
||||
|
||||
`Omnitrace <https://github.com/ROCm/omnitrace>`_ supports profiling Python code at the
|
||||
`ROCm Systems Profiler <https://github.com/ROCm/rocprofiler-systems>`_ supports profiling Python code at the
|
||||
source level and the script level.
|
||||
Python support is enabled via the ``OMNITRACE_USE_PYTHON`` and the
|
||||
``OMNITRACE_PYTHON_VERSIONS="<MAJOR>.<MINOR>`` CMake options.
|
||||
Alternatively, to build multiple Python versions, use
|
||||
``OMNITRACE_PYTHON_VERSIONS="<MAJOR>.<MINOR>;[<MAJOR>.<MINOR>]"``,
|
||||
and ``OMNITRACE_PYTHON_ROOT_DIRS="/path/to/version;[/path/to/version]"`` instead of ``OMNITRACE_PYTHON_VERSION``.
|
||||
When building multiple Python versions, the length of the ``OMNITRACE_PYTHON_VERSIONS``
|
||||
and ``OMNITRACE_PYTHON_ROOT_DIRS`` lists must
|
||||
Python support is enabled via the ``ROCPROFSYS_USE_PYTHON`` and the
|
||||
``ROCPROFSYS_PYTHON_VERSIONS="<MAJOR>.<MINOR>`` CMake options.
|
||||
Alternatively, to build multiple Python versions, use
|
||||
``ROCPROFSYS_PYTHON_VERSIONS="<MAJOR>.<MINOR>;[<MAJOR>.<MINOR>]"``,
|
||||
and ``ROCPROFSYS_PYTHON_ROOT_DIRS="/path/to/version;[/path/to/version]"`` instead of ``ROCPROFSYS_PYTHON_VERSION``.
|
||||
When building multiple Python versions, the length of the ``ROCPROFSYS_PYTHON_VERSIONS``
|
||||
and ``ROCPROFSYS_PYTHON_ROOT_DIRS`` lists must
|
||||
be the same size.
|
||||
|
||||
.. note::
|
||||
|
||||
When using Omnitrace with Python programs, the Python interpreter major and minor version (e.g. 3.7)
|
||||
When using ROCm Systems Profiler 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.<IMPL>-<VERSION>-<ARCH>-<OS>-<ABI>.so`` is generated
|
||||
where ``IMPL`` is the Python implementation, ``VERSION`` is the major and minor
|
||||
used when compiling the Python bindings. When building ROCm Systems Profiler,
|
||||
the shared object file ``libpyrocprofsys.<IMPL>-<VERSION>-<ARCH>-<OS>-<ABI>.so`` is generated
|
||||
where ``IMPL`` is the Python implementation, ``VERSION`` is the major and minor
|
||||
version, ``ARCH`` is the architecture,
|
||||
``OS`` is the operating system, and ``ABI`` is the application binary interface,
|
||||
for example, ``libpyomnitrace.cpython-38-x86_64-linux-gnu.so``.
|
||||
``OS`` is the operating system, and ``ABI`` is the application binary interface,
|
||||
for example, ``libpyrocprofsys.cpython-38-x86_64-linux-gnu.so``.
|
||||
|
||||
Getting Started
|
||||
========================================
|
||||
|
||||
The Omnitrace Python package is installed in ``lib/pythonX.Y/site-packages/omnitrace``.
|
||||
To ensure the Python interpreter can find the Omnitrace package,
|
||||
The ROCm Systems Profiler Python package is installed in ``lib/pythonX.Y/site-packages/rocprofsys``.
|
||||
To ensure the Python interpreter can find the ROCm Systems Profiler package,
|
||||
add this path to the ``PYTHONPATH`` environment variable, as in the following example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export PYTHONPATH=/opt/omnitrace/lib/python3.8/site-packages:${PYTHONPATH}
|
||||
export PYTHONPATH=/opt/rocprofiler-systems/lib/python3.8/site-packages:${PYTHONPATH}
|
||||
|
||||
Both the ``share/omnitrace/setup-env.sh`` script and the module file in
|
||||
``share/modulefiles/omnitrace`` automatically handle the prefixing of the ``PYTHONPATH``
|
||||
Both the ``share/rocprofiler-systems/setup-env.sh`` script and the module file in
|
||||
``share/modulefiles/rocprofiler-systems`` automatically handle the prefixing of the ``PYTHONPATH``
|
||||
environment variable.
|
||||
|
||||
Running Omnitrace on a Python script
|
||||
Running ROCm Systems Profiler on a Python script
|
||||
========================================
|
||||
|
||||
Omnitrace provides an ``omnitrace-python`` helper bash script which
|
||||
ROCm Systems Profiler provides an ``rocprof-sys-python`` helper bash script which
|
||||
ensures ``PYTHONPATH`` is properly set and the correct Python interpreter is used.
|
||||
This means the following commands are effectively equivalent:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
omnitrace-python --help
|
||||
rocprof-sys-python --help
|
||||
|
||||
and
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export PYTHONPATH=/opt/omnitrace/lib/python3.8/site-packages:${PYTHONPATH}
|
||||
python3.8 -m omnitrace --help
|
||||
export PYTHONPATH=/opt/rocprofiler-systems/lib/python3.8/site-packages:${PYTHONPATH}
|
||||
python3.8 -m rocprofsys --help
|
||||
|
||||
.. note::
|
||||
|
||||
``omnitrace-python`` and ``python -m omnitrace`` use the same command-line syntax
|
||||
as the other ``omnitrace`` executables (``omnitrace-python <OMNITRACE_ARGS> -- <SCRIPT> <SCRIPT_ARGS>``)
|
||||
``rocprof-sys-python`` and ``python -m rocprofsys`` use the same command-line syntax
|
||||
as the other ``rocprof-sys`` executables (``rocprof-sys-python <ROCPROFSYS_ARGS> -- <SCRIPT> <SCRIPT_ARGS>``)
|
||||
and has similar options.
|
||||
|
||||
Command line options
|
||||
-----------------------------------
|
||||
|
||||
Use ``omnitrace-python --help`` to view the available options:
|
||||
Use ``rocprof-sys-python --help`` to view the available options:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
usage: omnitrace [-h] [-v VERBOSITY] [-b] [-c FILE] [-s FILE] [-F [BOOL]] [--label [{args,file,line} [{args,file,line} ...]]] [-I FUNC [FUNC ...]] [-E FUNC [FUNC ...]] [-R FUNC [FUNC ...]] [-MI FILE [FILE ...]] [-ME FILE [FILE ...]] [-MR FILE [FILE ...]] [--trace-c [BOOL]]
|
||||
usage: rocprof-sys [-h] [-v VERBOSITY] [-b] [-c FILE] [-s FILE] [-F [BOOL]] [--label [{args,file,line} [{args,file,line} ...]]] [-I FUNC [FUNC ...]] [-E FUNC [FUNC ...]] [-R FUNC [FUNC ...]] [-MI FILE [FILE ...]] [-ME FILE [FILE ...]] [-MR FILE [FILE ...]] [--trace-c [BOOL]]
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
@@ -82,7 +82,7 @@ Use ``omnitrace-python --help`` to view the available options:
|
||||
Logging verbosity
|
||||
-b, --builtin Put 'profile' in the builtins. Use '@profile' to decorate a single function, or 'with profile:' to profile a single section of code.
|
||||
-c FILE, --config FILE
|
||||
OmniTrace configuration file
|
||||
ROCm Systems Profiler configuration file
|
||||
-s FILE, --setup FILE
|
||||
Code to execute before the code to profile
|
||||
-F [BOOL], --full-filepath [BOOL]
|
||||
@@ -103,19 +103,19 @@ Use ``omnitrace-python --help`` to view the available options:
|
||||
Select only entries from these files
|
||||
--trace-c [BOOL] Enable profiling C functions
|
||||
|
||||
usage: python3 -m omnitrace <OMNITRACE_ARGS> -- <SCRIPT> <SCRIPT_ARGS>
|
||||
usage: python3 -m rocprofsys <ROCPROFSYS_ARGS> -- <SCRIPT> <SCRIPT_ARGS>
|
||||
|
||||
.. note::
|
||||
|
||||
The ``--trace-c`` option does not incorporate Omnitrace's dynamic instrumentation support.
|
||||
The ``--trace-c`` option does not incorporate ROCm Systems Profiler's dynamic instrumentation support.
|
||||
It only enables profiling the underlying C function call within the Python interpreter.
|
||||
|
||||
Selective instrumentation
|
||||
-----------------------------------
|
||||
|
||||
Similar to the ``omnitrace-instrument`` executable, command-line options exist for restricting,
|
||||
Similar to the ``rocprof-sys-instrument`` executable, command-line options exist for restricting,
|
||||
including, and excluding certain functions and modules, for example, ``--function-exclude "^__init__$"``.
|
||||
Alternatively, add the ``@profile`` decorator to the primary function of interest
|
||||
Alternatively, add the ``@profile`` decorator to the primary function of interest
|
||||
in your program and use the ``-b`` / ``--builtin`` command-line option to narrow the scope of the
|
||||
instrumentation to this function and its children.
|
||||
|
||||
@@ -145,8 +145,8 @@ Consider the following Python code (``example.py``):
|
||||
if __name__ == "__main__":
|
||||
run(20)
|
||||
|
||||
Running ``omnitrace-python ./example.py`` with ``OMNITRACE_PROFILE=ON`` and
|
||||
``OMNITRACE_TIMEMORY_COMPONENTS=trip_count`` produces the following:
|
||||
Running ``rocprof-sys-python ./example.py`` with ``ROCPROFSYS_PROFILE=ON`` and
|
||||
``ROCPROFSYS_TIMEMORY_COMPONENTS=trip_count`` produces the following:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -187,7 +187,7 @@ If the ``inefficient`` function is decorated with ``@profile`` as follows:
|
||||
def inefficient(n):
|
||||
# ...
|
||||
|
||||
And then run using the command ``omnitrace-python -b -- ./example.py``, Omnitrace produces this output:
|
||||
And then run using the command ``rocprof-sys-python -b -- ./example.py``, ROCm Systems Profiler produces this output:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -199,37 +199,37 @@ And then run using the command ``omnitrace-python -b -- ./example.py``, Omnitrac
|
||||
| |0>>> inefficient | 1 | 0 | trip_count | 1 |
|
||||
|-----------------------------------------------------------|
|
||||
|
||||
Omnitrace Python source instrumentation
|
||||
ROCm Systems Profiler Python source instrumentation
|
||||
========================================
|
||||
|
||||
Starting with the unmodified ``example.py`` script above, import the ``omnitrace`` module:
|
||||
Starting with the unmodified ``example.py`` script above, import the ``rocprofsys`` module:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import sys
|
||||
import omnitrace # import omnitrace
|
||||
import rocprofsys # import rocprofsys
|
||||
|
||||
def fib(n):
|
||||
# ... etc. ...
|
||||
|
||||
Next, add ``@omnitrace.profile()`` to the ``run`` function:
|
||||
Next, add ``@rocprofsys.profile()`` to the ``run`` function:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@omnitrace.profile()
|
||||
@rocprofsys.profile()
|
||||
def run(n):
|
||||
# ...
|
||||
|
||||
Alternatively, use ``omnitrace.profile()`` as a context-manager around ``run(20)``:
|
||||
Alternatively, use ``rocprofsys.profile()`` as a context-manager around ``run(20)``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
if __name__ == "__main__":
|
||||
with omnitrace.profile():
|
||||
with rocprofsys.profile():
|
||||
run(20)
|
||||
|
||||
The results for both of the source-level instrumentation modes are identical to the
|
||||
original ``omnitrace-python ./example.py`` results:
|
||||
The results for both of the source-level instrumentation modes are identical to the
|
||||
original ``rocprofsys-python ./example.py`` results:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -264,14 +264,14 @@ original ``omnitrace-python ./example.py`` results:
|
||||
|
||||
.. note::
|
||||
|
||||
When ``omnitrace-python`` is used without built-ins, the profiling results can be cluttered by the
|
||||
When ``rocprof-sys-python`` is used without built-ins, the profiling results can be cluttered by the
|
||||
numerous functions called when more complex modules are imported, such as ``import numpy``.
|
||||
|
||||
Omnitrace Python source instrumentation configuration
|
||||
ROCm Systems Profiler Python source instrumentation configuration
|
||||
-------------------------------------------------------------
|
||||
|
||||
Within the Python source code, the profiler can be configured by directly
|
||||
modifying the ``omnitrace.profiler.config`` data fields.
|
||||
Within the Python source code, the profiler can be configured by directly
|
||||
modifying the ``rocprof-sys.profiler.config`` data fields.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -295,8 +295,8 @@ modifying the ``omnitrace.profiler.config`` data fields.
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
from omnitrace.profiler import config
|
||||
from omnitrace import profile
|
||||
from rocprofsys.profiler import config
|
||||
from rocprofsys import profile
|
||||
|
||||
config.include_args = True
|
||||
config.include_filename = False
|
||||
|
||||
Reference in New Issue
Block a user