New Relic Mobile includes a number of ways to customize and extend the data your application sends to New Relic. New Relic refers 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 New Relic 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.
|Custom Data Options||Description|
|Session-level custom attributes||In creating your own attributes, consisting of a key-value pair, you can add custom data for use in tracking session data.|
|Custom breadcrumbs||Useful for troubleshooting crash causes, custom breadcrumb events track the user's code-level path through the app by seeing which breadcrumb API calls were reached and reporting app status details from those moments.|
|Custom interactions||Custom interactions give you tracing power so you can debug method timings and improve network call efficiency. A common use of interactions is to understand the underlying activity associated with loading a particular app screen.|
|Custom events||You can instrument custom events to collect data about user activity as a user navigates through your app. That user activity will in turn trigger other data collection: a collection of breadcrumbs, auto-instrumented HTTP requests and errors, auto-instrumented interactions, and custom interactions.|
Access to these features depends on your subscription level.
Add session-level custom attributes
Custom attributes annotate (or "tag") your New Relic Mobile data. A custom attribute consists of a key-value pair. For example, you might create the key
userEmail with values such as
email@example.com. The agent automatically attaches custom attributes to the default data sent by New Relic Mobile, 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 in New Relic Insights (available with Mobile Enterprise).
Setting custom attributes will add the key-value pair information at the session level. All default Mobile 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
- iOS: Use
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
statusattribute recording a
failurekey 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 in New Relic Insights (available with Mobile Enterprise) 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:
Create custom interactions
The New Relic Mobile 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.
New Relic Mobile 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.
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:
You can also configure interaction tracing globally:
- Android: Disable entirely with
withInteractionTracing(), or disable only auto-instrumented traces with
- iOS: Disable entirely with
NRFeatureFlag_InteractionTracing(), or disable only auto-instrumented traces with
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 in New Relic Insights (available with Mobile Enterprise) 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 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: