Asight Systems quick start

1. Overview

Asight Systems is a performance analysis suite for PPU applications. It traces various CPU and GPU events and displays their timelines. You can use it to perform system-level analysis and identify performance bottlenecks. Asight Systems consists of two tools:

• The asys command-line tool: Runs on Linux to collect events from a target application and generate a report. The asys tool supports collecting various event types, such as HGGC, HGTX, OSRT, and their call stack information. It also provides flexible ways to start and stop data collection.

• The Asight Systems GUI: Runs on Windows and macOS to visualize reports. The Asight Systems GUI provides multiple views, such as TimelineView, EventsView, and FunctionTable, to display reports. It can smoothly render large amounts of data and is easy to use.

The workflow for using 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. Use the Asight Systems GUI to open and analyze the report.

2. Get and install

If you use an official image, the tool is pre-installed and no setup 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 running environment

   Once the environment variables are configured, run the following command to check if your environment meets the requirements for asys tracing and sampling:

   asys status

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

   

   Tip: Some configuration check failures do not prevent the asys command-line tool from running, but may affect certain features:

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

   • If the perf_event_open syscall check fails, you cannot collect call stack data. If you use Docker, you can add the --pid=host--privileged=true argument to the docker run command to enable perf_event_open.

   • If the Ftrace check fails, you cannot perform CPU sampling. To enable Ftrace in a Docker environment, add the -v/sys/kernel/debug:/sys/kernel/debug argument to the docker run command to mount the Ftrace directory. You must also 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 tool is released as a separate software package and supports the following operating systems:

• Windows 10, Windows 11

• macOS 10.15 and later

Click the download link to open the download page. Select the version you need. Download the MSI package for Windows or the DMG package for macOS.

3. Quick start

The device that runs the PPU application is the target machine, and the device used to view the report is the host machine. First, use the asys command-line tool on the target machine to generate a report. Then, use the Asight Systems GUI on the host machine to open, view, and analyze it.

3.1 Capture a report with asys

Run the asys profile command on the target machine to specify trace options, run your application, and generate a trace report.

The syntax for the profile subcommand is: asys profile [option] <application> [applicationargs]

For example, to collect data for a target application named test, run the following command:

asys profile -o report test

This command produces the following output and generates a file named report.asysrep in the current directory.

[Asight]:Profile executed.
[Asight]:Starttraceservice,thismaytakeawhile...
[Asight]:Startingtargetapp:./test
[Asight]:Targetapplicationpid:125290,pgrp:125290
[Asight]:Collectingdata...
[Asight]:Alltargetapplicationcreatedprocessesareterminated.
[Asight]:Tracewrittenintotheoutputfile:report.asysrep

The asys tool supports various trace options, such as hggc, hgtx, and acblas. You can also control the collection process and use an interactive collection mode. For more information, see Capture a report with the asys command-line tool.

Tip: We recommend that you keep the size of the report file under 200 MB. To reduce the report size, you can specify the -s none option for asys to disable CPU sampling. For more information, see CPU and thread activity tracing. You can also control the sampling process to reduce the sampling time. For more information, see Control the collection process.

3.2 View a report

Reports generated by the asys command-line tool have an .asysrep extension and can be opened in the Asight Systems GUI. You can open files in the GUI in the following ways:

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

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

• From the shortcut menu: Right-click an empty area in the Project Explorer and select Open...

• Open from the command line of the GUI tool by running asys-ui report.asysrep.

The report file (.asysrep) is self-contained and can be shared with others. However, the version of the Asight Systems suite used to view a report must not be older than the version that generated it. The GUI tool displays a warning when you open a report that was generated by a newer version of the command-line tool.

For more information about the Asight Systems GUI, see View a report with the Asight Systems GUI.