General Profiling Command

Function

The msprof command line tool provides the capabilities of collecting and parsing the profile data during AI task running, AI processor system data, and other required data.

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

Command Format

For Ascend EP, log in to the operating environment and run the 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> 

For Ascend RC, log in to the operating environment, go to the /var directory where msprof is installed, and run the 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> 

In the following examples, the recommended method is used to avoid redundant information.

app Parameters

The user application and related parameters can be passed. The following are examples.

• Configuration example of method 1:
  • Pass the binary executable program and program parameters to msprof.

    msprof --output=/home/projects/output /home/projects/main parameter1 parameter2

  • Pass the execution script and script parameters to msprof.

    msprof --output=/home/projects/output /home/projects/run.sh parameter1 parameter2

• Configuration example of method 2:
  • Use the --application option of msprof to pass the binary executable application and application parameters.

    msprof --application="/home/projects/main parameter1 parameter2 ..."

  • Use the --application option of msprof to pass the 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. If method 1 is used and 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 perform 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 parameter is required if you collect all profile data, profile data during AI task running, or msproftx data. This parameter is optional if you collect AI processor system data. This parameter is optional if you collect the host-side system data.

options Parameters

• --output=<path>: (optional) indicates the path for storing the collected profile data.
  • This parameter is optional if you collect all profile data or profile data during AI task running.
  • This parameter is required if you collect only AI processor system data.

  This parameter has a higher priority than ASCEND_WORK_PATH. For details, see the Environment Variables.

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

  When you pass the user application or execution script by adding the AI task execution command to the end of the msprof command, the profile data is flushed to the current directory by default.

  When you pass the user application or execution script is passed by adding the AI task execution command to --application, the profile data is flushed to the directory where the AI task file is stored by default.

• --type=<type>: (optional) indicates the format of the profile data parsing result file. 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: The profile data is parsed into a .json or .csv file and a .db file (msprof_timestamp.db) The default value is text.
  • 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.
• --environment=<env>: (optional) indicates the custom environment variables required in the operating environment during profiling.

  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}".

• --storage-limit=<limit-value>: (optional) indicates the 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 parameter is not set and the available disk space is less than 20 MB before profiling, data is not flushed to the disk.

• --help: (optional) displays the help information.

Example

msprof --output=/home/projects/output /home/projects/MyApp/out/main

./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.