Android インストゥルメンテーションのカスタマイズ

情報ポイント

情報ポイントを使用すると、独自のコードがどのように実行されているかを追跡できます。メソッドが呼び出される頻度、実行にかかる時間、および例外がスローされたかどうかを確認できます。情報ポイントを設定する最も簡単な方法は、@InfoPoint 注釈を使用することです。例：

@InfoPoint
public void infoPointMethod(String arg1, int arg2, long value) {
System.out.println("Executing infoPointMethod!");
}

CallTracker インターフェイスを使用して手動で実行することもできます。たとえば、downloadImage メソッドに関する情報を収集するには、次のようなコードを使用できます。

private void downloadImage(URL url) {
CallTracker tracker =
Instrumentation.beginCall("com.example.android.awesomeapp.ImageDownloader", "downloadImage")
.withArguments(url);
try {
//download image.
tracker.reportCallEnded()
} catch(Exception e) {
//handle exception thrown
tracker.reportCallEndedWithException(e);
}
}

この情報は、コントローラ UI の [カスタムデータ（Custom Data）] ビューに表示されます。

カスタムタイマー

カスタムタイマーでは、startTimer と stopTimer を使用して、複数のメソッドにまたがる場合でも、コード内の任意のイベントシーケンスの時間を測定できます。

public class MyActivity extends Activity {
@Override
protected void onStart(){
Instrumentation.startTimer("Time Spent on MyActivity");
//your code here.
}
@Override
protected void onStop(){
Instrumentation.stopTimer("Time Spent on MyActivity");
//your code here.
}
}

メソッド startTimer(String) および stopTime(String) はさまざまなスレッドから呼び出すことができます。同じ名前値を使用して startTimer を再度呼び出すと、名前付きタイマーがリセットされます。

この情報は、コントローラ UI の [カスタムデータ（Custom Data）] ビューに表示されます。

Custom Metrics

任意の整数ベースのデータを Android エージェントに渡すことができます。reportMetric コールの最初のパラメータは、メトリックをコントローラ UI に表示する場合の名前です。メトリック名には、英数字とスペースのみを使用します。不正な文字は、ASCII 16 進値に置き換えられます。

たとえば、ユーザが UI のチェックアウトボタンをクリックした回数を追跡するには、次のようなコードを使用できます。

findViewById(R.id.checkout_button).setOnClickListener(new View.OnClickListener(){
@Override
public void onClick(View view){
//run your checkout routine.
Instrumentation.reportMetric("Checkout Count", 1);
}
});

この情報は、コントローラ UI の [カスタムデータ（Custom Data）] ビューに表示されます。

Custom User Data

setUserData(key, value, success, error) メソッドで役立つ任意の文字列キー/値のペアを設定し、後で削除できます。

これが設定されると、アプリケーションの現在の実行の残りについて、ユーザーデータは、ネットワークリクエスト、セッション、またはクラッシュのインストゥルメンテーションとともに引き続き送信されます。以前に設定されたユーザーデータはキーごとに削除できます。または、clearAllUserData を使用して、すべてのキーの以前に設定されたユーザーデータを一度に削除できます。

パラメータ

次の表で、パラメータについて説明します。

例

次のコード例は、SDK API を使用してユーザーデータを設定する方法を示しています。

void onUserLoggedIn(String userid) {
Instrumentation.setUserData("User ID", userid);
...
}

この情報は、[ネットワークリクエストの分析（Network Request Analyze）] で確認でき、クラッシュスナップショットに追加されます。キーと値はそれぞれ 2048 文字に制限されています。

また、次のメソッドを使用して、他のデータ型（Long、Boolean、Double、Date）の値を含むユーザデータを設定することもできます。

トピックパス(パンくずリスト)

トピックパスを使用すると、ユーザエクスペリエンスのコンテキストでクラッシュの場所を特定できます。一連のイベントをキャプチャする場合は、トピックパスを設定します。その後のある時点でアプリケーションがクラッシュした場合、トピックパスはクラッシュレポートとともに表示されます。

トピックパスを残すには、次の 2 つの方法があります。

• クラッシュレポートのみ
• モーダル

クラッシュレポートのみ

次のメソッドを使用すると、トピックパスがクラッシュレポートのみで報告されます。

public static void leaveBreadcrumb(java.lang.String breadcrumb)

モーダル

次のメソッドを使用すると、トピックパスが報告される場所を微調整（クラッシュレポートのみ、またはクラッシュレポートとセッションを選択）できます。

public static void leaveBreadcrumb(java.lang.String breadcrumb, int mode)

モードは次のいずれかです。

• CRASHES_ONLY
• CRASHES_AND_SESSIONS

breadcrumb が 2048 文字を超えている場合は、切り捨てられます。空の場合、トピック パス（パンくずリスト）は記録されません。各クラッシュレポートには、最近の 99 件のトピックパスが表示されます。

shutdownAgent

shutdownAgent コールはコレクタへの発信データを停止し、デバイスにデータを保持しません。

Instrumentation.shutdownAgent();

• このコールは、エージェントからのトラフィックのみを停止します。
• エージェントが初期化されると、コールは削除できず、ライセンスが消費されます。
• この状態をデバイスで永続的にする場合は、UserDefaults にコードを追加して状態を保存し、そのフラグを使用してコード内のエージェントを条件付きで初期化します。

restartAgent

エージェントを再度有効にして shutdownAgent を元に戻すには、restartAgent を使用します。

Instrumentation.restartAgent();

• このコールは、同様にリモートでエージェントをシャットダウンできるサーバ側のコールにも対応します。
• コールは、アプリケーションの実行中にのみ有効です。
• エージェントがリモートで無効になっている場合、コールは無視されます。
• コールがメモリから削除され、アプリケーションが再起動されるか、デバイスが再起動されると、エージェントは通常どおり初期化されます。

ハイブリッドサポートのランタイム設定

次のコード例では、JavaScript エージェントのインジェクションを無効にしています。クライアントがこのフラグに false を受け取ると、JavaScript エージェントは無効になります。そのため、WebView はインストルメント化されず、Ajax リクエストはモニターされません。

Instrumentation.start(
AgentConfiguration.builder()
.withAppKey(getString(R.string.app_key))
.withContext(applicationContext)
.withJSAgentInjectionEnabled(false)
.build())

インジェクションは、新しい WKWebView の作成時に発生します。このため、このフラグが false に設定されているときに WKWebView が作成された場合、その特定の WKWebView は、その後フラグが true に設定されてもインストルメント化されません。

Ajax コールの収集およびレポートは、デフォルトでは無効になっています。Ajax コールのインジェクションおよび収集とレポートを有効にするには、次に示すようにインストルメンテーションの構成でメソッド jsAgentEnabled に true を渡します。

Instrumentation.start(
AgentConfiguration.builder()
.withAppKey(getString(R.string.app_key))
.withContext(applicationContext)
.withJSAgentAjaxEnabled(true)
.build())

プログラムによって制御されるセッションの例

次のコード例では、現在のセッションが終了し、チェックアウトが行われると新しいセッションが開始されます。

public void checkoutCart(){
if (currentCartItems!=null && currentCartItems.size()>0){
CheckoutTask checkoutReq = new CheckoutTask();
checkoutReq.execute(getEndpoint() + "cart/co");
currentCartItemsMap.clear();
convertItemsMaptoList();
Instrumentation.startNextSession();
} else {
displayToast("There are no items in the cart");
}
}

構文

詳細については、最新の Java ドキュメントを参照してください。

Instrumentation.start(AgentConfiguration.builder()
.withAppKey("<EUM_APP_KEY>")
.withContext(getApplicationContext())
.withCollectorURL(collectorURL*) // The URL of the EUM Server(on-prem)
.withCompileTimeInstrumentationCheck(true) // Set to false if you are using features of the SDK only, like custom HTTP support, but not to instrument your app.
.withLoggingEnabled(true)//set default INFO logging. Tagged "AppDynamics".
.withApplicationName(applicationName)//set a custom app name
.withExcludedUrlPatterns(excludedUrlPatterns) // Set excluded url regex patterns for http tracking
.withCollectorChannelFactory(collectorChannelFactory()) // The custom HTTP implementation to use
.build());

EUM サーバーの URL のリストについては、「Splunk AppDynamics オンプレミス ドメインと IP 範囲」を参照してください。

カスタム HTTP ライブラリを使用するようにエージェントを設定する

Android エージェントは、ビーコンを配信するために HTTP を使用します。エージェントがカスタム HTTP ライブラリを使用してビーコンを配信する場合は、次の手順を実行します。

