From da457c9a435aa1d362093b45d466193c8ab40ecd Mon Sep 17 00:00:00 2001 From: Gopesh Bhardwaj Date: Tue, 7 Oct 2025 13:17:55 +0530 Subject: [PATCH] [Documentation] rocprofv3 attach/detach (#1108) * Fixing typo in script * updating docs * updating docs * updating docs * Update projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst Co-authored-by: Mark Meserve * Update projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst Co-authored-by: Mark Meserve --------- Co-authored-by: Mark Meserve --- .../rocprofiler-sdk/source/bin/rocprofv3.py | 2 +- .../rocprofiler-sdk/source/docs/_toc.yml.in | 3 +- .../using-rocprofv3-process-attachment.rst | 96 +++++++++++++++++++ .../source/docs/how-to/using-rocprofv3.rst | 49 +--------- .../rocprofiler-sdk/source/docs/index.rst | 1 + 5 files changed, 101 insertions(+), 50 deletions(-) create mode 100644 projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst diff --git a/projects/rocprofiler-sdk/source/bin/rocprofv3.py b/projects/rocprofiler-sdk/source/bin/rocprofv3.py index 660613a73f..44ddab2db2 100755 --- a/projects/rocprofiler-sdk/source/bin/rocprofv3.py +++ b/projects/rocprofiler-sdk/source/bin/rocprofv3.py @@ -233,7 +233,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins For attachment profiling of running processes: $ rocprofv3 --attach --hip-trace --kernel-trace - $ rocprofv3 --attach 1234 --attach-duration 10 --hsa-trace + $ rocprofv3 --attach 1234 --attach-duration-msec 10 --hsa-trace """ diff --git a/projects/rocprofiler-sdk/source/docs/_toc.yml.in b/projects/rocprofiler-sdk/source/docs/_toc.yml.in index 779079b751..1019b61f6a 100644 --- a/projects/rocprofiler-sdk/source/docs/_toc.yml.in +++ b/projects/rocprofiler-sdk/source/docs/_toc.yml.in @@ -14,8 +14,9 @@ subtrees: - file: how-to/samples title: Samples - file: how-to/using-rocprofv3 - - file: how-to/using-rocpd-output-format - file: how-to/using-rocprofv3-avail + - file: how-to/using-rocprofv3-process-attachment + - file: how-to/using-rocpd-output-format - file: how-to/using-rocprofiler-sdk-roctx - file: how-to/using-rocprofv3-with-mpi - file: how-to/using-rocprofv3-with-openmp diff --git a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst new file mode 100644 index 0000000000..54344351f8 --- /dev/null +++ b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst @@ -0,0 +1,96 @@ + +.. meta:: + :description: Guide for using rocprofv3 process attachment + :keywords: ROCprofiler-SDK, process attachment, ptrace, dynamic profiling + +.. _rocprofv3_process_attachment: +================================= + +Using rocprofv3 Process Attachment: +================================= + +``rocprofv3`` supports dynamic process attachment using the ``--attach`` option. This feature allows users to attach the profiler to an already running application without needing to restart it. The attachment is performed using the ``ptrace`` system call, which enables the profiler to monitor and collect performance data from the target process. +This capability is particularly useful for profiling long-running applications or services where restarting the application is not feasible. + +Here is an example of the syntax for attaching to a running process: +.. code-block:: bash + + rocprofv3 --attach [--hip-trace] [--output-format ] + +Where ```` is the process ID of the target application. The optional ``--hip-trace`` flag enables HIP API tracing, and the ``--output-format`` option allows specifying the desired output format (e.g., rocpd, csv, json). + +**Basic attachment syntax:** + +.. code-block:: bash + + rocprofv3 -p + # or + rocprofv3 --pid + # or + rocprofv3 --attach + +**Example: Attach to a running process and profile** + +1. Start the target application in the background: +.. code-block:: bash + + ./myapp -n 1 & + +2. Get the process ID (PID) of the running application: +.. code-block:: bash + + echo $(pgrep myapp) + OR + ps aux | grep myapp + +3. Attach ``rocprofv3`` to the running application: +.. code-block:: bash + + rocprofv3 --attach --hip-trace --output-format rocpd + +4. Detach the profiler when done: + Press `Enter` in the terminal where ``rocprofv3`` is running to detach the profiler from the target application. Sending SIGINT (`Ctrl+C`) can also be sent to ``rocprofv3`` to detach from the target. + +5. The profiling data will be saved in the specified output format. + +**Example: Attach to a running process and profile for a specific duration (e.g., 5 seconds):** + +1. Start the target application in the background: +.. code-block:: bash + + ./myapp -n 1 & + +2. Get the process ID (PID) of the running application: +.. code-block:: bash + + echo $(pgrep myapp) + OR + ps aux | grep myapp + +3. Attach ``rocprofv3`` to the running application: +.. code-block:: bash + + rocprofv3 --attach --attach-duration-msec 5000 --sys-trace --output-format csv + +4. The profiler will automatically detach after the specified duration (5 seconds in this case). +5. The profiling data will be saved in the specified output format. + + For example, if you used `--output-format csv`, the data will be saved as a CSV file. + + +**Example: Attach with counter collection:** + +.. code-block:: bash + + rocprofv3 --pid 12345 --pmc SQ_WAVES GRBM_COUNT --output-format csv + + +The attachment functionality works with all tracing and profiling options available in ``rocprofv3``, providing the same comprehensive analysis capabilities as standard application launching. + +**Important considerations for process attachment:** + +- The target process must be running and actively using GPU resources for meaningful profiling data +- Attachment requires appropriate system permissions (may need elevated privileges depending on the target process) +- Attachment in a docker container requires the ptrace capability to be added for the container (`SYS_PTRACE`) +- The profiler will collect data for the entire remaining lifetime of the process or until the configured collection period expires +- Use ``--attach-duration-msec`` to specify how long to profile the attached process (in milliseconds) diff --git a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst index 5bdec274b0..02d766c9b9 100644 --- a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst +++ b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst @@ -601,54 +601,7 @@ Process Attachment Process attachment uses the ``-p``, ``--pid``, or ``--attach`` options (all equivalent) followed by the target process ID. The profiler will instrument the target process and collect the specified tracing or counter data for the configured duration. -**Basic attachment syntax:** - -.. code-block:: bash - - rocprofv3 -p - # or - rocprofv3 --pid - # or - rocprofv3 --attach - -**Example: Attach to a running process and collect HIP traces:** - -.. code-block:: bash - - # Find the process ID of your application - ps aux | grep my_application - - # Attach to the process (replace 12345 with actual PID) - rocprofv3 --attach 12345 --hip-trace --output-format csv - -**Example: Attach with multiple tracing options:** - -.. code-block:: bash - - rocprofv3 -p 12345 --hip-trace --kernel-trace --memory-copy-trace --output-format json - -**Example: Attach with counter collection:** - -.. code-block:: bash - - rocprofv3 --pid 12345 --pmc SQ_WAVES GRBM_COUNT --output-format csv - -**Important considerations for process attachment:** - -- The target process must be running and actively using GPU resources for meaningful profiling data -- Attachment requires appropriate system permissions (may need elevated privileges depending on the target process) -- The profiler will collect data for the entire remaining lifetime of the process or until the configured collection period expires -- Use ``--attach-duration-msec`` to specify how long to profile the attached process (in milliseconds) - -**Example with duration control:** - -.. code-block:: bash - - # Attach and profile for 5 seconds - rocprofv3 --attach 12345 --attach-duration-msec 5000 --sys-trace --output-format csv - -The attachment functionality works with all tracing and profiling options available in ``rocprofv3``, providing the same comprehensive analysis capabilities as standard application launching. - +Read in detail about process attachment in :ref:`using-rocprofv3-process-attachment`. Post-processing tracing options ++++++++++++++++++++++++++++++++ diff --git a/projects/rocprofiler-sdk/source/docs/index.rst b/projects/rocprofiler-sdk/source/docs/index.rst index fccdda2891..1c4c566ad8 100644 --- a/projects/rocprofiler-sdk/source/docs/index.rst +++ b/projects/rocprofiler-sdk/source/docs/index.rst @@ -33,6 +33,7 @@ The documentation is structured as follows: * :doc:`Samples ` * :ref:`using-rocprofv3` * :ref:`using-rocprofv3-avail` + * :ref:`rocprofv3_process_attachment` * :ref:`using-rocpd-output-format` * :ref:`using-rocprofiler-sdk-roctx` * :ref:`using-rocprofv3-with-mpi`