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

Related pages:

以下のセクションでは、Xamarin SDK を使用してインストゥルメンテーションをカスタマイズする方法について説明します。

エージェントは情報を報告する前にローカルバッファにイベントに関するデータを保存するため、慎重に API を使用することをお勧めします。

コールの追跡

メソッドをインストゥルメント化すると、インストゥルメント化されたメソッドが呼び出される頻度と、実行にかかる時間を確認できます。これを行うには、インストゥルメント化するメソッドの開始時と終了時にコールを追加します。

次の例では、クラス MyClass のコンストラクタで実行されたコードが追跡され、報告されます。独自のコードでは、BeginCall のクラスとメソッドを指定することによってコールの追跡を開始し、その後追跡を完了し、ReportCallEnded を呼び出すことによってデータを報告します。

using AppDynamics.Agent;
...
public class MyClass {
    public MyClass() {
        var tracker = Instrumentation.BeginCall("MyClass", "Constructor");
        // The code placed here will be tracked and reported.
        tracker.ReportCallEnded();
    }
}

C#

イベントの時間

複数のメソッドにまたがるアプリケーション内のイベントの時間を計る必要がある場合があります。これを行うには、イベントの開始時に StartTimerWithName を、続いて終了時に StopTimerWithName を呼び出します。たとえば、ユーザが画面の表示に費やした時間を追跡するためのインストゥルメンテーションは次のようになります。

using AppDynamics.Agent;
...
async private void StartCapturePreview_Click(object sender, RoutedEventArgs e) {
    capturePreview.Source = captureManager;
    Instrumentation.StartTimerWithName("CapturePreview");
    await captureManager.StartPreviewAsync();
}
async private void StopCapturePreview_Click(object sender, RoutedEventArgs e) {
    await captureManager.StopPreviewAsync();
    Instrumentation.StopTimerWithName("CapturePreview");
}

C#

レポートメトリック（Report Metrics）

他のタイプのデータを報告するには、メトリックを使用できます。メトリック名には、英数字とスペースのみを使用します。不正な文字は、ASCII 16 進値に置き換えられます。メトリック値は整数である必要があります。

次のスニペットは、メトリックを報告する方法を示しています。

using AppDynamics.Agent;
...
Instrumentation.ReportMetricWithName("Database Rows", 5123);

C#

HTTP リクエスト

AppDynamics.Agent.HTTPRequestTracker クラスを使用してネットワークリクエストを報告できます。

次に、HTTPRequestTracker を System.Net.Http.HttpClient クラスで使用する例を示します。tracker オブジェクトは、ネットワークリクエストおよびネットワークエラーを同期的にキャプチャして報告します。

using AppDynamics.Agent;
...
public async Task<string> Fetch(Uri uri) {
  var client = new HttpClient();
  // Create AppDynamics Tracker
  var tracker = HTTPRequestTracker.Create(uri);
  // Add AppDynamics Server Correlation Headers
  foreach (var header in ServerCorrelationHeaders.Generate) {
      // Each header could have multiple values
      foreach (var value in header.Value) {
          client.DefaultRequestHeaders.Add(header.Key, value);
      }
  }
  HttpResponseMessage response = null;
  try {
      response = await client.GetAsync(uri);
  } catch (Exception ex) {
      // Capture any network errors.
      tracker.Exception = ex;
      tracker.ReportDone();
      throw ex; //you decide to throw it or not
  }
  if (!response.Equals(null)) {
      // Capture request information such as the 
      // status code, status message, and headers.
      tracker.ResponseCode = (int)response.StatusCode;
      tracker.StatusLine = response.ReasonPhrase;
      tracker.ResponseHeaderFields = response.Headers;
      tracker.ReportDone();
      return await response.Content.ReadAsStringAsync();
   }
   return null;
}

C#

トピックパスを残す

トピックパスを残して関心のあるイベントにマークを付けることができます。たとえば、アプリケーションがクラッシュした場合に、残したトピックパスがクラッシュレポートに表示され、コンテキストを提供できます。また、トピックパスがセッションに表示されるように構成することもできます。

次に、トピックパスを残すためのメソッドの署名を示します。

static void AppDynamics.Agent.Instrumentation.LeaveBreadcrumb(string breadcrumb, BreadcrumbVisibility mode)

C#

トピックパスの可視性を設定するには、モードを使用します。可視性によって、コントローラ UI でのトピックパスの表示場所が定義されます。モードの値は、次のいずれかになります。

BreadcrumbVisibility.CrashesOnly：トピックパスはクラッシュスナップショットにのみ表示されます。
BreadcrumbVisibility.CrashesAndSessions：トピックパスはクラッシュスナップショットとセッションに表示されます。

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

using AppDynamics.Agent;
...
Instrumentation.LeaveBreadcrumb("GetUserInfo", BreadcrumbVisibility.CrashesOnly);

C#

クラッシュレポートおよびセッションでトピックパスを表示するには、次のようにします。

