From f0f008d494380793b52686738fd3b8caf2721cac Mon Sep 17 00:00:00 2001 From: Swati Rawat <120587655+SwRaw@users.noreply.github.com> Date: Tue, 28 Oct 2025 21:22:23 +0530 Subject: [PATCH] Update using-rocprofv3-process-attachment.rst (#1534) --- .../using-rocprofv3-process-attachment.rst | 106 +++++++++++------- 1 file changed, 66 insertions(+), 40 deletions(-) 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 index 54344351f8..8fd7567f44 100644 --- 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 @@ -4,20 +4,26 @@ :keywords: ROCprofiler-SDK, process attachment, ptrace, dynamic profiling .. _rocprofv3_process_attachment: -================================= -Using rocprofv3 Process Attachment: -================================= +========================================== +Dynamic process attachment using rocprofv3 +========================================== -``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. +For profiling long-running applications or services where restarting the application is not feasible, ``rocprofv3`` provides dynamic process attachment using the ``--attach`` option. This feature facilitates attaching the profiler to a running application without the need 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. + +Here is an example syntax for dynamic process attachment: -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). +Here are the options used in the preceding example: + +- ````: Process ID of the target application. + +- ``--hip-trace``: This optional flag enables HIP API tracing. + +- ``--output-format``: The desired output format such as rocpd, csv, or json. **Basic attachment syntax:** @@ -25,72 +31,92 @@ Where ```` is the process ID of the target application. The optional ``--hi rocprofv3 -p # or - rocprofv3 --pid + rocprofv3 --pid # or rocprofv3 --attach -**Example: Attach to a running process and profile** +Basic dynamic process attachment +--------------------------------- + +Follow these steps to attach the profiler to a running process and profile: 1. Start the target application in the background: -.. code-block:: bash - ./myapp -n 1 & + .. 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 + .. 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 + .. 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. + To detach the profiler from the target application, press "Enter" in the terminal where ``rocprofv3`` is running. You can also send SIGINT (Ctrl+C) to ``rocprofv3`` to detach from the target. -**Example: Attach to a running process and profile for a specific duration (e.g., 5 seconds):** +5. The profiling data will be saved in the format specified using ``output-format``. + +.. _duration-specific: + +Duration-specific dynamic process attachment +--------------------------------------------- + +Follow these steps to attach the profiler to a running process and profile for a specific duration such as 5 seconds: 1. Start the target application in the background: -.. code-block:: bash - ./myapp -n 1 & + .. 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 + .. 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 + .. code-block:: bash -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. + rocprofv3 --attach --attach-duration-msec 5000 --sys-trace --output-format csv - For example, if you used `--output-format csv`, the data will be saved as a CSV file. +4. The profiler will automatically detach after the specified duration (5 seconds in this case). Note that the duration is to be specified in milliseconds (ms). +5. The profiling data will be saved in the format specified using ``output-format``. For example, if you specify ``--output-format csv``, the data will be saved as a CSV file. -**Example: Attach with counter collection:** +Dynamic process attachment with counter collection +--------------------------------------------------- + +The dynamic process attachment functionality works with all tracing and profiling options available in ``rocprofv3``, providing the same comprehensive analysis capabilities as standard application launching. + +The following example attaches the profiler to a process with PID "12345", collects counters ``SQ_WAVES`` and ``GRBM_COUNT``, and saves profiling data in a CSV file: .. code-block:: bash - rocprofv3 --pid 12345 --pmc SQ_WAVES GRBM_COUNT --output-format csv + rocprofv3 --pid 12345 --pmc SQ_WAVES GRBM_COUNT --output-format csv +Key considerations +------------------- -The attachment functionality works with all tracing and profiling options available in ``rocprofv3``, providing the same comprehensive analysis capabilities as standard application launching. +Here are some important points to be noted while using dynamic process attachment: -**Important considerations for process attachment:** +- The target process must be running and actively using GPU resources for meaningful profiling data. -- 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) +- Attachment requires appropriate system permissions. It might even need elevated privileges depending on the target process. + +- To use attachment in a docker container, add the ``ptrace`` capability to the container (``SYS_PTRACE``). + +- The profiler collects data for the entire remaining lifetime of the process or until the configured collection period expires. To learn how to configure the collection period, see :ref:`duration-specific`.