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.

You support this feature by:

  • 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:

  • Debug log entries -- when NSLog message text isn't prepended by the text "Error:"
  • Error log entries -- when NSLog message text is prepended with "Error:"
// 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.

The ApigeeLogger includes the following macros:

ApigeeLogAssert(<tag>, ...)
ApigeeLogError(<tag>, ...)
ApigeeLogWarn(<tag>, ...)
ApigeeLogInfo(<tag>, ...)
ApigeeLogDebug(<tag>, ...)
ApigeeLogVerbose(<tag>, ...)

The following table describes the arguments:

Argument Description
<tag> A category you specify to identify a subsystem or class of messages.
... The standard variable argument list as used in NSLog.

The following example illustrates the syntax:

ApigeeLogAssert(@"MyTag", @"A message containing %d arguments: %@", 2, @"my second argument");

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:

 + (ApigeeLogger *) logger;

  ...

  - (void) assert:(NSString *) tag format:(NSString *) format, ...)
  - (void) error:(NSString *) tag format:(NSString *) format, ...)
  - (void) warn:(NSString *) tag format:(NSString *) format, ...)
  - (void) info:(NSString *) tag format:(NSString *) format, ...)
  - (void) debug:(NSString *) tag format:(NSString *) format, ...)
  - (void) verbose:(NSString *) tag format:(NSString *) format, ...)

@end

The following example illustrates:

[[[ApigeeLogger] logger] info:@"My Tag" format:@"My message constructed from %d arguments: %@", 2, @"the rest of the message"];

Enabling error & crash monitoring

To log crash and error messages using the Apigee SDK, do the following:

  1. If it is present in your project, remove or comment out the import of the default Android Log class:
    import android.util.Log;
  2. Import the Apigee SDK Log class
    import com.apigee.sdk.apm.android.Log;

    This is necessary because the interface for Apigee's Log classes matches that of the default Android Log class.

Using the Apigee Log class

The Log class includes the following methods:

Log.v(<tag>, <message>);  // verbose
Log.d(<tag>, <message>);  // debug
Log.i(<tag>, <message>);  // info
Log.w(<tag>, <message>);  // warning
Log.e(<tag>, <message>);   // error
Log.wtf(<tag>, <message>);  // assert/critical

The following table describes the arguments:

Argument Description
<tag> A category you specify to identify a subsystem or class of messages.
<message> The message to send to the log.

The following example illustrates the syntax:

Log.e("MyTag", "A message describing the error.");

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:  

client.logVerbose({tag:"<tag>", logMessage:"<message>"})
client.logDebug({tag:"<tag>", logMessage:"<message>"})
client.logInfo({tag:"<tag>", logMessage:"<message>"})
client.logWarn({tag:"<tag>", logMessage:"<message>"})
client.logError({tag:"<tag>", logMessage:"<message>"})
client.logAssert({tag:"<tag>", logMessage:"<message>"})

The following table describes the parts of the JSON sent by each function:

Argument Description
<tag> A category you specify to identify a subsystem or class of messages.
<message> The message to send to the log.

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:

  1. 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.
  2. Select the dropdown menu for the metadata you want to filter by. For descriptions of the options, see Data displayed for logs.
  3. Select the amount of log data you want to view, measured as the amount of time preceding the current time.
  4. 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:

  1. In the admin portal, click Configure.
  2. 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).
  3. Click Save Changes.

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:

  1. In admin portal, click Configure.
  2. Select your app in the app list at the top of the page.
  3. In the Application Specific Configs section, add an entry with the following values:
    • Category (the left-hand field): ALARM 
    • Key (the middle field): SUPPRESS_ALARMS
    • Value (the right-hand field): true
  4. Click Save Changes.

Disabling error and crash logging

The best way to disable error and crash logging is by using the admin portal. To disable logging, use the following steps:

  1. In the admin portal, click Configure.
  2. On the Default Configs page, clear the Enable Log Capturing check box.
  3. Click Save Changes.

You can also disable logging programmatically, as described below.

If you want to disable error and crash logging programmatically with the App Services SDK for iOS, do the following when you initialize the ApigeeClient class in AppDelegate.m:

  1. Instantiate ApigeeMonitoringOptions and set crashReportingEnabled to NO:

    ApigeeMonitoringOptions *monitoringOptions = [[ApigeeMonitoringClient alloc] init];
    monitoringOptions.crashReportingEnabled = NO;
    				
  2. Send monitoringOptions as the value of the options parameter when you initialize the ApigeeClient class:

    		
    appDelegate.apigeeClient = [[ApigeeClient alloc]
                                initWithOrganizationId:orgName
                                applicationId:appName
                                options:monitoringOptions];
    				

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.

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)