using AppDynamics.Agent;
...
Instrumentation.LeaveBreadcrumb("GetUserInfo", BreadcrumbVisibility.CrashesAndSessions);

C#

エラーと例外のレポート

Instrumentation クラスの reportError メソッドを使用して例外を報告できます。報告された例外は、セッション詳細に表示されます。

また、問題に対して次の重大度レベルの 1 つを設定することもできます。重大度レベルを使用すると、[Code Issues Dashboard] または [Code Issues Analyze] でエラーをフィルタリングできます。

ErrorSeverityLevel.INFO
ErrorSeverityLevel.WARNING
ErrorSeverityLevel.CRITICAL

次の例では、API を使用して考えられる例外を報告し、ファイルへの書き込み時に重大度レベルを ErrorSeverityLevel.CRITICAL（クリティカル）に設定します。

using AppDynamics.Agent;
...
try {
    // possible exception //
}
catch (Exception e){
    Instrumentation.ReportError(exception, ErrorSeverityLevel.CRITICAL);
}

XML

クラッシュとしての例外の報告の無効化

デフォルトでは、Xamarin エージェントが例外をクラッシュとして報告します。ブーリアン型のプロパティ enableExceptionReporting を使用して、クラッシュとしてのすべての例外を有効または無効にできます。デフォルトは次の値です。true.

using AppDynamics.Agent;
...
var config = AppDynamics.Agent.AgentConfiguration.Create(<EUM_APP_KEY>);
AppDynamics.Agent.Instrumentation.enableExceptionReporting = false;
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
...

C#

クラッシュとしての集約例外の報告

Xamarin エージェントを設定して、ブーリアン型のプロパティ EnableAggregateExceptionHandling を true に設定することで、（処理済みおよび未処理の）集約例外をクラッシュとして報告できます。プロパティが false に設定されている場合は、未処理の例外のみが報告されます。デフォルト値は false です。

次のコード例では、Xamarin エージェントを設定して、（処理済みおよび未処理の）集約例外をクラッシュとして報告します。

using AppDynamics.Agent;
...
var config = AppDynamics.Agent.AgentConfiguration.Create(<EUM_APP_KEY>);
AppDynamics.Agent.Instrumentation.EnableAggregateExceptionHandling = true;
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);
...

C#

プログラムによるセッションの制御

デフォルトでは、ユーザが非アクティブになってからモバイルセッションが終了します。たとえば、ユーザがアプリケーションを開くと、セッションは開始され、ユーザが設定した期間にアプリケーションを使用しなくなった後にのみ終了します。ユーザがアプリケーションの再使用を開始すると、新しいセッションが開始されます。

ただし、セッションの期間を定義するのに非アクティブな期間を設定する代わりに、次の API を使用して、セッションの開始と終了をプログラムで制御できます。

static void AppDynamics.Agent.Instrumentation.StartNextSession()

C#

メソッド StartNextSession を呼び出すと、現在のセッションが終了し、新しいセッションが開始されます。API を使用すると、セッションを定義してフレーム化することができます。これにより、ビジネス目標と予想されるユーザフローをより厳密に合わせることができます。たとえば、API を使用して、製品の購入を追跡するセッションを定義したり、新しいユーザを登録したりすることができます。

この API を過剰に使用すると、セッションが調整されます（過剰使用は Xamarin エージェントごとに 1 分あたり 10 コールを超えた場合になりますが、変更される可能性があります）。API を使用しない場合、セッションは、ユーザが非アクティブになった後、デフォルトの終了にフォールバックします。

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

次の例では、商品の購入時に現在のセッションが終了し、新しいセッションが開始されます。

using AppDynamics.Agent;
...
public async Task BuySaleItemAsync(SaleItem item)
{
    try 
    {
        bool buySucceeded = await this.MobileService.InvokeApiAsync<SaleItem, bool>("buy", item);
        if (buySucceeded)
        {
            await UserDialogs.Instance.AlertAsync("Thanks for buying this item");
            Instrumentation.StartNextSession();
        }
    }
    catch (Exception e)
    {
        Debug.WriteLine(@"Unexpected error {0}", e.Message);
    }
}

C#

セッションフレームの開始と終了

ISessionFrame API を使用して、セッションアクティビティに表示されるセッションフレームを作成できます。セッションフレームは、セッション中にユーザが実行している内容のコンテキストを提供します。この API を使用すると、ユーザ画面の命名方法が向上し、ビジネスコンテキスト内のユーザフローを記録できます。

使用例

次に、ISessionFrame API の一般的な使用例を示します。

1 つの画面で複数の関数を実行し、個々の関数をより詳細に追跡する必要があります。
ユーザフローは、複数の画面またはユーザのインタラクションに及びます。たとえば、API を使用してセッションフレーム「Login」、「Product Selection」、および「Purchase」を作成して、ユーザが購入のためにフローを記録することができます。
ユーザの操作に基づいて動的情報をキャプチャし、オーダー ID などのセッションフレームに名前を付けることができます。

