AGI System Profiler UI

Overview

The System Profiler trace viewer UI is split into three parts: the button bar and timeline at the top, the expandable/collapsable details panel at the bottom and a scrollable track area in the center. The button bar contains the navigation mode buttons, a track filter textbox that can be used to filter which tracks are shown, an info button that will display some metadata about the trace and the device it was taken on, and a help button that will display the keyboard and mouse shortcuts. The detail panel at the bottom wil automatically expand and show information about the currently selected item or items.

Tracks and Track Groups

The profiling data is displayed in tracks stacked vertically. Some tracks, such as the thread tracks, can be expanded and collapsed via a button to the right of the track name. Many tracks are grouped into track groups that can be expanded and collapsed by clicking the chevron on the left of the group's name. Some track groups will display a summary of its tracks, when collapsed. For example the CPU track group will show the overall CPU usage as a graph if it is collapsed.

Tracks and track groups can be pinned and unpinned via the pin button to the right of the track or track group name. Pinned tracks and track groups are displayed at the top, right beneath the timeline, and do not scroll.

Navigating around the trace is best done via the WASD keys and the mouse wheel.

  • The W and S keys, as well as Ctrl++ and Ctrl+- zoom in and out.
  • The A and D keys, as well as the left and right arrow keys pan the view left and right.
  • The Q and E keys, as well as the up and down arrow keys scroll the tracks.
  • Holding shift will increase the movement speed of the pressed buttons.

The mousewheel can be used to scroll and pan the tracks. Holding Ctrl while scrolling the track wheel will zoom in and out. Track pad guestures for scrolling and zooming are also supported.

The button bar at the top of the UI contains buttons to switch between the four navigation modes. The current selected navigation mode controls the action of the drag of the primary mouse button. The navigation mode can also be switched using the keyboard's 1, 2, 3, and 4 buttons:

  1. Selection Mode: In this mode dragging can be used to box-select multiple items in the tracks.
  2. Pan Mode: In this mode, which is the default, dragging will pan and scroll the tracks.
  3. Zoom Mode: Dragging the mouse vertically will zoom in and out.
  4. Timing Mode: Dragging the mouse will allow you to select a time range.

Regardless of what the current mode is, all of the above actions can also be achieved via modifier keys:

  1. Shift+Drag to box select items.
  2. Space+Drag to pan and scroll.
  3. Ctrl+Mouse Wheel to zoom.
  4. Ctrl+Drag to select a time range.

Other Keyboard Shortcuts

  • F will zoom in/out to the current selection.
  • Z and 0 will reset and completely zoom out.
  • V toggles highlighting VSync if it is available in the trace.
  • M will mark the current selection by selectig its time range.
  • H and ? will show a little keyboard and mouse shortcut cheatsheet.

A Note for Systrace Users

Users of the legacy Systrace tracing tool may notice that these keyboard and mouse shortcuts match what they are used to from Systrace. This is done by design. We hope you will feel right at home in AGI's System Profiler!

Zoom and Data Aggregation

When a profile trace is first opened, the UI shows the entire trace at the maximum zoomed-out level. This is to give a quick overview of the entire trace. Inspecting the profile is then finding an area of interest from this overview and drilling down into the details by zooming in on hotspots. In order to show usable data when zommed out, AGI will aggregate the profiling data appropriatly for each zoom level. For many tracks, there is a cut-over zoom level, where the data may be shown in a different way that is more suitable for its aggregated form. For example, the CPU tracks, while zoomed in show the time slices of each thread executing on the CPU cores, but when zooming out will eventually switch to a graph showing the core's utilization instead.

Selection and Details

Events captured by the profiling system are often rich in metadata associated with them. A lot of this data can not easily be displayed in the track view. However, you can view these extra details by selecting items in the track view. If a hovered item supports selecting, the mouse curser will change to the pointer / hand icon and left clicking will select the hovered item. Selecting items will cause the details panel at the bottom to expand and display information about the currently selected item.

