Profiling

The Momentics IDE for BlackBerry contains tools that you can use to analyze the performance of your app. To use these tools in the IDE, you can set up a launch configuration to define which tools to run with your app (for example, the Application Profiler, the Cascades Profiler, the Code Coverage tool, or the Memory Analysis tool). For more information about the tools, see Using the Momentics IDE.

You can use the Application Profiler and the Cascades Profiler to examine the overall performance of your applications, without following the source code one line at a time. While a debugger helps you find errors in your code, profilers identify areas of your code that could run more efficiently and highlight functions that consume the most CPU time. When you profile your code, the IDE inserts code before each function to gather call information (Call Count instrumentation), or just after the function enters and just before the function exits (Function instrumentation).

Profiling a C/C++ project

If you're creating a Cascades C++ application and developing the application UI in C++ only, you can use the QNX Application Profiler perspective and the Application Profiler tool in the Momentics IDE. The Application Profiler traces execution of your code and provides statistics on how much time your app spends in each function.

Screen showing the C/C++ profiling toolbar in the Momentics IDE.

To use the Application Profiler to profile a C/C++ project:

  1. Make sure your app is showing in the Active Project window or select it from the drop-down list.
  2. In the Action drop-down list, select Profile C/C++.
  3. Click Profile button.

For more information about configuring your C/C++ project for profiling, see Use the Application Profiler.

Profiling a QML project

If you're creating a Cascades project with QML components, you can use the Cascades Profiler. The Cascades Profiler is a tool that lets you profile Cascades QML applications visually.

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. You can't use the Cascades Profiler for earlier releases of your target device.

The Cascades Profiler shows you information about frame rendering, image loading, loading and compiling of QML files, QML signal handling, and time consumed by running QML bindings. 

Screen showing the QML profiling toolbar in the Momentics IDE.

To use the Cascades Profiler to profile a QML project:

  1. Make sure your app is showing in the Active Project window or select it from the drop-down list.
  2. In the Action drop-down list, select Profile QML.
  3. Click Profile QML button.

For more information about profiling your QML project, see Using the Cascades Profiler.

Using the Cascades Profiler

By default, when you click Profile QML button, the Cascades Profiler starts profiling during application launch. You see the Cascades Profiler connecting to the profiler port and the profile editor window 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 data that the Cascades Profiler gathers by using the profile 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 images 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 an image or a QML asset 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.You can order the spans by duration to see the longest span, and then you can 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 Tools tab, click Add/Delete Tool.
  3. Select the Cascades Profiler check box and click OK.
  4. 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.
  5. 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
#define QT_DECLARATIVE_DEBUG
#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 Setting the build configuration.

If data doesn't appear in the profiling editor window, open the Device Log in the Console View, and 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 contains 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: 2014-01-23

comments powered by Disqus