Profiler Tutorial - Lumberyard User Guide

Profiler Tutorial

Profiler is in preview release and is subject to change.

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

You can register an application in GridHub and use Profiler to capture, inspect, play back, and export the data that you collect.

Registering Your Application

To enable Profiler to capture information from your application, you must first register the application in GridHub. To do so, add AzFramework::TargetManagementComponent to the application’s SystemComponent.

Note: Lumberyard's built-in applications already have this component added by default.

Launching Profiler

Unlike many Lumberyard utilities, you launch Profiler from its own executable file.

To launch profiler

  • From the Lumberyard dev\Bin64\ directory, run Profiler.exe.

              Profiler initial window

Capturing Data

Profiler has two main modes of use: capture mode and inspection mode.

To use capture mode, perform the following steps.

To capture data

  1. Click Target.

                Target button

    Profiler shows you the applications that are available for profiling:

                Applications available for profiling
  2. Select a target application.

    After you have selected a target, the target selector shows the state of the connection to the target. The next time you launch Profiler, it automatically selects your target for you, if it's available.

                Application selected for data capture

    The window is divided horizontally into channels that have associated Profiler instances. A channel is a collection of Profiler instances that relate to a specific system.

  3. Each Profiler instance in a channel has a unique color. A Profiler instance is active when its color is solid:

                Active profiler instances

    Click the color next to a Profiler instance. The color is no longer solid, showing that the Profiler instance is inactive:

                Inactive profiler instances

    Click the color again to turn on the display and activate the instance again.

  4. After you have selected a target and chosen the Profiler instances that you want to see, click Capture.

                Capture button

    After the capture begins, data begins to populate the channels.

                Capture begin
  5. To stop the data capture, click Stop Capture.

                Stop Capture button
  6. When prompted, save the captured data to disk. Profiler saves the data in a binary format file with a .drl extension, reloads the data from disk, and switches to inspection mode.


    If you do not save the data, it will be discarded.

Inspecting Data

You can use profiler to examine the data that you have captured.

To inspect captured data

  1. In Profiler, click File, Open Data, or press Ctrl+O:

                Open Data
  2. Navigate to the .drl file that contains your saved data and open it.

    The main screen of the Profiler provides an overview of the channels of system information. This example uses a file that has 1162 frames of data:

                Profiler main screen

    You can use this main view to discover anomalies across channels, or to examine particular areas of interest at a high level.

    When you open the main window, the scroll box at the bottom is on the right because the playback stopped at the end of the captured data.

    Notice the red vertical line on the right.

  3. Click in the channels area of the window.

                Click the window

    The red vertical line moves to where you clicked. The frame indicator shows the new position of the red line. You can place the red line, which is called the scrubber, on any frame that you want to examine in detail. For finer control over the position of the scrubber, you can enter a number in the Frame indicator.

                Frame indicator

    The scrubber moves accordingly.

  4. To view detailed information about a frame on which the scrubber rests, the click the Detailed Profiling Information icon next to the profiler instance whose data you would like to see:

                Detailed Profiling Information

    Profiler instance information appears in a detail window.

                Detail window

    Individual profilers present details in different ways, so their detail windows can look different. For information on system-specific detail windows in Profiler, see Using Profiler for Networking, Using the Profiler for CPU Usage, and Using Profiler for VRAM.

  5. To return to capture mode from inspection mode, click the LIVE tab.

                Click LIVE to return to capture mode

Playing Back Data

You can mark and play back a subset of your captured data.

Notice that after you moved the scrubber the first time, a yellow vertical line appeared on the right at the end of the data:

          Yellow marker at the end

This yellow marker is movable and marks the end of your desired playback range. By default, it is at the end of the captured data but may be obscured by the red scrubber.

  1. Scroll the window all the way to the left, to the beginning of the capture range.

                Yellow marker at beginning

    Now a yellow marker also appears at the beginning of the data. You can use these two yellow markers, which by default are at the beginning and end of the capture range, to restrict the range of playback to an area of data that you are interested in. You will use these shortly.

    If you have many frames of data (as in this example), the initial view does not show you all frames by default.

  2. To see all frames at once, click the Frame Count Selector, which determines the number of frames visible, and choose All frames:

                Choose all frames

    Now you can see the entire range of captured data, with the yellow markers at the beginning and at the end:

                All frames
  3. Drag the two yellow markers to an area of data that you want to play back. You can ignore the position of the scrubber for now.

                Restricted range marked for playback
  4. Click Play to start the playback:

                Play recorded data

    As the data plays back, the scrubber moves from the first yellow marker to the second, and then loops back to the first.

    Here are some tips to keep in mind:

    • If the playback speed is too fast (the default is 60), use the Playback Speed option to adjust it from 1 through 60.

    • If you click a location in the playback window during playback, the playback stops and moves the scrubber to the location that you clicked.

    • You can place the scrubber on a frame that you are interested in and click the detail button for a profiler instance to see the detail window for the frame.

    • For greater convenience and visibility, leave the profiler instance detail window open to see the data change in the detail window as the scrubber loops between markers.

                Detail window and main window open
  5. Click Stop to stop the playback.

Exporting Data

Some Profiler instances have an export option that you can use to save data to a .csv file.

To export data from a Profiler instance to a .csv file

  1. Click the Save to CSV icon for the Profiler instance whose data you want to save:

              Click Save to CSV

    Not all profilers have the data export option.

  2. To choose the fields that you want to export, click Customize in the export dialog box.

              Customize export fields