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 <gopesh.bhardwaj@amd.com> Co-authored-by: Swati Rawat <120587655+SwRaw@users.noreply.github.com>
이 커밋은 다음에 포함됨:
Julian Jose
GitHub
@@ -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 -- <application_path>
|
||||
|
||||
This command generates a configuration file (typically ``<process_id>_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:
|
||||
|
||||
|
||||
새 이슈에서 참조
사용자 차단