Asight Systems quick start

1. Overview

Asight Systems is a performance analysis suite for PPU programs. It supports tracing various CPU and GPU events and displaying them on a timeline. This allows you to perform system-level analysis to identify performance bottlenecks. Asight Systems consists of two tools:

• The asys command-line tool: Collects events from a target application and generates a report. It runs on Linux. The asys tool supports collecting various event types, such as HGGC, HGTX, and OSRT, and their call stacks. It also provides flexible methods for starting and stopping collection.

• Asight Systems GUI: Displays reports and runs on Windows and macOS. The GUI provides multiple views for analysis, such as TimelineView, EventsView, and FunctionTable. It is designed to smoothly render massive datasets and is easy to use.

The workflow for the Asight Systems tool suite is as follows:

1. Use the asys command-line tool to trace a target application and generate a report.

2. Open the report in the Asight Systems GUI for analysis.

2. Get and install

If you are using the official image, the tool is preinstalled and no additional installation is required.

2.1 Get the asys CLI

1. Configure environment variables

   Navigate to the PPU_SDK directory and run the following script to configure the required environment variables:

   source envsetup.sh

2. Check the runtime environment

   After configuring the environment variables, check whether your environment meets the requirements for asys tracing and sampling by running the following command:

   asys status

   If the command indicates that the environment check passes, you can use asys to capture application trace data.

3. 

   Tip: The asys command-line tool can still function even if some configuration checks fail, but certain features might be affected:

   • If the root permission check fails, you cannot perform CPU sampling or collect its call stack.

   • If the perf_event_open syscall check fails, you cannot collect the call stack. If you are using Docker, add the --pid=host --privileged=true arguments to the docker run command to enable perf_event_open.

   • If the Ftrace check fails, you cannot use CPU sampling. To enable Ftrace when using Docker, add the -v /sys/kernel/debug:/sys/kernel/debug argument to the docker run command to mount the ftrace directory. You also need to ensure that the /sys/kernel/debug directory on the host machine is not empty.

2.2 Get the Asight Systems GUI

The Asight Systems GUI installer is released separately and supports the following operating system versions:

• Windows 10, Windows 11

• macOS 10.15 and later

Click the download link to go to the download page and select the version you need. Download the MSI installer for Windows and the DMG installer for macOS.

3. Quick start

The device that runs the PPU program is the target machine, and the device used to view the report is the host machine. The Asight Systems workflow is as follows: use the asys command-line tool on the target machine to collect a report, and then use the Asight Systems GUI on the host machine to open the report for viewing and analysis.

3.1 Collect a report with asys

On the target machine, run the asys profile command to specify trace options, launch your application, and generate a trace report. The syntax for the profile subcommand is: asys profile [option] <application> [applicationargs]

For example, to collect data from the target application test, run the following command:

asys profile -o report test

The command prints the following output and generates a file named report.asysrep in the current directory:

[Asight]:Profile executed.
[Asight]:Start trace service, this may take a while...
[Asight]:Starting target app:./test
[Asight]:Target application pid:125290, pgrp:125290
[Asight]:Collecting data...
[Asight]:All target application created processes are terminated.
[Asight]:Trace written into the output file:report.asysrep

The asys tool supports various trace targets, such as hggc, hgtx, and acblas. It also allows you to control the collection process and use an interactive collection mode.

Tip: We recommend keeping the report file size under 200 MB. To reduce the file size, you can disable CPU sampling by specifying the -s none option; see CPU and Thread Activity Tracking. You can also reduce the sampling time by controlling the collection process; see Control the Collection Process.

3.2 View reports

Reports collected by the asys command-line tool have the .asysrep file extension and can be viewed in the Asight Systems GUI. To open a file in the GUI, use one of the following methods:

• From the main menu: File > Open...

• Drag and drop the file into the main Asight Systems GUI window.

• From the context menu: Right-click a blank area in the Project Explorer and select Open...

• From the command line: asys-ui report.asysrep

Report files (.asysrep) are self-contained and can be shared with other users. However, the Asight Systems suite version used to view a report must not be older than the version used to collect it. The GUI will display a notification if you attempt to open a report collected with a newer version of the command-line tool. For more details about the Asight Systems GUI, see Use Asight Systems GUI to View Reports.

3.3 Use the GUI for remote collection

You can collect reports locally on the target machine with the asys command-line tool, or remotely from the host machine using the Asight Systems GUI over an SSH connection.

1. Remote collection requirements for the target machine

   Ensure that the target machine meets the following requirements:

   1. The PPU_SDK is installed.

   2. The SSH service is enabled.

   3. For password-based authentication, ensure that an SSH login password is set.

   To learn how to install the SSH service, see Install SSH Service.

2. Start remote collection

   From the menu bar, select Connection > Connect... to launch the Connection Dialog, as shown in the following figure:

   

   After you configure the Target application, Report name, and Connection information, click Launch to start the collection, as shown in the following figure:

   

   Once collection is complete, the report opens automatically in the GUI. For more details about remote collection, see Connection Dialog.