Monitoring app errors and crashes

Using API BaaS, you can view data logged by your app about app errors and crashes. When your app supports this feature, data collected from logged errors and crashes is displayed in graphical form in the admin portal. Using these charts in the portal, you can track trends in your app's performance and apply fixes and performance improvements as the need arises.

Logging messages from your app's code. The way you do this will differ based on the platform on which your app is deployed.

Configuring the admin portal to: enable log capturing and specify the level at which logs should be captured.

In the admin portal, in the Monitoring > Errors & Crashes section, you can view log data displayed both graphically and in raw form.

Data Available

Description

App errors

These are errors logged by your app's code. API BaaS retrieves messages logged by your code and displays data from the logs as reports in the admin portal. You may need to instrument your code to support this feature. For more information, see Logging app errors.

Crashes

These are errors logged by the device's operating system when your app crashes. Logged data is summarized for each crash and can include the operating platform and device model.

The admin portal provides a crash log pointer. Use this to download a crash stack trace recorded by the operating system. To get the crash log link, ensure that you're on the Errors & Crashes page (use the left-hand navigation, under Monitoring) and select Crashes from the leftmost dropdown at the top of the page.

In iOS, you will need to symbolicate the memory addresses in the crash log, which are shown as hexadecimal values. Symbolication replaces each hex address with function name, filename, and line number information. See Symbolicating iOS Crash Logs for further details.

Logging app errors

To support having your app's error logs picked up by API BaaS, you'll need to instrument your app by logging from your code. How you support this will differ depending on the platform on which your app is deployed. With logging APIs provided with the Apigee SDKs, you can capture information at log levels similar to other frameworks you might have used.

Once your code is creating log messages using the APIs, you can configure the admin portal to specify the level at which these messages should be captured. For more information, see Setting log capture level.

When logging, you code should clearly identify the severity of the error and generate an error message that clearly identifies the error situation.

Within an iOS app, there are two ways you can log data that's retrieved by API BaaS: by using NSLog calls and by using macros defined in the Apigee iOS SDK.

With your NSLog calls, you can log error and debug level messages in the admin portal. Support for NSLog in API BaaS allows you to use your NSLog calls rather than using a separate API. However, with NSLog, API BaaS supports only the error and debug message levels.

With the Apigee iOS SDK macros, you can log the full range of messages for tracking in the admin portal: assert, error, warn, info, debug, verbose.

Logging with NSLog

API BaaS is designed to listen for your NSLog calls and to send data from those calls to the server, where you can track them. Your NSLog calls will generate two kinds of monitoring data for the admin portal:

// Log a message that will display as debug message.
NSLog(@"Device registered for push notifications");
// Log a message that will display as an error.
NSLog(@"error: Server does not recognize payload");

Logging with the Apigee SDK logger class

To support logging the full list of log levels in the admin portal, you can use the Objective-C class ApigeeLogger included in the App Services iOS SDK. The log levels supported by the logger class correspond to the levels you can select as a reporting threshold when you configure logging in the admin portal.

You can log in two ways. The easiest way is to add the included macros to classes in your app from which you want to log messages. The other, described below, is to use the Objective-C API that supports the macros.

You can also use the Objective-C API that supports the macros. However you will not automatically get the function context. Use the Objective-C API if you don't need the calling context in your log messages. If you use the Objective-C API, add the following code to any class where you want advanced logging:

To log messages in JavaScript that will be retrieved by App Services, use the Apigee.Client class available with the App Services JavaScript SDK. The Apigee.Client class includes the following functions. Each function takes as an argument a JSON body containing options for the request:

Viewing error and crash log data

Using the admin portal, you can easily filter charts and lists that capture app error and crash log data. You filter the data presented by selecting from the dropdowns at the top of the Errors & Crashes page. As you make selections from the menus, the data represented on the page adjusts to reflect your selections.

The table below describes the options available in the menus. To filter log data views, follow these steps:

