Add custom data to mobile monitoring

New Relic mobile monitoring includes a number of ways to customize and extend the data your mobile app reports. We refer to this type of implementation as "custom instrumentation." This document explains how to get additional data into New Relic, and how to view that new data in the UI.

Choose a custom data type

You can use these options to create your own data types for custom instrumentation for your mobile apps. Using these four options, you can get a wide range of data based on your needs for your apps.

Add session-level custom attributes

Custom attributes annotate (or "tag") your mobile monitoring data. A custom attribute consists of a key-value pair. For example, you might create the key userEmail with values such as alice@bigcorp.test and bob@example.com. The agent automatically attaches custom attributes to default mobile monitoring data, and to any breadcrumbs or custom events you create.

You can use custom attributes to capture usage data that's relevant to your business. Common examples include account names or IDs, user emails, and subscription levels. You can then filter and facet in the Crash analysis page and via NRQL query.

Setting custom attributes will add the key-value pair information at the session level. All default mobile monitoring events inherit these session-level custom attributes.

As a best practice, use custom attributes to track a single value for a key that can be true across a session (for example, a user's subscription level, or whether SAML was used to log in).

To track the change of a value over the course of a session, like a change in connection type, you would instead record a breadcrumb and its own custom attributes. To track a series of discrete user actions that occur across the course of a session, use custom events.

To add custom attributes, see:

• Android: Use setAttribute() and incrementAttribute().
• iOS: Use setAttribute() and incrementAttribute().

Record breadcrumbs

Breadcrumbs track the state of your app as it runs, then report a snapshot of that state if your app crashes. This allows you to debug your mobile app crashes more easily.

Custom interactions only inherit custom attributes created at the session level. Breadcrumbs will inherit those same session-level custom attributes, but optionally you can also report additional custom attributes specific to each recordBreadcrumb() API call.

You can use breadcrumbs in several ways:

• You could record a breadcrumb event when your app receives an HTTP response, and also record the values in that response as custom attributes (for example, the response might tell the app what screen to display next or recording unique timestamps for each change in the course of a session). If the app crashes or throws errors, you will be able to see invalid data from the HTTP response.
• You could track the success of each step of your user login process, with perhaps a status attribute recording a success or failure key for each step. This would let you debug which step is causing issues.

Once you have released a version of your app that creates MobileBreadcrumb custom events, you can see them in the crash event trail whenever they appear in the app's code path as part of a crashed session. You can also query them using NRQL and query either all breadcrumbs or just breadcrumbs from crashed sessions. This lets you see the frequency of app paths that include that particular breadcrumb.

To add custom breadcrumbs, see:

• Android: Use recordBreadcrumb().
• iOS: Use recordBreadcrumb().

Create custom interactions

Our mobile monitoring agent begins instrumenting an interaction when it detects a screen load or partial screen load (such as fragments for Android or view controllers for iOS). New Relic automatically traces slow interactions, providing a complete, in-depth picture of a single slow interaction, including the methods that were called, what network requests were made, and the CPU and memory usage once that interaction started.

Our mobile monitoring automatically selects data-rich traces. The specific criteria the agent looks for are interactions whose instrumented methods account for at least 30% of the overall interaction time.

In addition to the auto-instrumentation, you can start a custom interaction to force the agent to start recording a trace beginning at that point in your app code and continuing across the subsequent methods and network calls. Custom interaction traces provide deep information. However, they increase the overhead of the agent compared to other custom data collection methods because of the large amount of data collected for the entire duration of an interaction.

When associated with a crash, custom interactions show up in the crash event trail. You can also query them with NRQL for flexible analysis.

Interactions are powerful for tracing but are less flexible in other ways than other custom data types: While custom breadcrumbs and custom events let you optimize your custom attributes to specific events, interactions can only inherit session-level attributes.

You can also manually end a custom interaction. However, ensure that the interaction includes enough method activity to be recorded. If the agent does not detect any traced activity for 0.5 seconds, the agent stops the interaction tracing because it is assumed no interesting data remains. In addition, the agent can only trace one interaction at a time, so if a new interaction is triggered the current trace will automatically be stopped in preference for the new trace.

To add custom interaction traces, see:

• Android: Use startInteraction() and endInteraction().
• iOS: Create and complete interactions.

You can also configure interaction tracing globally:

• Android: Disable entirely with withInteractionTracing(), or disable only auto-instrumented traces with withDefaultInteractions().
• iOS: Disable entirely with NRFeatureFlag_InteractionTracing(), or disable only auto-instrumented traces with NRFeatureFlag_DefaultInteractions().

Record custom events

Custom events are a powerful tool for reporting arbitrary user activity to New Relic. When associated with a crash, custom events show up in the crash event trail. You can also query them with NRQL for flexible analysis. Unlike custom interactions, custom events allow you to add custom attributes to a particular event within the user session.

For example, you could record a custom event each time a user taps a button or accesses a certain feature, and then use NRQL to track how often that feature was used. Beyond a simple count, you can FACET on default mobile app attributes such as location, device, or carrier to analyze usage. Adding session-level custom attributes would let you further examine usage based on the criteria important to you, such as user subscription level or other user characteristics. Adding additional attributes for that custom event would allow you to track user behavior more closely: What data did they enter or what option did they select, for example.

To add custom events, see:

• Android: Use recordCustomEvent().
• iOS: Use recordCustomEvent().