4. Opening reports

You can open report files on your local machine, or from a remote server over SSH.

You can open a .pvti file in the System Analyser by double-clicking it in your OS’s file browser. (Not supported on Linux.)

4.1. Opening recent reports

If you’ve opened a report before, the Home screen displays a list of recently opened reports in the Recent panel.

  • Click on a recent report to open it again. That report will automatically move to the top of the Recent list.

  • If you want to remove a report from the Recent list, click on the trash icon that appears to the left of a report when you hover your mouse over it.

  • If you attempt to open a report file from the Recent list that has been moved or deleted since it was last opened, an error dialog appears indicating that the file can’t be found. You can either replace the file, in which case the corresponding link in the Recent panel will work again, or you can click on the Remove from recent files button in the error dialog to remove that file from the Recent list.

  • To copy a report directory’s location in the PopVision custom format, click the Copy icon to the right of the report’s entry. See Sharing reports below for details.

The Recent reports list can contain up to 64 previous file selections.

The News from Graphcore section on the right of the landing page shows recent news articles from Graphcore. Clicking on the links opens the articles in your default web browser. You can collapse the news section by clicking the small arrow next to it.

If you’ve previously opened two reports to compare them, they will be listed on the Recent comparisons tab, which allows you to open them again for comparison.

4.2. Sharing report URLs

The System Analyser can create custom URLs that make it simpler to share report locations with others, even for remote reports. Each report in the Recent reports list has a Copy icon on its right-hand end.

  • Click the Copy icon to copy a custom-formatted URL to the clipboard.

The URL follows the standard format, and is of the form:

system-analyser://<server>/<path-to-report-directory>

The recipient of such a file will be able to double-click it to launch the System Analyser and have it attempt to open the file at that location. If no username is supplied in the URL, and the server requires it, you’ll be prompted to enter one, in addition to any other login credentials you’ll need to supply to access that server location.

To get custom URLs to work on Linux, you’ll need a .desktop file, and to have configured the default program for system-analyser links by running

xdg-mime default your_desktop_file.desktop x-scheme-handler/system-analyser

4.3. Opening the Demo Report

If you don’t have any generated reports, you can open and browse the demo report that’s included with the System Analyser. It’s a small report, but contains all of the features that are supported in the current application.

  • Click on the Open demo report link on the Home screen to open the demo report.

The Recent list can contain up to 64 previous file selections.

4.4. Local reports

You can open report files stored on your local machine.

To open a report stored locally on your machine:

  • Click on the Open a report link from the Open panel on the Home screen. You’ll be presented with a file selection dialog, and the local tab at the top will be selected by default. You’ll see listings of the directories and files on your local machine.

  • The System Analyser application can open .pvti files and .json files that support the Chromium trace format. When the System Analyser identifies a directory in which any .pvti files are found, those files are listed on the right-hand side.

  • When typing a path into the box at the top of the dialog, a drop-down list shows the directories within the current directory. You can use the up and down arrow keys to navigate this list, and choose the next path element by pressing the Enter key.

  • You can sort these files by name or modified date, in ascending or descending order, by clicking on the appropriate column header. Your sorting preference is saved.

  • You can toggle the Open dialog between modal and full-screen view by clicking on the icon to the left of the window’s title.

  • After navigating to the desired directory, you can select a file by clicking on it. Multiple files can be selected at once.

  • Once you’ve selected the file(s) you wish to open, click on the Open button to load the report data from the file(s).

While the report file(s) load into the application, you’ll see a Loading progress bar, then the main reports view is displayed.

While you have a report open, you can add other reports to it byclicking the Open button in the top left-hand corner of the application.

4.5. Remote reports

If you are using an IPU system on a remote server, for example on a cloud service, any reports generated will be saved to that server. In this case you can open them remotely by specifying the server address, and connecting to the machine over SSH. The reports are analysed and the output is streamed back to the System Analyser application on your local machine, allowing you to view the reports.

When the System Analyser opens report files on a remote machine, it uploads a small binary app containing an analysis engine to the remote server. This analysis engine pre-processes the report data and sends it back over SSH to the System Analyser application running on your local machine. If you’re running other performance-critical processes on that remote machine, you should be aware of any effects this process may have on the capacity of the remote machine’s hardware to run any other tasks. As server performance varies a great deal, the only way to know how much processor speed the app takes is to try a small sample, and monitor the CPU usage.

