Android SDK API guide

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:

1. Review the Android SDK API release notes to ensure you have your app instrumented with a current SDK for New Relic Mobile.
2. 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

If you have custom libraries or application code that you want to include in interaction traces:

1. Use the following Java annotation:

   import com.newrelic.agent.android.instrumentation.Trace;

2. Add the @Trace annotation to the methods you want to instrument:

   @Trace
     public void myHeavyweightMethod() {
     …

3. 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 predefined IMAGE 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.

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, with conn 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 the noticeHttpTransaction 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);

For more help