ISessionFrame API

次の表に、セッションフレームで使用できる 2 つのメソッドと 1 つのプロパティを示します。つまり、StartSessionFrame を使用してセッションフレームを開始してから、返された ISessionFrame オブジェクトを使用してセッションフレームの名前を変更し、終了します。

クラス	メソッド/プロパティ	説明
`Instrument`	方式： `static ISessionFrame StartSessionFrame(string sessionFrameName)` C#	セッションフレームを開始して名前を付けるには、これを使用します。セッションフレームに命名すると、Sessions Details ダイアログ内のフレームを簡単に特定して追跡することができます。
`ISessionFrame`	プロパティ: `string Name` C#	セッションフレーム名の名前を変更します。更新されたセッションフレーム名を、`StartSessionFrame` から返された `ISessionFrame` オブジェクトのこのプロパティに割り当てます。
`ISessionFrame`	方式： `static void End()` C#	セッションフレームを終了します。 `StartSessionFrame` から返された `ISessionFrame` オブジェクトからこのメソッドを呼び出すことができます。

セッションフレームの例

次の例では、ISessionFrame API を使用し、チェックアウトプロセス中のユーザアクティビティを追跡します。

using AppDynamics.Agent;
...
 
namespace ShoppingApp {
    public partial class ShoppingCart : ContentPage {
        private ISessionFrame sessionFrame;
        private string orderId;
        ...
        void checkoutCartButtonClicked(object sender, EventArgs e) {
            // The checkout starts when the user clicks the checkout button.
            // This may be after they have updated quantities of items in their cart, etc.
            sessionFrame = Instrumentation.StartSessionFrame("Checkout");
        }
        void confirmOrderButtonClicked(object sender, EventArgs e) {
            // Once they have confirmed payment info and shipping information, and they
            // are clicking the "Confirm" button to start the backend process of checking out,
            // we may know more information about the order itself, such as an order ID.
            sessionFrame.Name = $"Checkout: Order ID {this.orderId}";
        }
        void processOrderCompleted(object sender, EventArgs e) {
            // Once the order is processed, the user is done "checking out" so we end
            // the session frame.
            sessionFrame.End();
        }
        void checkoutCancelled(object sender, EventArgs e) {
            // If they cancel or go back, you'll want to end the session frame also, or else
            // it will be left open and appear to have never ended.
            sessionFrame.End();
        }
    }
}

CPP

ユーザデータの追加

重要なイベントや情報を記録するために、文字列のキー/値ペアを設定できます。ユーザデータを設定するためのメソッドの署名を以下に示します。

static void AppDynamics.Agent.Instrumentation.SetUserData(string key, string value)

C#

たとえば、ユーザのログインのためのメソッドが呼び出されたときにユーザ ID をログに記録することができます。

using AppDynamics.Agent;
...
void LogInUser(UserCredentials) {
   // Log in user
   ...
   // Set user data with the user name.
   Instrumentation.SetUserData("user_id", UserCredentials.ID);
}

C#

この情報は、[Network Request Analyze] で確認でき、取得可能なクラッシュスナップショットに追加されます。キーと値はそれぞれ 2048 文字に制限されています。

また、次のメソッドを使用して、他のタイプ（long、boolean、double、DateTime）の値をユーザデータに設定することもできます。

ユーザデータを削除するには、次のメソッドを使用します。

ログレベルの設定（オプション）

クラス AgentConfiguration の一部として、設定 LoggingLevel を使用してログレベルを設定できます。

LoggingLevel は、次の表にリストされているレベルのいずれかに設定できます。

レベル	説明
`Off`	エージェントはメッセージをまったく出力しません。
`Error`	エラーと最初のバナーのみを表示します。これはデフォルトです。
`Warn`	警告レベル以上のメッセージ。
`Info`	情報レベル以上のメッセージ。開発者にとって役立つ場合があります。
`Debug`	デバッグレベル以上のメッセージ。サポート担当者と開発者にとって役立ちます。
`Verbose`	詳細レベル以上のメッセージ。詳細ロギングは、トラブルシューティングにのみ使用します。実稼働環境では必ず無効にしてください。
`All`	すべてのメッセージ

次に例を示します。

var config = AppDynamics.Agent.AgentConfiguration.Create("<#Your App Key#>");
config.LoggingLevel = AppDynamics.Agent.LoggingLevel.All;
AppDynamics.Agent.Instrumentation.InitWithConfiguration(config);

C#

Xamarin SDK のドキュメント

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

4.5.6 以降、Xamarin エージェントは、コントローラと他の AppDynamics プラットフォームコンポーネントとは異なるバージョン番号から始まります。すべての Xamarin エージェント機能を完全にサポートするために必要なコントローラおよび EUM Server の最小バージョンについては、『モバイルエージェントバージョンおよび展開サポートマトリックス』を参照してください。