Applicable Products

Product	Supported
Ascend 950PR/Ascend 950DT	√
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	√
Atlas inference products	√
Atlas training products	√

Function

This function is used to parse and export profile data.

Precautions

Complete the operations in Before You Start first.
The profiling has completed.
Direct parsing on the device is not supported for the products below. You must copy the generated PROF_XXX directory to an environment where the Toolkit package is installed.
- Ascend RC scenarios of Atlas 200I/500 A2 inference products

Command Format

msprof --export=on --output=<dir> [--type=<type>] [--reports=<reports_sample_config.json>] [--model-id=<number>] [--iteration-id=<number>] [--summary-format=<csv/json>] [--clear=on]

Command-line Options

**Table 1** Options
Option	Description	Required/Optional
--export	Profile data parsing and export, The value can be on or off (default). on: This option is enabled. off: This option is disabled. To export data of a specific model (model ID) or iteration (iteration ID), run the msprof --export command again to configure the --model-id and --iteration-id options after the msprof profiling command is executed. The PROF_XXX files that are not parsed are automatically parsed and then exported. Example: msprof --export=on --output=/home/profiler_data/PROF_XXX	Required
--output	Directory for storing the profile data file. The value must be the PROF_XXX directory or the parent directory of the PROF_XXX directory, for example, /home/profiler_data/PROF_XXX. The path cannot contain the following characters: "\n", "\\n", "\f", "\\f", "\r", "\\r", "\b", "\\b", "\t", "\\t", "\v", "\\v", "\u007F", "\\u007F", "\"", "\\\"", "'", "\'", "\\", "\\\\", "%", "\\%", ">", "\\>", "<", "\\<", "\|", "\\\|", "&", "\\&", "$", "\\$", ";", "\\;", "`", "\\`".	Required
--type	Format of the profile data parsing result file. That is, you can choose the format of the result file generated after the profile data collected by the msprof command is automatically parsed. The available formats include: text: parsed into timeline and summary files in .json and .csv formats, as well as .db files (msprof_Timestamp.db). For details, see Profile Data File References. CANN 7.0.0 and later versions support the use of this parameter to parse profile data. db: The profile data is parsed into a .db file (msprof_timestamp.db) that summarizes all profile data and is displayed by the MindStudio Insight tool. The amount of information in this data format is different from that parsed by the text parameter. You are advised to use the text parameter. When the type is set to db, only the --output option of the msprof --export command is supported. Other options of the command are invalid. The default value is text.	Optional
--reports	After the custom reports_sample_config.json configuration file is passed, the corresponding profile data files are exported based on the range specified in the configuration file. For details, see Example (--reports). Ascend 950PR/Ascend 950DT does not support this option.	Optional
--model-id	Model ID. The value must be a positive integer. This parameter must be used together with --iteration-id to export the profile data of a specified computing iteration in the model. If neither --iteration-id nor --model-id is specified, all profile data is exported by default. For Atlas A2 training products/Atlas A2 inference products, --model-id can be set to 4294967295, which specifies the step mode. That is, the value of --iteration-id specifies parsing by step. Only profile data of the MindSpore framework (version 2.3 or later) can be parsed. For Atlas A3 training products/Atlas A3 inference products, --model-id can be set to 4294967295, which specifies the step mode. That is, the value of --iteration-id specifies parsing by step. Only profile data of the MindSpore framework (version 2.3 or later) can be parsed. If --model-id is set to other values, this option specifies the iteration ID for graph-based statistics collection. (The iteration ID is incremented by 1 each time a graph is executed. When a script is compiled into multiple graphs, the iteration ID is different from the step ID at the script layer.)	Optional
--iteration-id	Iteration ID. The value must be a positive integer. This parameter must be used together with --model-id to export the profile data of a specified computing iteration in the model. If neither --iteration-id nor --model-id is specified, all profile data is exported by default. For the Atlas A2 training products/Atlas A2 inference products, if --model-id is set to 4294967295, this option specifies the iteration ID whose data is collected by step. The iteration ID increases by 1 each time a step is executed. Only profile data of the MindSpore framework (version 2.3 or later) can be parsed. For the Atlas A3 training products/Atlas A3 inference products, if --model-id is set to 4294967295, this option specifies the iteration ID whose data is collected by step. The iteration ID increases by 1 each time a step is executed. Only profile data of the MindSpore framework (version 2.3 or later) can be parsed. If --model-id is set to other values, this option specifies the iteration ID for graph-based statistics collection. (The iteration ID is incremented by 1 each time a graph is executed. When a script is compiled into multiple graphs, the iteration ID is different from the step ID at the script layer.)	Optional
--summary-format	Export format of a summary data file. The values are as follows: json: The parsed summary data file is in JSON format. csv (default): The parsed summary data file is in CSV format. Supported only when --type=text.	Optional
--python-path	Path to the Python interpreter used for parsing. The Python version must be 3.7.5 or later. If the default Python version in the environment is earlier than 3.7.5, use this parameter to set the Python version to 3.7.5 or later. If this option is executed by a user with higher permissions, do not specify a path with low permissions.	Optional
--clear	Data simplification mode. After this option is enabled, the sqlite directory in PROF_XXX/device_{id} is deleted after profile data is exported, so as to save storage space. The value can be on or off (default).	Optional

By default, all profile data is exported.
In single-operator scenarios or scenarios where only AI processor system data is collected (that means the --application option is not specified in the msprof profiling command), --iteration-id and --model-id are not supported.

Example

Specify the /home/profiler_data/PROF_XXX directory as the profile data directory and run the following command:

msprof --export=on --output=/home/profiler_data/PROF_XXX

Example (--reports)

Specify the /home/profiler_data/PROF_XXX directory as the profile data directory, pass the custom reports_sample_config.json configuration file, and run the following command:

msprof --export=on --output=/home/profiler_data/PROF_XXX --reports=${INSTALL_DIR}/tools/profiler/profiler_tool/analysis/msconfig/reports_sample_config.json

Replace ${INSTALL_DIR} with the CANN component directory. For example, if the installation is performed by the root user, the default file storage path is /usr/local/Ascend/cann.

The path cannot contain the following characters: "\n", "\\n", "\f", "\\f", "\r", "\\r", "\b", "\\b", "\t", "\\t", "\v", "\\v", "\u007F", "\\u007F", "\"", "\\\"", "'", "\'", "\\", "\\\\", "%", "\\%", ">", "\\>", "<", "\\<", "|", "\\|", "&", "\\&", "$", "\\$", ";", "\\;", "`", "\\`".

--reports specifies the reports_sample_config.json file. Use this option with the --export option and configure --type=text. It controls only the timeline data in the .json file. The summary data in the .csv file will always be fully exported.
Soft links are not supported. The maximum file size is 64 MB, and the maximum length of the file path (including the file name) is 1,024 characters.

By default, the reports_sample_config.json file is stored in the ${INSTALL_DIR}/tools/profiler/profiler_tool/analysis/msconfig/ directory. The content of the file is as follows:

The reports_sample_config.json file can be created in any directory, on which you have read and write permissions.

{
	"json_process": {
		"ascend": true,
		"acc_pmu": true,
		"cann": true,
		"ddr": true,
		"stars_chip_trans": true,
		"hbm": true,
		"communication": true,
		"hccs": true,
		"os_runtime_api": true,
		"network_usage": true,
		"disk_usage": true,
		"memory_usage": true,
		"cpu_usage": true,
		"msproftx": true,
		"npu_mem": true,
		"overlap_analyse": true,
		"pcie": true,
		"sio": true,
		"stars_soc": true,
		"step_trace": true,
		"freq": true,
		"llc": true,
		"nic": true,
		"roce": true,
		"qos": true,
		"device_tx": true
	}
}

The preceding parameters are switches for profiling specific data. You can set them to true or false (or delete unwanted fields). The following timeline data layers in the msprof_*.json file can be profiled: CANN, Ascend Hardware, AI Core Freq, On-Chip Memory, Communication, Overlap Analysis, and NPU_MEM.

The prerequisite for exporting these data is that the original profile data already contains these fields, which means these data fields are profiled.
Ensure that the reports_sample_config.json file is in the correct format. Otherwise, the following situations may occur:
- If the file contains errors like misspellings, the --reports option fails, exporting all profile data instead.
- The system stops the export and reports an error if the --reports option cannot access the configuration file due to insufficient permissions or a non-existent file.

Output Description

After the msprof --export command is executed, the mindstudio_profiler_output directory is generated in the PROF_XXX directory.

The structure of the generated profile data directory is as follows:

Single-process profiling

└── PROF_XXX
      ├── device_0
      │    └── data
      ├── device_1
      │    └── data
      ├── host
      │    └── data
      ├── msprof_*.db
      └── mindstudio_profiler_output
            ├── msprof_{timestamp}.json
            ├── step_trace_{timestamp}.json
            ├── xx_*.csv
             ...
            └── README.txt

Multi-process profiling

└── PROF_XXX1
      ├── device_0
      │    └── data
      ├── host
      │    └── data
      ├── msprof_*.db
      └── mindstudio_profiler_output
            ├── msprof_{timestamp}.json
            ├── step_trace_{timestamp}.json
            ├── xx_*.csv
             ...
            └── README.txt
└── PROF_XXX2
      ├── device_1
      │    └── data
      ├── host
      │    └── data
      ├── msprof_*.db
      └── mindstudio_profiler_output
            ├── msprof_{timestamp}.json
            ├── step_trace_{timestamp}.json
            ├── xx_*.csv
             ...
            └── README.txt

msprof_*.db is a .db file that summarizes all profile data. The .json files in the mindstudio_profiler_output directory are timeline information files, which collect the running durations of operators and tasks and display the collected data in color blocks. The .csv files are summary information files, which summarize the running durations in tables. For details about profile data, see Profile Data File References.
In multi-device setups, if single-process collection is started, only one PROF_XXX directory is generated. If multi-process collection is started, multiple PROF_XXX directories are generated. In addition, the device directory is generated in the PROF_XXX directory. The number of device directories generated in each PROF_XXX directory is related to the actual user operations and does not affect profile data analysis.
The files in the mindstudio_profiler_output directory are generated based on the actual profile data. If the necessary profile data file is absent, the corresponding timeline and summary data will be unavailable.
For a msprof process that is forcibly interrupted, the tool saves the collected raw profile data. You can run msprof --parse to reparse the data and then run msprof --export.

Profile Data Parsing and Export