It is also possible to select multiple items at the same time. Left clicking on an aggregated data item will function as if all aggregated data items have been selected. Similarily box-selection can be used to select many items, even from various tracks. When multiple items are selected, the details view changed and shows a tabular aggregated view appropriate of the selected items.

The details panel can be resized by dragging the divider, and collapsed/expanded by clicking the chevron on the right side. To clear the current selection press Esc or click on an empty area in the track view.

Time Range Selection

It is often helpful to be able to focus on a specific time range and attempt to line up events from different tracks. This is what time range selection is for. To select a time range, drag the mouse in the Timing mode, or Ctrl+Drag in any mode. The start and end of the range can be modified by dragging the marker lines, which highlight when hovered. When a time range is selected, everything outside the range is dimmed and duration of the selected range is displayed, allowing easy measuring.

Another helpful way to select a time range in order to inspect what happens on other tracks, is to press the M key to mark the currently selected slice and align the time range to its start and end. Scrolling through the tracks then makes it easy to spot what else was happening at the same time.

GPU Tracks

The GPU tracks in AGI's System Profiler give an inside view into the goings-on of the GPU. There are four main track types you will see in the GPU section, depending on what data sources were enabled during the trace capture: 1. GPU Queue Tracks: These tracks show the GPU activity of our application. 2. GPU Counter Tracks: These tracks show the GPU's hardware counters sampled at periodic intervals. 3. Vulkan Events Track: This track shows Vulkan API related events recorded during the trace. 4. SurfaceFlinger Tracks: These tracks show SurfaceFlinger events and show how the graphics buffers move through the system.

GPU Queue Tracks

GPUs are highly parallelized and some have multiple hardware queues than can execute different types of work simultaniously. On sucnh devices you will see more than one track. These tracks contain slices which represent time spans the GPU was executing work for your application. Each slice will indicate what type of work the GPU was executing.

Each GPU activity slice is also associated with a lot of metadata, so it is highly recommended to select slices and inspect their details. One useful feature is that the slices are associated with the Vulkan command buffer, render pass, and frame buffer that initiated the work. The Vulkan handles of these objects are displayed in the details tab. Since these handles are ephemeral, we recommend you use the vkSetDebugUtilsObjectNameEXT function from the VK_EXT_debug_utils extension, or the vkDebugMarkerSetObjectNameEXT function from the VK_EXT_debug_marker extension to give your VkFrameBuffer, VkRenderPass, and VkCommandBuffer objects names that will be surfaced in the trace alongside the handles. Both of these extensions are implemented by AGI and made available to the application while tracing.

GPU Counter Tracks

The GPU counter tracks graph the value of the GPU's hardware counters sampled at a periodic interval and provide insight into the GPU's activity. The counter tracks show the difference in the underlyig hardware counter between samples and are often normalized to a "per second" rate or percentage. The counters can give you great insight into where your GPU usage may be bottlenecked by highlighting the business of the various hardware components of the GPU. The available counters is hardware specific and the UI will show a short description of each counter when hovering over the track name. For more details on the available counters, please consult our GPU counters (TODO: fix this link) page.

Vulkan Event Track

The Vulkan event track shows Vulkan API level events recorded during the trace. The main events currently tracked are calls to vkQueueSubmit. Clicking on a queue submit event, will highlight all the GPU activity slices associated with that submit. This allows you to get a better understanding of the asynchronous work queued by your usage of the Vulkan API and understand any latency between the CPU and GPU.

SurfaceFlinger Tracks

The SurfaceFlinger tracks show you how the graphics buffers, i.e. your application's swapchain render targets, move through the system all the way to when they are shown on the display. These tracks show events emitted by SurfaceFlinger during the trace and aggregates them by buffer. This makes it easy to track overhead needed for aquiring and posting buffers and the associated latency.