From 2d3803da893e76a74ba4f51d1271d9c661d54a46 Mon Sep 17 00:00:00 2001 From: Julian Jose Date: Thu, 11 Sep 2025 12:11:04 +0530 Subject: [PATCH] Update using-rocprofv3 documentation (#331) * Update using-rocprofv3 documentation * Update using-rocprofv3.rst * Update using-rocprofv3.rst * Update projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst Co-authored-by: Swati Rawat <120587655+SwRaw@users.noreply.github.com> * Update projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst Co-authored-by: Swati Rawat <120587655+SwRaw@users.noreply.github.com> --------- Co-authored-by: Gopesh Bhardwaj Co-authored-by: Swati Rawat <120587655+SwRaw@users.noreply.github.com> --- .../source/docs/how-to/using-rocprofv3.rst | 108 +++++++++++++++++- 1 file changed, 106 insertions(+), 2 deletions(-) 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 43c1ada9b3..8e00f603d9 100644 --- a/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst +++ b/projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3.rst @@ -49,13 +49,15 @@ The following table lists the commonly used ``rocprofv3`` command-line options c - | ``-i`` INPUT \| ``--input`` INPUT |br| |br| |br| |br| |br| |br| | ``-o`` OUTPUT_FILE \| ``--output-file`` OUTPUT_FILE |br| |br| |br| | ``-d`` OUTPUT_DIRECTORY \| ``--output-directory`` OUTPUT_DIRECTORY |br| |br| - | ``--output-format {csv,json,pftrace,otf2,rocpd} [{csv,json,pftrace,otf2,rocpd} ...]`` |br| |br| + | ``-f {csv,json,pftrace,otf2,rocpd} [{csv,json,pftrace,otf2,rocpd} ...]`` \| ``--output-format {csv,json,pftrace,otf2,rocpd} [{csv,json,pftrace,otf2,rocpd} ...]`` |br| |br| + | ``--output-config`` [BOOL] |br| |br| | ``--log-level {fatal,error,warning,info,trace,env}`` |br| |br| | ``-E`` EXTRA_COUNTERS \| ``--extra-counters`` EXTRA_COUNTERS - | Specifies the path to the input file. JSON and YAML formats support configuration of all command-line options for tracing and profiling whereas the text format supports only the specification of HW counters. |br| |br| | Specifies output file name. If nothing is specified, the default path is ``%hostname%/%pid%``. |br| |br| | Specifies the output path for saving the output files. If nothing is specified, the default path is ``%hostname%/%pid%``. |br| |br| | Specifies output format. Supported formats: CSV, JSON, PFTrace, OTF2 and rocpd. |br| |br| |br| + | Generates a configuration output file containing the resolved ``rocprofv3`` settings and options used for the profiling session. |br| |br| |br| | Sets the desired log level. |br| |br| |br| | Specifies the path to a YAML file consisting of extra counter definitions. @@ -185,8 +187,31 @@ To see exhaustive list of ``rocprofv3`` options: .. code-block:: bash + rocprofv3 -h rocprofv3 --help +To display version information for ``rocprofv3``: + +.. code-block:: bash + + rocprofv3 -v + rocprofv3 --version + +The version command provides comprehensive build and system information including: + +.. code-block:: shell + + $ rocprofv3 -v + version: 1.0.0 + git_revision: a1b2c3d4e5f6789012345678901234567890abcd + library_arch: x86_64-linux-gnu + system_name: Linux + system_processor: x86_64 + system_version: 6.8.0-57-generic + compiler_id: GNU + compiler_version: 11.4.0 + rocm_version: 6.2.0 + Application tracing --------------------- @@ -659,6 +684,85 @@ The preceding command generates an output file named "filename" consisting of th .. include:: /data/summary.txt :literal: +Configuration Output ++++++++++++++++++++++++ + +The ``--output-config`` option generates a comprehensive configuration output file that contains all resolved ``rocprofv3`` settings and options used during a profiling session. This feature is essential for debugging, reproducibility, and configuration validation. + +To generate a configuration output file during profiling: + +.. code-block:: bash + + rocprofv3 --output-config --hip-trace -- + +This command generates a configuration file (typically ``_config.json``) alongside the regular profiling output files. + + +The generated JSON configuration file contains detailed information about the profiling session and is structured with a ``rocprofiler-sdk-tool`` array containing comprehensive metadata and configuration details. + +The metadata section includes essential session information such as process ID (``pid``), initialization and finalization timestamps (``init_time``, ``fini_time``), the exact command executed, and detailed build specifications. The build specification contains version information, compiler details, git revision, system architecture, and kernel version, providing complete context for reproducing the environment. + +The config section is the most comprehensive part, containing all profiling options with their resolved boolean and numerical values. This includes tracing options like ``hip_runtime_api_trace``, ``hip_compiler_api_trace``, ``kernel_trace``, ``hsa_core_api_trace``, ``memory_copy_trace``, and many others. It also shows advanced configuration like PC sampling settings (``pc_sampling_method``, ``pc_sampling_interval``), filtering options (``kernel_filter_include``, ``kernel_filter_exclude``), output formatting choices (``csv_output``, ``json_output``, ``pftrace_output``), and performance tuning parameters. + +The environment section captures all environment variables active during the profiling session, including system variables such as ``SHELL``, ``COLORTERM``, ``HOSTNAME``, and ROCm-specific variables, providing complete environmental context for reproduction. + +Example configuration output structure: + +.. code-block:: json + + { + "rocprofiler-sdk-tool": [ + { + "metadata": { + "pid": 213524, + "init_time": 682678344984459, + "fini_time": 682678842290172, + "config": { + "hip_runtime_api_trace": true, + "hip_compiler_api_trace": true, + "kernel_trace": false, + "hsa_core_api_trace": false, + "memory_copy_trace": false, + "counter_collection": false, + "kernel_filter_include": ".*", + "demangle": true, + "minimum_output_bytes": 0, + "csv_output": true, + "json_output": false, + "output_path": "out", + "output_file": "1a2b3c4d5e6f/213524" + }, + "command": ["./MatrixTranspose"], + "build_spec": { + "version_major": 1, + "version_minor": 0, + "compiler_id": "GNU", + "compiler_version": "11.4.0", + "git_revision": "a1b2c3d4e5f6789012345678901234567890abcd", + "system_name": "Linux", + "system_processor": "x86_64" + }, + "environment": { + "SHELL": "/bin/bash", + "COLORTERM": "truecolor", + "HOSTNAME": "1a2b3c4d5e6f", + "ROCM_ROOT": "/opt/rocm-6.4.2", + "ROCM_VERSION": "6.4.2", + "BUILD_NUM": "12345", + "ROCPROF_OUTPUT_PATH": "out", + "ROCPROF_OUTPUT_CONFIG_FILE": "1", + "ROCPROF_OUTPUT_FORMAT": "csv", + "ROCPROF_HIP_COMPILER_API_TRACE": "1", + "ROCPROF_HIP_RUNTIME_API_TRACE": "1", + ".... Output truncated for brevity ...." + } + } + } + ] + } + +The configuration output file provides complete transparency into ``rocprofv3`` operation, documenting all settings, defaults, and environmental context required for profiling sessions. + Collecting traces using input file ++++++++++++++++++++++++++++++++++++ @@ -1698,7 +1802,7 @@ The agent index is a unique identifier for each agent in the system. It is used - **relative** == *logical_node_id* - Relative index of the agent accounting for cgroups masking. This is a monotonically increasing number, which is incremented for every folder in ``/sys/class/kfd/kfd/topology/nodes/``, whose properties file is non-empty. For example, Agent-0, Agent-1, Agent-2. - **type-relative** == *logical_node_type_id* - Relative index of the agent accounting for cgroups masking, where indexing starts at zero for each agent type. For example, CPU-0, GPU-0, GPU-1. -To set the agent index in the output files, use the ``--agent-index`` option. The default value is ``relative``. +To set the agent index in the output files, use the ``--agent-index`` or ``-A {absolute,relative,type-relative}`` option. The default value is ``relative``. The following example shows how to set the agent index on a system with multiple GPUs and CPUs: