General Collection Commands

Applicability

Product	Supported (Yes/No)
Atlas A3 Training Series Product	Yes
Atlas A2 Training Series Product/Atlas 800I A2 Inference Product	Yes
Atlas 200/500 A2 Inference Product	Yes
Atlas Inference Series Product	Yes
Atlas Training Series Product	Yes

Function Description

The msprof command line tool provides the capabilities of collecting and parsing the AI task runtime profile data, Ascend AI Processor system data, and other required data.

The basic profiling commands of msprof are used to query the basic information about profiling, including parameter description, AI task file, data storage path, and custom environment variables.

Precautions

Ensure that an AI task can run properly in the operating environment.
Ensure that operations in Before You Start have been completed.

The Python call stack, PyTorch or MindSpore framework layer data cannot be profiled. You can use the framework APIs to profile such data.

Syntax (Ascend EP)

Log in to the environment where the CANN Toolkit package and ops operator package are installed, and run the following command in any directory:

(Recommended) Method 1: Pass the user application or execution script at the end of the msprof command.
```
msprof [options] <app> 
```
Method 2: Pass the user application or execution script using the --application option.
```
msprof [options] --application=<app> 
```

Syntax (Ascend RC)

Log in to the operating environment, go to the /var directory where the msprof tool is located, and run the following command:

(Recommended) Method 1: Pass the user application or execution script at the end of the msprof command.
```
./msprof [options] <app> 
```
Method 2: Pass the user application or execution script using the --application option.
```
./msprof [options] --application=<app> 
```

Options

**Table 1** Options
Option	Required/Optional	Description	Applicability
<app>	This option is required if you use method 1 to collect all profile data, AI task runtime profile data, or msproftx data.	(Supported only in method 1) User application whose profile data is to be collected. Enter the user application or execution script at the end of the msprof command. Configuration examples: Example 1 (passing the Python execution script and script parameters using msprof): msprof --output=/home/projects/output python3 /home/projects/MyApp/out/sample_run.py parameter1 parameter2 Example 2 (passing the main binary executable application using msprof): msprof --output=/home/projects/output main Example 3 (passing the main binary executable application using msprof): msprof --output=/home/projects/output /home/projects/MyApp/out/main Example 4 (passing the main binary executable application and application parameters using msprof): msprof --output=/home/projects/output /home/projects/MyApp/out/main parameter1 parameter2 Example 5 (passing the shell execution script and script parameters using msprof): msprof --output=/home/projects/output /home/projects/MyApp/out/sample_run.sh parameter1 parameter2 NOTE: If the user application command contains parameters that need to be enclosed in quotation marks, write the command to a shell script and run the shell script to add the user application command to the msprof command. You are advised not to configure AI tasks in directories owned by other users or directories writable by other users to avoid privilege escalation risks. You are advised not to configure high-risk operations, such as deleting files or directories, changing passwords, and running privilege escalation commands. Do not use pmupload as the application name. This option is required if you collect all profile data, AI task runtime profile data, or msproftx data. This option is optional if you collect Ascend AI Processor system data. This option is optional if you collect the host-side system data.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--application=<app>	This option is required if you use method 2 to collect all profile data, AI task runtime profile data, or msproftx data.	(Supported only in method 2) User application whose profile data is to be collected. You can use this option to pass the user application name and input parameters. Configuration examples: Use the --application option of msprof to pass the main binary executable application and application parameters. msprof --application="/home/projects/main parameter1 parameter2 ..." Use the --application option of msprof to pass the shell execution script and script parameters. Training scenario: msprof --application="/home/projects/run.sh parameter1 parameter2 ..." If abnormal symbols are found in the parameters, the parameters cannot be identified. It is recommended that you employ method 1 for user application passing. NOTE: You are advised not to configure AI tasks in directories owned by other users or directories writable by other users to avoid privilege escalation risks. You are advised not to configure high-risk operations, such as deleting files or directories, changing passwords, and running privilege escalation commands. Do not use pmupload as the application name. This option is required if you collect all profile data, AI task runtime profile data, or msproftx data. This option is optional if you collect Ascend AI Processor system data. This option is optional if you collect the host-side system data.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--output=<path>	Optional	Path for storing the collected profile data. This option is optional if you collect all profile data or AI task runtime profile data. This option is mandatory if you collect only Ascend AI Processor system data. This parameter has a higher priority than ASCEND_WORK_PATH. For details, see Environment Variables. The following special characters are not allowed in the path: "\n", "\\n", "\f", "\\f", "\r", "\\r", "\b", "\\b", "\t", "\\t", "\v", "\\v", "\u007F", "\\u007F", "\"", "\\\"", "'", "\'", "\\", "\\\\", "%", "\\%", ">", "\\>", "<", "\\<", "\|", "\\\|", "&", "\\&", "$", "\\$", ";", "\\;", "`", "\\`". When the user application or execution script is passed by adding the AI task execution command to the end of the msprof command, the profile data whose --output is not configured is flushed to the current directory by default. When the user application or execution script is passed by adding the AI task execution command to the --application option, the profile data whose --output is not configured is flushed to the directory where the AI task file is located by default.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--type=<type>	Optional	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 a .json or .csv file and a .db file (msprof_timestamp.db). db: parsed into a .db file (msprof_timestamp.db) that summarizes all profile data and is displayed by the MindStudio Insight tool. The default value is text. NOTE: For details about the exported .json, .csv, and .db files, see Profile Data File References.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--environment=<env>	Optional	Custom environment variables required in the operating environment during data collection. You are not advised using the directories owned by other users to overwrite the original environment variables, so as to avoid privilege escalation risks. The value format is --environment="${envKey}=${envValue}" or --environment="${envKey1}=${envValue1};${envKey2}=${envValue2}". Example: --environment="LD_LIBRARY_PATH=/home/xxx/Ascend/nnrt/latest;/home/xxx/Ascend/nnae/latest/lib64".	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--storage-limit=<limit-value>	Optional	Maximum size of files that can be stored in a specified disk directory. If the size of profile data files in the disk is about to use up the maximum storage space specified by this option or the total remaining disk space is about to be used up (remaining space ≤ 20 MB), the earliest files in the disk are aged and deleted. The value range is [200, 4294967295], in MB, for example, --storage-limit=200MB. By default, this option is not set. If this option is not set, the default value is 90% of the available space of the disk where the directory for storing profile data files is located.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--python-path=<python-path>	Optional	Path to the Python interpreter used for parsing. The Python version must be 3.7.5 or later. If this option is executed by a user with higher permissions, do not specify a path with low permissions.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product
--help	Optional	Help information.	Atlas 200/500 A2 Inference Product Atlas Inference Series Product Atlas Training Series Product Atlas A2 Training Series Product/Atlas 800I A2 Inference Product Atlas A3 Training Series Product

Example (Ascend EP)

Log in to the environment where the CANN Toolkit package and ops operator package are installed.
Run the following command in any directory to collect profile data:
```
msprof --output=/home/projects/output /home/projects/MyApp/out/main
```
After the msprof command is executed, the profile data result file is automatically parsed and exported. For details, see Profile Data File References.

Example (Ascend RC)

Log in to the operating environment.
Go to the /var directory where the msprof tool is located and run the following command to collect profile data:
```
./msprof --output=/home/projects/output /home/projects/MyApp/out/main
```
After the msprof command is executed, the profile data result file is automatically parsed and exported. For details, see Profile Data File References.

Parent topic: Profile Data Collecting and Parsing