Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed formatting, updated code samples with line numbering and format type, and updated some instructions.


The Appcelerator Performance service, powered by Apteligent, monitors your application's health, crashes, and overall performance. Using Appcelerator Performance, developers are able to analyze crash reports to see why applications crashed and focus on the specific problems on user feedback.

This topic covers how to use the APSPerformance API.  For For information about using the Performance Dashboard, see Application Details Screen: Performance Tab.


To use the Appcelerator Performance service, add the APS library to your project, then use the APSPerformance API to add breadcrumbs, user metadata, and exception handling code to log events leading up to a crash.  Login Login to the Appcelerator Dashboard and use the Appcelerator Performance dashboard to monitor application performance and analyze crash reports.



your project

To integrate the Performance service with a new or existing Android application:

  1. Go to the Appcelerator Dashboard and create a new native Android application.
  2. Download the Services SDK and get your Performance application key.
  3. Unpack the Services SDK ZIP file.
  4. Copy the  appcelerator-sdk-android-<VERSION>.jar  to the  lib  folder of your Android project.
  5. Modify the project's AndroidManifest.xml file to include the following permissions: 

    Code Block
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android=""
        android:versionName="1.0" >
        <!-- Add these permissions to enable Performance -->
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
        <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
        <uses-permission android:name="android.permission.INTERNET"/>
        <!-- Optional permissions for advanced reporting -->
        <uses-permission android:name="android.permission.GET_TASKS" />
        <uses-permission android:name="android.permission.READ_LOGS"/>
  6. Add the following import statements to the main Activity of the project: 

    Code Block
    import com.appcelerator.aps.APSServiceManager;
    import com.appcelerator.aps.APSPerformance;
  7. In the main Activity's onCreate() method, enable the service by calling the APSServiceManager's enable() method.  Pass Pass the method the application context as the first argument and the APS application key as the second argument.  This This provides basic app monitoring and crash reporting services.

    Code Block
    public void onCreate() {
        APSServiceManager.getInstance().enable(getApplicationContext(), "APP_KEY");

    To get your APS App key:

    1. Go to the Appcelerator Dashboard (login may be required).
    2. Click Go in the Dashboard section.
    3. Select your application from the Apps drop-down menu.
    4. Click the Overview tab.
    5. Click the Services button.
    6. Click Show Key under the Analytics, Performance and Cloud section.

The Android application can now make additional method calls using the APSPerformance class.  Before Before making API calls to the APSPerformance class, you need to retrieve a shared instance using the the getInstance() method.  Make Make APSPerformance API calls using the shared instance.

Create a


breadcrumb trail

To make it easier to track the events leading up to a crash, use the leaveBreadcrumb() method to add breadcrumbs in your code.  Place Place breadcrumbs near events and application state changes to track problematic paths that can lead to an application crash.  Append Append variables to your breadcrumbs to track their state.  For For example:

Code Block
public static int alphaCB (int value) {
    APSPerformance.getInstance().leaveBreadcrumb("enter alphaCB:" + value);
    //do some stuff...
    APSPerformance.getInstance().leaveBreadcrumb("exit alphaCB:" + result);
    return result;
public static int betaCB (int value) {
    APSPerformance.getInstance().leaveBreadcrumb("enter betaCB:" + value);
    // do some stuff...
    APSPerformance.getInstance().leaveBreadcrumb("exit betaCB:" + result);
    return result;
switch (state) {
    APSPerformance.getInstance().leaveBreadcrumb("switch:" + state);
    case x : 
    case y :
    default :

These breadcrumbs are collected and passed to the Appcelerator Performance service.  To To view the breadcrumbs, in the Appcelerator Performance dashboard, when viewing a specific application, click either Crash Reports or Handled Exceptions.  In In the list of crashes or handled errors in the right pane, click on the crash or error to view its details.  Click Click the Breadcrumbs tab to view the breadcrumb trails leading up to the crash or error.

The most recent 100 breadcrumbs are displayed before the crash occurred.  A A breadcrumb can be up to 140 characters.



user metadata

Use the the setUsername() and setMetadata() methods to differentiate users of your application when viewing reports on the Appcelerator Performance dashboard.  For For example:

Code Block
boolean status = login(username);
if (status) {
    // Sets the username
    // Sets some user state metadata for tracking errors
    APSPerformance.getInstance().setMetadata("lastLogin", datetime);
// Track the user's state
APSPerformance.getInstance().setMetadata("gameLevel", 0);
// do some stuff...
APSPerformance.getInstance().setMetadata("gameLevel", 1);
// do some stuff...
APSPerformance.getInstance().setMetadata("gameLevel", 2);

The username appears with the crash or error reports. By default, a guest profile is created to differentiate users if a username is not specified.  To To retrieve this unique identifier, use the  getUniqueIdentifier() method.

To access the user metadata, either click on a username in a crash or error report to open a detailed view, or in the Appcelerator Peformance dashboard, when viewing a specific application, click Search by User in the left pane then in the right pane, enter a user's name to find information about them.



an exception

You can track handled exceptions in your application by passing a Java Exception object to the logHandledException() method, which can help identify and analyze potential errors and hot spots.  For example:

Code Block
try {
    throw Exception("FATAL ERROR!");
catch (exception) {


To view handled errors, in the Appcelerator Peformance dashboard, when viewing a specific application, click Handled Exceptions in the left pane.  A A list of handled errors and statistics appears in the right pane.  Click Click an error to view it in more detail.

Appcelerator Performance limits the logging of handled exceptions to one per minute. Up to five  exceptions are buffered and are subsequently sent after the one minute limit.

Allow the


user to





Use the setOptOutStatus() method to allow the user NOT to send any information to the Appcelerator Performance service.  Passing Passing true to this method disables sending data to Appcelerator Performance.

Code Block
// Disable sending data to Appcelerator Performance

Check for a



Use the didCrashOnLastAppLoad() method to check if the application crashed in a previous session. If the method returns true, the application crashed on the last session.  Note Note that if setOptOutStatus() is set to true, this method always returns false.

Code Block
if (APSPerformance.getInstance().didCrashOnLastAppLoad()){
    // Application crashed on the last load
    // Do something...




For complete API information, see APSPerformance API.