1. 次の抽象クラスを拡張するクラスを実装します。

   CODECopy

   public abstract class CollectorChannel { private URL url; private int connectTimeout; private int readTimeout; private Map<String, List<String>> requestProperties = new HashMap<String, List<String>>(); private String requestMethod; public void setURL(URL url) { this.url = url; } public URL getURL() { return url; } public void setConnectTimeout(int connectTimeout) { this.connectTimeout = connectTimeout; } public int getConnectTimeout() { return connectTimeout; } public void setReadTimeout(int readTimeout) { this.readTimeout = readTimeout; } public int getReadTimeout() { return readTimeout; } public void addRequestProperty(String property, String value) { if (!requestProperties.containsKey(property)) { requestProperties.put(property, new ArrayList<String>()); } requestProperties.get(property).add(value); } public Map<String, List<String>> getRequestProperties() { return Collections.unmodifiableMap(requestProperties); } public void setRequestMethod(String requestMethod) { this.requestMethod = requestMethod; } public String getRequestMethod() { return requestMethod; } public abstract OutputStream getOutputStream() throws IOException; public abstract InputStream getInputStream() throws IOException; public abstract int getResponseCode() throws IOException; public abstract Map<String,List<String>> getHeaderFields() throws IOException; }

   public abstract class CollectorChannel {
   private URL url;
   private int connectTimeout;
   private int readTimeout;
   private Map<String, List<String>> requestProperties = new HashMap<String, List<String>>();
   private String requestMethod;
   public void setURL(URL url) {
   this.url = url;
   }
   public URL getURL() {
   return url;
   }
   public void setConnectTimeout(int connectTimeout) {
   this.connectTimeout = connectTimeout;
   }
   public int getConnectTimeout() {
   return connectTimeout;
   }
   public void setReadTimeout(int readTimeout) {
   this.readTimeout = readTimeout;
   }
   public int getReadTimeout() {
   return readTimeout;
   }
   public void addRequestProperty(String property, String value) {
   if (!requestProperties.containsKey(property)) {
   requestProperties.put(property, new ArrayList<String>());
   }
   requestProperties.get(property).add(value);
   }
   public Map<String, List<String>> getRequestProperties() {
   return Collections.unmodifiableMap(requestProperties);
   }
   public void setRequestMethod(String requestMethod) {
   this.requestMethod = requestMethod;
   }
   public String getRequestMethod() {
   return requestMethod;
   }
   public abstract OutputStream getOutputStream() throws IOException;
   public abstract InputStream getInputStream() throws IOException;
   public abstract int getResponseCode() throws IOException;
   public abstract Map<String,List<String>> getHeaderFields() throws IOException;
   }

   このインターフェイスは、おおむね HttpURLConnection に基づいています。

2. CollectorChannelFactory インターフェイスのバージョンを実装します。

   PYTHONCopy

   public interface CollectorChannelFactory { /** * Returns a new instance of CollectorChannel. * * If you want to supply a custom CollectorChannel, implement this interface, and return * an instance of your concrete implementation of CollectorChannel from this method. */ public CollectorChannel newCollectorChannel(); }

   public interface CollectorChannelFactory {
   /**
   * Returns a new instance of CollectorChannel.
   *
   * If you want to supply a custom CollectorChannel, implement this interface, and return
   * an instance of your concrete implementation of CollectorChannel from this method.
   */
   public CollectorChannel newCollectorChannel();
   }

   newCollectorChannel の実装は、CollectorChannel の実装の新しいインスタンスを返す必要があります。

3. CollectorChannelFactory を AgentConfiguration オブジェクトに渡します。

セキュリティおよびプライバシー上の懸念点

インタラクション キャプチャ モードは、セキュリティとプライバシー上の理由でデフォルトでは無効になっています。これは、ユーザインタラクションに機密情報が含まれている可能性があるためです。UI インタラクションとスクリーンショットのキャプチャの両方を有効にすると、このような潜在的なセキュリティとプライバシー上の問題が複合化する場合があります。

ユーザ インタラクション キャプチャ モードの有効化

ユーザーインタラクションのキャプチャモードを有効にするには、AgentConfiguration オブジェクトからメソッド withInteractionCaptureMode() にキャプチャモードを渡します。次のインストゥルメンテーション コードの例では、サポート対象のすべてのタイプのユーザインタラクションをキャプチャするように Android エージェントを設定します。

Instrumentation.start(AgentConfiguration.builder()
.withAppKey("<EUM_APP_KEY>")
.withContext(getApplicationContext())
.withInteractionCaptureMode(InteractionCaptureMode.All)
.build());

また、1 つのタイプのユーザインタラクションのみをキャプチャするように Android エージェントを設定することもできます。

Instrumentation.start(AgentConfiguration.builder()
.withAppKey("<EUM_APP_KEY>")
.withContext(getApplicationContext())
.withInteractionCaptureMode(InteractionCaptureMode.ButtonPressed)
.build());

スクリーンショットの無効化

コントローラ UI からまたは Android SDK を使用すると、スクリーンショットを無効にすることができます。Android SDK を使用してスクリーンショットを無効化するには、AgentConfiguration クラスからメソッド withScreenshotsEnabled(false) を使用します。

Instrumentation.start(AgentConfiguration.builder()
.withAppKey("<EUM_APP_KEY>")
.withContext(getApplicationContext())
.withScreenshotsEnabled(false)
.build());
}

Android SDK のドキュメント

SDK API の完全なマニュアルについては、次に示す最新の Java ドキュメントまたは以前のバージョンを参照してください。