Starting with version 5.9.0 of the New Relic Android agent, you can set a custom user identifier value to associate user sessions with analytics events and attributes. For more information, see the NewRelic.setUserId
method.
New Relic Mobile's Android agent provides an SDK API to set up custom instrumentation for monitoring your application. The API gives you the ability to:
- Instrument your own code.
- Create, name, and end interaction traces from events in your mobile app.
- Record custom metrics.
- Send custom attributes and events to New Relic Insights.
- Track networking from libraries not supported automatically.
Install the SDK
Before using the Android SDK API:
- Review the Android SDK API release notes to ensure you have your app instrumented with a current SDK for New Relic Mobile.
- Follow the Add a new app instructions in rpm.newrelic.com/mobile.
For more information, see the detailed Android installation and configuration procedures. If you need to support Android 2.2, see the legacy Android agent SDK procedures.
Instrument your code
Tracing is heavily optimized, but it does impose a performance overhead. Avoid instrumenting methods that are expected to be called hundreds of times.
If you have custom libraries or application code that you want to include in interaction traces:
-
Use the following Java annotation:
import com.newrelic.agent.android.instrumentation.Trace;
-
Add the
@Trace
annotation to the methods you want to instrument:@Trace public void myHeavyweightMethod() { …
- To tell New Relic Mobile what kind of method is being traced, use the optional
category
attribute.
- Automatically instrumented methods
-
Automatic instrumentation is one of the agent's more convenient features. However, if it interferes with the method being traced, add
@SkipTrace
to the method, and the agent will skip it during compile time instrumentation.Classes Methods Activity
onCreate
onCreateView
AsyncTask
execute
executeOnExecutor
BitmapFactory
decodeFile
decodeResourceStream
decodeResource
decodeByteArray
decodeStream
decodeFileDescriptor
decodeResourceStream
SQLiteDatabase
query
queryWithFactory
rawQuery
rawQueryWithFactory
insert
insertOrThrow
insertWithOnConflict
replace
replaceOrThrow
delete
update
updateWithOnConflict
execSql
GSON
toJson
fromJson
JSONObject
<init>
toString
JSONArray
<init>
toString
- Category attribute example
-
The category can be a custom name, or it can be one of the predefined
MetricCategory
enums (listed below). Here is an example of instrumenting an image processing method using the predefinedIMAGE
category:@Trace(category = MetricCategory.IMAGE) public void processImageData() { …
Available
MetricCategory
enums include:MetricCategory Description VIEW_LOADING
Creating sub views, controls, and other related tasks VIEW_LAYOUT
Inflation of layouts, resolving components DATABASE
SQLite and other file I/O IMAGE
Image loading and processing JSON
JSON parsing or creation NETWORK
Web service integration methods, remote resource loading
Use the API methods
The following table lists all the New Relic Android SDK API calls, ordered by common use cases.
If you want to... | Do this |
---|---|
Track app activity that may be helpful for troubleshooting crashes | See recordBreadcrumb . |
Track a method as an interaction | See startInteraction . |
Name or rename an interaction | See setInteractionName . |
End an interaction | See endInteraction . |
Disable or enable all interactions | See withInteractionTracing . |
Set an app version associated with an interaction | See withApplicationVersion . |
Set custom build ID | See withApplicationBuild . |
Create custom metrics | See recordMetric . |
Send custom attributes and events to Insights |
There are several ways to add custom attributes and events. For more about which would be the best method to use and why, see Add custom data.
|
Track custom network requests and failures |
Use these methods:
|
Record a handled exception as an event, including context | See recordHandledException() . |
Manual cross application tracing
The noticeHttpTransaction
code does not automatically append the appropriate header ID value needed to get cross application tracing to work. This is why you will not see the application link in your Android app on New Relic's Map page for mobile apps or on the HTTP requests page.
You can use a public method in the New Relic Android SDK to get the appropriate ID to pass along with your HTTP request to your back-end application, as long as it is already instrumented by New Relic. The appropriate header ID will be passed from the back-end application in the response, providing everything needed for cross application tracing to function.
- Cross application tracing example
-
This example adds the
NewRelic-ID
to the back-end HTTP request, withconn
as the external HTTP connection. (Notice the additional import.)import com.newrelic.agent.android.NewRelic; import com.newrelic.agent.android.Agent; //required for getCrossProcessId() ... ... //new method for appending the crossProcessID necessary for CAT in New Relic public static void setCrossProcessHeader(HttpURLConnection conn) { String crossProcessId = Agent.getCrossProcessId(); // API call into the agent for the X-NewRelic-ID if (crossProcessId != null) { conn.setRequestProperty("X-NewRelic-ID", crossProcessId); } }
After adding the appropriate header to the request to the back-end app, the response from the app needs to be parsed for the
X-Newrelic-App-Data
header, and then added to thenoticeHttpTransaction
call as a string. For example://NewRelic.noticeHttpTransaction(url, httpMethod, statusCode, startTimeMs, endTimeMs, bytesSent, bytesReceived, responseBody, params, response); //Where xNewRelicAppDataHeader is the value of the X-NewRelic-App-Data header NewRelic.noticeHttpTransaction("http://api.newrelic.com", "GET", 200, System.nanoTime(), System.nanoTime(),100 ,100, "Test", new HashMap<String, String>(), xNewRelicAppDataHeader);