Using the Cascades Profiler

By default, when you click Momentics IDE launch button to launch the QML Profile launch mode, the Cascades Profiler starts profiling during application launch. The Cascades Profiler connects to the profiler port and the profile editor opens.

Screen showing a profiling session started for the LightningCrossfadeQML sample app.To see your profiling data, click the Stop button in the upper-left corner of your profile editor window.

When you profile your app, data is collected on the device and downloaded to the IDE when you stop the profiler. You can continue your profiling session by pressing the start or stop button as many times as you want as long as the app is running.

Screen showing the Cascades Profiler Save As and Save Window As buttons.You can use the Save As and Save Window As buttons to save your profiling data to a file. When you click Save As, the profiler saves all your profiling data to a file. When you click Save Window As, the profiler saves the data only for the window that you select.

Understanding views and data

You can view the profiling data in the profiler editor window. The profiler editor has two views:

  • Timeline view: Provides details about the three main QML threads: frame rendering, image loading, and QML engine
  • Events view: Shows the events in each thread

Timeline view

The Timeline view shows you the time that your app spends in the frame rendering, image loading, and QML engine threads. You can expand the Frame Rendering Thread, the Image Loading Thread, and the QML Engine Thread views to see the details. You should see a very small number of frames per second for each item in these threads. For example, the duration of a frame rendering span should be less than 16 milliseconds so that the app can render 60 frames per second.

When you hover over a span in the Timeline view, you can see the duration and time stamp information, and the thread that the span belongs to. You can adjust the view of the spans by expanding or collapsing the viewable window in the lower-left corner of the profiler editor window.

In the example below, the time window is reduced in the navigation area (the timespans are enlarged). By default, the navigation area extends over the entire width of the window.

Screen showing the profiling data for the CascadesCookbookQML sample app.

The Image Loading Thread view displays the time that your app spends loading each image as a percentage of how much time your app takes to load all the images. You can double-click the image in the Image Loading Thread to view the image.

The Cascades Profiler can open assets (images or QML files) only if they are available in your Eclipse workspace. If you generate images or QML assets dynamically on the device, the profiler can't open the files. The Cascades Profiler stores the name of the project that you are profiling in your saved .trace files. If you open the .trace file in a different IDE, where the project isn't available, you can't open the images or QML files.

The QML Engine Thread view shows you how long your app takes to create and compile (if you start profiling during application launch). Creating and compiling your app involves binding and initializing all the properties that your app uses in the QML engine thread. This process is sequential. By default, the rendering spans appear in the order that they occur based on the time stamp.

Screen showing the Cascades Profiler Idle spans and navigation buttons. To see the longest span, you can order the spans by duration and use the arrows at the top of the profiler editor window to navigate through the spans.

The smallest amount of time that is recorded for each event is one millisecond. For example, even if an event took only 0.25 milliseconds to execute, the QML Engine Thread view shows one millisecond as the duration of the event.

Events view

The Events view lets you look at frame rendering information and examine the call stack by filtering based on selected events, function (caller), or function being called (callee). You can look in the Details column to see the first lines of code that were executed for each event, or you can double-click events to open your QML file at the code that was executed. You can use the arrows to move forward or backward in the call stack.

In the image below, the main.qml thread was selected in the QML Engine Thread view. The lower pane shows the events that were called by main.qml.

Screen showing the Cascades Profiler Events View.

Analyzing the data

When you look at your profiling data, you should first look at long spans. You can order the spans by length and you can double-click the spans to see the code that they execute. Pay attention to the following patterns in your profiling data:

  • Look at idle spans if you want to see if there's anything else going on, such as background processes. By default, the idle spans are hidden. To see the idle spans, click the Show/Hide Rendering Idle Spans button on the toolbar.

  • Check out long spans of frame rendering (for example, spans longer than 100 milliseconds). When your app is busy rendering frames, the UI might not appear smooth and responsive.

  • Look at the creating block. If the creating block is too long, it might be waiting for each binding to finish. Consider using smaller bindings.

  • Look for unnecessary bindings that run frequently.

  • Check your compile times. If your compile times are longer than you expected, you can use QML assets that are loaded dynamically to postpone some of the compiling in your app.

  • Check the handling signal. If it's too long, you should investigate. Hover over the signal and expand the categories to find the source code.

  • Look at the time it takes to set up the UI. If you use a network request to display data when your app starts, consider making the network request before you create the UI. For more information about improving startup times, see Improving startup performance of Cascades apps.

Configuring the Cascades Profiler

You can use the Run Configurations wizard to change your run configuration for profiling.

Screen showing the Cascades Profiler tools configuration.

To configure your app for profiling:

  1. In the Project Explorer view, right-click any project and click Run As > Run Configurations.
  2. On the QML Profile tab, select the Start profiling during application launch check box if you want to collect creating and compiling times. If the check box is cleared, you can profile manually whenever you want. This feature is useful if you are only interested in profiling certain events in your app.
  3. Click Apply, and then click Close or Run.

By default, the Cascades Profiler uses port number 5768. You can change this value to another number, but you should ensure that the port number isn't used or reserved, or the profiler may not be able to connect.

Troubleshooting your configuration

To profile QML and JavaScript code in your Cascades application, you don't need to add or change any code in new projects that use the templates that the IDE provides. The Cascades project build system ensures that the qt_declarative_debug macro is defined in the debug build.

If you want to profile an existing project or an application compiled in a Device-Release configuration, you must add the following code as the first lines of your main.cpp file:

// Enable declarative debugging/profiling
#include <qt4/QtDeclarative/qdeclarativedebug.h>

You should profile applications in a debug build configuration only (for example, Device-Debug or Simulator-Debug). For more information, see Build your app.

If data doesn't appear in the profiling editor window, open the Device Log in the Console View, select the buffer set for your app, and then filter for the message "QDeclarative". You should see two messages that indicate that you're using the Qt library with profiling support and a port on which Qt is awaiting connection.

Screen showing the Cascades Profiler connections in the Device Log.

You can also filter for messages that contain the word "profile". You should see three messages that indicate that the Cascades Profiler has started. You should also be able to see the server-side connections, the trace engine instance that was created, and the trace engine instance that was registered.

Screen showing the filtered Cascades Profiler connections in the Device Log.

If you don't see these messages, it's possible that your target is running a version of the OS that doesn't support the Cascades Profiler. The Cascades Profiler works only if you run your app on a BlackBerry device or BlackBerry 10 Device Simulator that is running BlackBerry 10 version 10.1 or later.

Last modified: 2015-03-31

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus