Android SDK API の利用

New Relic Android SDK のバージョン 5.9.0 から、カスタムユーザーIDを設定して、ユーザーセッションをアナリティクスのイベントや属性に関連付けることができます。詳しくは、NewRelic.setUserId メソッドを確認ください。

New Relic Mobile 用の Android SDK API を利用する手順は以下のとおりです。

トレース処理は(トレースのオーバーヘッドが小さくなるよう)最適化されていますが、ある程度のオーバーヘッドはあります。そのため、何百回も呼ばれることが予想されるメソッドを計測するのは避けてください。

SDK の新規インストール

rpm.newrelic.com の指示に従って、New Relic Mobile 用の最新の SDK で、アプリが計測されるようにしてください。

Android 2.2 のサポートが必要な場合は、旧 Android エージェント SDK の手順をご覧ください。

コードの計測

インタラクショントレースに含めるカスタムライブラリやアプリケーションコードがある場合は、以下を実行します。

  1. 以下の Java アノテーションを使います。

    import com.newrelic.agent.android.instrumentation.Trace;
  2. @Trace アノテーションを計測したい各メソッドに追加します。

    @Trace
      public void myHeavyweightMethod() {
      …

New Relic Mobile にどのようなメソッドがトレースされているかを伝えるには、category 属性を使います。

例: MetricCategory.IMAGE として分類された画像処理メソッドの場合:

@Trace(category = MetricCategory.IMAGE)
public void processImageData() {
…

MetricCategory 列挙型には、次のカテゴリがあります。

カテゴリ 説明
VIEW_LOADING サブビュー、コントロール、その他の関連タスクの作成
VIEW_LAYOUT レイアウトのインフレーション、コンポーネントの解決
DATABASE SQLite とその他のファイル I/O
IMAGE 画像読み込みと処理
JSON JSON のパースと生成
NETWORK Web サービスの統合方法、リモートリソースのロード

以下のメソッド(リストされているクラスとそのサブクラスのメソッド)は、すでに New Relic の計測対象です。よって、これらのメソッドに @Trace アノテーションを追加する必要はありません。

クラス メソッド
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
自動計測はエージェントの優れた特徴の一つです。ただし、その計測が邪魔な場合は、メソッドに @SkipTrace を追加すると、エージェントはそのメソッドをコンパイル時の計測対象から外します。

インタラクションの作成

インタラクションの開始点として特定のメソッドを追跡する手順は以下の通りです。

  1. Android 用の SDK API を import します。

    import com.newrelic.agent.android.NewRelic;
  2. インタラクショントレースを開始するには、次のメソッドを呼出します。

    NewRelic.startInteraction(String actionName);

例: ユーザーのトレースを開始するには、Activity にあるボタンを押します。

public class MainActivity extends Activity {
  ...
  @Override
  public boolean onOptionsItemSelected(MenuItem item) {
    switch (item.getItemId()) {
      case R.id.action_refresh:
        NewRelic.startInteraction("RefreshContacts");
   ……
        return true;
      default:
        return super.onOptionsItemSelected(item);
    }
  }
  ...
}

インタラクションの名前付け

New Relic Mobile は意味のある名前でインタラクションをグループ化されない場合があります。たとえば、すべてのアクティビティが単一のアクティビティ名(通常は FragmentActivity)の下にある場合や、インタラクションの名前が非常に一般的な場合などです。New Relic は自動計測の改善に常に邁進しています。また、その他にも、手動でインタラクションの名前を付けることもできます。

onCreate() メソッドの先頭で NewRelic.setInteractionName() を呼び出すことで、計測する各インタラクションに名前を設定できます。手動で名前を付けたインタラクションは、Interactions ページに別々に表示されます。

NewRelic.setInteractionName(String intName)
インタラクションに名前をつける
以下の例では、Activity クラス内で onCreate() メソッドの先頭でNewRelic.setInteractionName() を呼んでいます。

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {

        //Rename the in-flight interaction
        NewRelic.setInteractionName("Display MyCustomInteraction");
    }

    // ... continue methods ...

} 

インタラクションの終了

New Relic Mobile は自動的にインタラクションを終了します。しかし、それよりも早く終了させたい場合は、文字列のインタラクションIDを引数に NewRelic.endInteraction() を呼び出します。(NewRelic.startInteraction() の戻り値として、New Relic Mobile はこのIDを返します)。この呼び出しは、インタラクションがすでに終了している場合は無効となります。

インタラクションを無効にする

New Relic Android SDK のバージョン5.4.0以降、API メソッドを使って、インタラクショントレースを有効/無効にできます。このメソッドは、エージェントを起動する前に呼び出す必要がありますが、その後はいつでも変更できます。

NewRelic.withInteractionTracing(boolean state)
エージェントが起動すると、インタラクショントレースは無効になります。エージェントの起動前に実行済みの1つ以上のアクティビティのインタラクションは、Interactions ページ表示されることがあります。

独自のアプリケーションバージョンの設定

New Relic Android SDK のバージョン 4.244.0 では、API メソッドを使って。独自のアプリケーションバージョンを文字列で設定できます。AndroidManifest.xml または build.gradle で定義されたバージョンを使う代わりに、アプリのバージョンを引数として、withApplicationVersion() メソッドを呼び出します。

NewRelic.withApplicationVersion(String appVersion)

独自のビルドIDを設定

New Relic Android SDK のバージョン5.1.0以降、API メソッドを使って、Crash report ページのアプリケーションバージョンの横に表示されるカスタムビルドIDを設定できます。AndroidManifest.xml で定義された versionCode 文字列の代わりに、カスタムビルドIDを文字列として、引数渡し、withApplicationBuild() メソッドを呼び出ます。

NewRelic.withApplicationBuild(String buildId)
非推奨:: NewRelic.withBuildIdentifier() は、バージョン5.3.0以降、withApplicationBuild() に代わりました。まだこのメソッドを使用することができますが、近い将来、このメソッドは削除されます。

カスタムメトリクスの作成

カスタムメトリック API を使って、任意の数値データと名前付きイベントを記録できます。カスタムメトリクスを使うことで、アプリケーション固有の独自のイベントを追跡できるようになります。

複数の API を使って、さまざまなレベルの詳細情報をカスタムメトリクスに記録できます。カスタムメトリックを作成するには、以下のメソッドを呼出します。

NewRelic.recordMetric(String name, String category)

name パラメータは、New Relic Mobile UI 上に表示されるメトリクスの文字列の名前です。メトリックを最大限に活用するために、分かりやすい名前を指定してください。

カスタムメトリクスに名前を付ける際のガイドラインは次のとおりです。

  • UI の表示に適した大文字と小文字を使用します。メトリック名はそのまま表示されます。
  • メトリック名を大文字にします。
  • / ] [ | * を使用しないでください。
  • マルチバイト文字は使用しないでください。

カスタムメトリックに詳細な情報を指定したい場合は、以下の3つの API メソッドを使います。

NewRelic.recordMetric(String name, String category, double value)

NewRelic.recordMetric(String name, String category, int count, double totalValue, double exclusiveValue)

NewRelic.recordMetric(String name, String category, int count, double totalValue, double exclusiveValue, MetricUnit countUnit, MetricUnit valueUnit)

これらのメソッドで、以下のパラメーターを使って様々な情報を記録できます。

パラメーター 説明
count イベントが発生した回数
totalValue 記録の合計値
exclusiveValue 記録の排他的な値。例えば、合計値が他の場所で測定された測定値を含む場合。そのほかの場所の値を無視したい場合。
countUnit メトリック数の測定単位。PERCENTBYTESSECONDS, BYTES_PER_SECONDOPERATIONS
valueUnit メトリック値の測定単位。PERCENTBYTESSECONDS, BYTES_PER_SECONDOPERATIONS

カスタムメトリクスを表示するには、Insights Metric Explorer からメトリックを検索し、チャートを作成し、Insight ダッシュボードに追加します。

Insights にカスタム属性やカスタムイベントを送信する

名前空間 NewRelicで以下の静的メソッドを使って、カスタム属性やカスタムイベントを New Relic Insights に送信できます。メソッドは、真偽値を結果として返します。成功した場合は true。処理が完了しなかった場合は false を返します。これらのメソッドは、New Relic Android SDK のバージョン5.0.0 以降で使用できます。

SDK は一度に最大64個のユーザー定義属性を格納できます。64を超える属性を格納しようとすると、SDK は false を返します。

カスタム属性名は可能な限りシンプルな形式を使ってください。New Relic では属性名として、空白を含まない1単語を推奨しています。My Custom Attributeよりも、myCustomAttribute の方が適した名前です。

以下は、カスタム属性に名前を付ける際の注意点です。

  • / ] [ | * を使用しないでください。
  • マルチバイト文字は使用しないでください。

カスタム属性やカスタムイベントには、以下のメソッドを使ってください。

setAttribute
メソッド:

public static boolean setAttribute(String name, String value);

指定された文字列の名前と文字列の値を持つ属性を作成します。 setAttribute は、呼び出されるたびに以前の値と型を上書きします。

:

boolean attributeSet = NewRelic.setAttribute("username", "SampleUserName");

メソッド:

public static boolean setAttribute(String name, float value);

指定された文字列の名前と数値で属性を作成します。setAttribute は、呼び出されるたびに以前の値と型を上書きします。

:

boolean attributeSet = NewRelic.setAttribute("rate", 9999.99);
incrementAttribute
メソッド:

public static boolean incrementAttribute(String name);

指定した属性の数を1つ増やします。属性が存在しない場合は、値が 1 の属性を作成します。

:

boolean incremented = NewRelic.incrementAttribute("rate");

メソッド:

public static boolean incrementAttribute(String name, float value) ;

float 値で指定された量だけ、指定した属性のカウントをインクリメントします。

:

boolean incremented = NewRelic.incrementAttribute("rate", 9999.99, false);
removeAttribute
メソッド:

文字列名として指定された属性を削除します。

:

boolean attributeRemoved = NewRelic.removeAttribute("rate");
removeAllAttributes
メソッド:

セッションからすべての属性を削除します。

:

boolean attributesRemoved = NewRelic.removeAllAttributes();
recordEvent
メソッド:

public static boolean recordEvent(String name, Map<<String, Object> eventAttributes);

Insights カスタムイベントを記録します。属性のリストを Map を設定します。

:

Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("attributeName1", "value1");
attributes.put("attributeName1", 2);
boolean eventRecorded = NewRelic.recordEvent("eventName", attributes);
setMaxEventPoolSize
メソッド:

public static void setMaxEventPoolSize(int maxSize);

イベントプールの最大サイズを設定します。限界に達すると、エージェントは次の収穫サイクルで送信されるまで、古いイベントといくつかの新しいイベントを破棄して、着信イベントのサンプリングを開始します。

:

boolean poolSizeSet = NewRelic.setMaxEventPoolSize(1000);
setMaxEventBufferTime
メソッド:

public static void setMaxEventBufferTime(int maxBufferTimeInSec);

エージェントがイベントをメモリに保存する最大時間(単位:秒)を設定します。最も古いイベントがこの時間を超えると、エージェントは収穫サイクルでバッファされたコンテンツを送信します。

:

boolean fiveMinuteLimitSet = NewRelic.setMaxEventBufferTime(600);
currentSessionId
メソッド:

public static String currentSessionId();

現在のセッションのIDを返します。

:

String sessionId = NewRelic.currentSessionId();
setUserId
メソッド:

public static boolean setUserId(String userId);

ユーザーセッションを分析のイベントと属性に関連付けるカスタムユーザーIDを設定します。このメソッドは、エージェントの起動後にいつでも呼び出すことができます。

:

boolean userIdWasSet = NewRelic.setUserId("SampleUserName");

ユーザーID は様々な用途に活用できます。例えば、Crash Analysis ページでは、ユーザーIDを使って、以下のことができます。

  • あるユーザーに固有のクラッシュを見つけることができます。あるユーザーに発生したある特定のクラッシュに焦点を当てることで、問題を迅速に解決することができます。
  • すべてのクラッシュをフィルタリングして、あるユーザー(またはユーザーグループ)のクラシュの発生をクラッシュタイプ別に表示できます。逆に、クラッシュリストをフィルタリングして、各クラッシュタイプの影響を受けるユーザーを表示できます。ユーザーIDをメールアドレスとしている場合は、クラッシュに対処できる解決策があるときに、簡単に知らせることができます。

自分たちのプライバシールールに従って、明示的にユーザーを識別したくない場合でも、この方法はユーザーセグメントをトラッキングする方法として、依然、有効です。有料ユーザーと無料エンドユーザーや登録ユーザーと未登録ユーザーの比較などにも使えます。ユーザーIDを使って、各セグメントで発生したクラッシュの数や種類をフィルタリングしたり、グループ化することで、そのセグメントを軸にして、その層に対して対応することができます。

独自にネットワークリクエストを追跡する

New Relic Mobile API は、ネットワークリクエストとネットワーク障害を追跡するメソッドを提供しています。たとえば、HTTP トランザクションを様々なレベルで記録するには、noticeHttpTransaction メソッド群を使用します。ネットワークリクエストが失敗した場合は、noticeNetworkFailure を使って、障害の詳細を記録できます。

以下の API メソッドを使って、HTTPトランザクションを記録します。

NewRelic.noticeHttpTransaction(String url, String httpMethod, int statusCode, long startTime, long endTime, long bytesSent, long bytesReceived)

NewRelic.noticeHttpTransaction(String url, String httpMethod, int statusCode, long startTime, long endTime, long bytesSent, long bytesReceived, String responseBody)

NewRelic.noticeHttpTransaction(String url, String httpMethod, int statusCode, long startTime, long endTime, long bytesSent, long bytesReceived, String responseBody, Map<String, String> params)

カスタムネットワークリクエスト用のメソッドのパラメータは次のとおりです。

パラメーター 説明
url リクエストの URL
httpMethod リクエストのメソッドの種類。例: POST, GET など。
statusCode HTTP レスポンスのステータスコード。例えば、200は OK
startTime エポック(UNIX時間)からのリクエストの開始時刻(単位: ミリ秒)
endTime エポック(UNIX時間)からのリクエストの終了時刻(単位: ミリ秒)
bytesSent 送信したリクエストのバイト数
bytesReceived 受信したレスポンスのバイト数
responseBody HTTP レスポンスのレスポンスボディ。HTTP トランザクションがエラーの場合は、レスポンスボディは捨てられ、レスポンスボディは HTTP エラーメトリックに含まれます。
params HTTPト ランザクションがエラーの場合は、HTTP エラーメトリックに含まれる追加パラメータ。

ネットワーク障害を記録するには、2つの API メソッドがあります。通常、これらの呼び出しを catch ブロックなどの例外ハンドラに置きます。

NewRelic.noticeNetworkFailure(String url, String httpMethod, long startTime, long endTime, Exception e)

NewRelic.noticeNetworkFailure(String url, String httpMethod, long startTime, long endTime, NetworkFailure failure)

カスタムネットワーク障害メソッドのパラメータは次のとおりです。

パラメーター 説明
url リクエストの URL
httpMethod リクエストのメソッドの種類。例: POST, GET など。
startTime エポック(UNIX時間)からのリクエストの開始時刻(単位: ミリ秒)
endTime エポック(UNIX時間)からのリクエストの終了時刻(単位: ミリ秒)
exception 発生した例外。New Relic Mobile は、一般的な例外を自動的にネットワーク障害タイプに変換します。
failure 発生したネットワーク障害のタイプ。例外をネットワーク障害に自動的に変換できない場合、このメソッドを使って障害を正確に分類できます。値は NetworkFailure 列挙型に定義されています。有効な値は次の通りです。UnknownBadURLTimedOutCannotConnectToHostDNSLookupFailedBadServerResponseSecureConnectionFailed.

手動でクロスアプリケーションを追跡

noticeHttpTransaction コードは、クロスアプリケーショントレース(CAT)を機能させるために必要なヘッダーIDを自動的に付加しません。そのため、モバイルアプリの Map ページHTTP requests ページの Android アプリにアプリケーションリンクは表示されません。

New Relic Android SDK のパブリックメソッドを使って、HTTP リクエストを(New Relic が計測済みの)バックエンドアプリケーションに渡す ID を取得できます。つまり、レスポンスのバックエンドアプリケーションから適切なヘッダーIDが渡され、アプリケーショントレース機能の追跡に必要なすべての情報が提供されるようになります。

NewRelic ID をバックエンドの HTTP リクエストに追加する例を次に示します。conn は外部 HTTP 接続を意味しています。 (注: 追加のインポートが必要であることに注意してください)

import com.newrelic.agent.android.NewRelic;
import com.newrelic.agent.android.Agent; //required for getCrossProcessId()
...
...
 
// New Relic の CAT に必要な crossProcessID を追加する新しいメソッド
public static void setCrossProcessHeader(HttpURLConnection conn) {
    String crossProcessId = Agent.getCrossProcessId(); // X-NewRelic-ID 用のエージェント API の呼び出し
    if (crossProcessId != null) {
        conn.setRequestProperty("X-NewRelic-ID", crossProcessId);
    }
}

バックエンドアプリケーションへのリクエストに適切なヘッダーを追加した後、アプリからのレスポンスを X-Newrelic-App-Data ヘッダーで利用するためにパースしてから、noticeHttpTransaction 呼び出しに文字列として追加する必要があります。以下がその例です。

//NewRelic.noticeHttpTransaction(url, httpMethod, statusCode, startTimeMs, endTimeMs, bytesSent, bytesReceived, responseBody, params, response);
//xNewRelicAppDataHeader は、X-NewRelic-App-Data ヘッダーの値です
NewRelic.noticeHttpTransaction("http://api.newrelic.com", "GET", 200, System.nanoTime(), System.nanoTime(),100 ,100, "Test", new HashMap<String, String>(), xNewRelicAppDataHeader);

関連情報

関連情報は次のとおりです。Interactions ページ (計測したインタラクションを表示)