To open a report stored on a remote machine:

  • Click on the Open a report link in the Open panel on the Home screen. You’ll be presented with a file selection dialog, and the local tab at the top will be selected by default.

  • Click on the remote tab at the top, and you’ll see a login dialog that allows you to connect to a remote server. Enter your username, and the address of the remote machine. You can enter the port or use the default. Click on the Connect button to connect to the remote machine.

  • If you have configured your SSH key in the Preferences dialog, then the connection should use the key for authentication on the remote server.

  • If your SSH key requires a passphrase, then you will have to configure a SSH agent in order to use the key.

  • If you haven’t set a path to your private SSH key in the Preferences dialog nor have you configured an SSH agent, then you will be prompted for a password to log into the remote machine.

  • Once logged in, you’ll see listings of the directories and files on the remote machine. You can sort these files by name, modified date or size, in ascending or descending order, by clicking on the appropriate column header.

  • The System Analyser application can open .pvti files and .json files that support the Chromium trace format. Multiple files can be opened together from this dialog by clicking to select all the files you want to open. You’ll notice that when the System Analyser identifies a directory in which any .pvti files are found, those files are listed on the right-hand side.

  • Once you’ve selected the file(s) you wish to open, click on the Open button to load the report data from the file(s).

While the report file(s) load into the application, you’ll see a Loading progress bar, then the main reports view is displayed.

4.5.1. Configure the SSH agent

The System Analyser does not currently support encrypted SSH private keys which means keys that are protected by a passphrase. However it does support SSH agents. If your key is passphrase protected you will need to make sure to add it to your SSH agent before the System Analyser can use it, by using the ssh-add command-line tool and ensure that the SSH agent mode is set correctly in the Preferences dialog.

To configure the SSH agent, from a terminal run:

# Start the SSH agent in the background.
eval "$(ssh-agent -s)"

# Add your SSH private key to the SSH agent
ssh-add -K ~/.ssh/id_rsa

Then edit your preferences to remove the entry in SSH private key path. Make sure that SSH agent mode is set to Automatically obtain ssh-agent socket path from environment.

4.5.2. Connecting via SSH and ProxyJump

If you are using an machine via a ProxyJump you can still use PopVision if you set up SSH forwarding. If your ProxyJump machine is at proxy.jump.com and your remote machine is at remote.machine.com, you can use port forwarding to connect:

ssh -N -f -L localhost:2222:remote.machine.com:22 proxy.jump.com

Then in PopVision click “Open a Report…” on the main screen, select “Remote”, and set “Hostname” to localhost and “Port” to 2222. You should now be able to open reports on the remote machine over the ProxyJump link.

Port forwarding is shut down again once that SSH session ends.

4.6. Connection errors

A number of errors can occur when connecting to a remote server. This section lists the most common and gives some troubleshooting steps.

Error: getaddrinfo ENOTFOUND server.example.com

This error occurs when the specified server could not be found (DNS lookup failed). Check that you have typed the server’s name correctly. If a VPN connection is required, check that it is connected and working correctly.

Error: Password authentication failed

If the SSH agent and SSH key authentication fail then password authentication is attempted. If you normally use a public key to connect to the server, check that you have correctly specified the key as described in SSH preferences Otherwise, check that password authentication is enabled on the server and that you have typed your password correctly.

Error: Cannot create directory '.cache/popvision_system_analyser' because a file already exists there.

The System Analyser will attempt to create a number of directories on the remote server if they do not already exist. If a file already exists with the same name then attempting to create the directory will fail. Check what the file is and either delete or rename it to allow the directory to be created.

Error: Could not create directory '.cache': Permission denied

The application will attempt to create a number of directories on the remote server if they do not already exist. This error indicates that you did not have permission to create one of these directories. This usually indicates a problem with how your home directory is set up on the server: either you do not have a home directory and don’t have permission to create one, or you have not been given adequate permissions on your own home directory. Contact the server administrator to ask for a home directory to be created or for its permissions to be corrected.

Error: Could not write to '.cache/popvision_system_analyser/backend_... on the remote. This could be caused by a full filesystem

This error usually occurs because there was not enough disk space on the server to upload the required binary file to your home directory (around 20 MB is required). You may be able to free up some space by deleting unused files.

In some cases servers have a home directory filesystem which is very limited in size but have a much larger local disk or “scratch space” available. The application can upload to the scratch space if you create a symbolic link from your home directory to the scratch drive, for example:

mv ~/.cache /localdata/username/.cache
ln -s /localdata/username/.cache ~/.cache