[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 <mark.meserve@amd.com> * Update projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-process-attachment.rst Co-authored-by: Mark Meserve <mark.meserve@amd.com> --------- Co-authored-by: Mark Meserve <mark.meserve@amd.com>
2025-10-07 13:17:55 +05:30
@@ -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 <PID> --hip-trace --kernel-trace
-    $ rocprofv3 --attach 1234 --attach-duration 10 --hsa-trace
+    $ rocprofv3 --attach 1234 --attach-duration-msec 10 --hsa-trace

 """

@@ -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
@@ -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 <PID> [--hip-trace] [--output-format <format>]
+
+Where ``<PID>`` 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 <PID> <tracing_options>
+    # or
+    rocprofv3 --pid <PID> <tracing_options>  
+    # or
+    rocprofv3 --attach <PID> <tracing_options>
+
+**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 <PID> --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 <PID> --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)
@@ -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 <PID> <tracing_options>
-    # or
-    rocprofv3 --pid <PID> <tracing_options>  
-    # or
-    rocprofv3 --attach <PID> <tracing_options>
-
-**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
 ++++++++++++++++++++++++++++++++
@@ -33,6 +33,7 @@ The documentation is structured as follows:
    * :doc:`Samples <how-to/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`