On the Errors & Crashes page, in the far left dropdown, select the category for the kind of log data you want to view: overview, app errors, or crashes.

Select the dropdown menu for the metadata you want to filter by. For descriptions of the options, see Data displayed for logs.

Select the amount of log data you want to view, measured as the amount of time preceding the current time.

To compare current log data with data from the preceding week or day, click Compare Last Week or Compare Yesterday.

Tips for viewing log data

As you're using the Errors & Crashes page, keep in mind the following tips for collecting information.

Use the menus at the top of the page to filter to the data you want to see.

Hovering the mouse pointer over charts will pop up specifics about data behind the chart.

Clicking a data point on some charts will display a popup with details about that data snapshot.

In some charts, clicking an item in the legend will hide or display the data corresponding to that item.

Data displayed for logs

The following table describes the kinds of data captured in the various charts and tables provided on the Errors & Crashes pages of the admin console. Note that not all data is available from both crash and app error logs.

Data

Description

Log Type Supported

App version

The version of the app.

Crash

Carrier

Carrier such as AT&T, Sprint, or Verizon.

App error

Crash log pointer

A pointer to the crash log.

Crash

Device ID

The Apigee device id for the device. The device id is a unique ID that is randomly generated in the App Services SDK when your app is first started in the device.

App error, crash

Device model

The device model, such as Apple iPhone 4g.

App error, crash

Log message

The message that was logged.

App error

Network type

Network type, such as 3G, 4G, and Wifi.

App error

OS

The platform version for the device, such as iOS 6 or Android 3.2.

App error, crash

Platform

The platform for the device, such as iOS or Android.

App error, crash

Severity

The severity of the error, such as ERROR or WARN.

App error

Tag

A category you define to group log messages.

App error

Time stamp

The time stamp of the crash.

App error, crash

Searching error logs

You can search for specific kinds of messages in the app error and crash logs. For example, if you've created specific messages for a new function in your app, you can search for those messages by entering an appropriate search string in the Message column.

You can search in the modes described in the following table:

Category

Description

Simple search

Provides a way to search the log message description text. Type a phrase to find messages whose description contains that text. This is the default view. If it is not displayed, click Hide Advanced to switch back to simple search.

Advanced search

Click Show Advanced for a way to filter by metadata that accompanies a log message. In the metadata category you want to filter by, type the first characters of the value you with which you want to filter.

Setting log capture level

You can control the level at which API BaaS will track logged errors. The log level filtering is based on the log level you choose. Each level is inclusive of the levels below it, that is, each level includes itself and any lower level. The available levels are:

Assert

Error

Warn

Info

Debug

Verbose

To configure error level capture, use the following steps:

In the admin portal, click Configure.

On the Default Configs page, in the Log Capture Level dropdown, select the logging level representing the least severe level you want to capture. App Services will capture messages at this level and greater (that is, more severe).

Disabling alert emails

Any error with a log level of "Assert" will automatically trigger an email alert that contains information about what happened, where it happened (such as in which phone model, device ID, and operating system), and when it happened.

You can suppress these alert emails. You might want to do this if you receive an unusually large number of email notifications, which may happen if your app has a bug that affects a large percentage of your users.

To disable alert emails:

In admin portal, click Configure.

Select your app in the app list at the top of the page.

In the Application Specific Configs section, add an entry with the following values:

You can disable error and crash reporting programmatically by using the MonitoringOptions class in the Apigee Android SDK. The following code illustrates how to do this using one of the methods that takes the options object as an argument:

// Create an options object and set crash reporting enabled to false.
MonitoringOptions monitoringOptions = new MonitoringOptions();
monitoringOptions.setCrashReportingEnabled(false);
// Use the options object when you create an instance of ApigeeClient.
ApigeeClient apigeeClient = new ApigeeClient(orgName, appName,
monitoringOptions, this.getApplicationContext());

To programmatically disable error and crash reporting with JavaScript, you will need to disable all monitoring. For more information, see "Disable app usage monitoring" in Monitoring app usage data.