Flutter モニタリング API

特定のアクションが追跡されないのを防ぐため、以下のコマンドを使用して、アプリの状態クラスの Instana を initState() できるだけ早い段階で初期化してください：

static Future<void> setup({@required String key, @required String reportingUrl}) async
 

現在、Dart SDK（ 2.12.0 以降）および Flutter （ 1.20.0 以降）の全バージョンがサポートされています。

データ収集は、実行時にいつでも有効にすることができます。 データ収集を有効にせずに ` Instana.setupAPI ` を呼び出した場合、その後データ収集を有効にすると、データ収集の開始が遅延します（たとえば、ユーザーの同意を得た後など）。

Instana エージェント（Android-agentおよび iOSAgent ）のすべてのインターフェースは、 Future非同期の値を返します。 エラーは、 PlatformException 型の例外としてラップされます。

フューチャーズの一般的なエラー処理手法 に従って、発生する可能性のあるエラーをログに記録することをお勧めします。

例:

InstanaAgent.setup(key: 'KEY', reportingUrl: 'REPORTING_URL')
    .catchError((e) =>
            log("Captured PlatformException during Instana setup: $e")
        );
 

同様に、非同期関数では次のようになります。

try {
  var result = await InstanaAgent.setup(key: 'KEY', reportingUrl: 'REPORTING_URL');
} catch (e) {
  log("Captured PlatformException during Instana setup: $e");
}
 

各 Instana エージェント（Android-agentおよび iOSAgent ）のインスタンスには一意のセッション識別子が割り当てられており、これをアプリ内で他の目的に利用することができます。

static Future<String> getSessionID() async
 

HTTP セッションは、 Flutter を使用して手動でキャプチャする必要があります。 詳しくは、各プラットフォームに固有の資料を参照してください。

static Future<Marker> startCapture({@required String url, @required String method, String viewName}) async
 

レスポンスの処理が完了したら、レスポンスサイズと HTTP レスポンスステータスコードを. Markerに設定できます。

応答の詳細を設定した後、以下のコマンドに示すように、 Marker で finish を呼び出してキャプチャーをファイナライズする必要があります。

marker.finish();
 

以下のコマンドを使用して、保留中の Marker を取り消すこともできます。

marker.cancel();
 

Instana は、モバイル・アプリケーションの洞察を論理ビューによってセグメント化することができます。 これを行うには、 InstanaAgent.setView(String) メソッドを使用してビュー名を設定します。 その後、ビューは、 setView を再度呼び出したときにビューが変更されるまで、すべてのモニター対象ビーコンに関連付けられます。

クラス ( WebViewActivityなど) などの技術名や総称名の代わりに、読み取り可能な名前 ( product detail page や payment selection など) を使用してビューを定義すると、コードベースに関する深い知識がなくても、チーム・メンバーは提供された洞察を理解することができます。

static Future<void> setView(String name) async
 

Instana に送信されるデータに、必要に応じてユーザー固有の情報を含めることができます。 この情報を使用して、以下のようなより多くの機能をアンロックすることができます。

• エラーの影響を受けるユーザーの数を計算する
• 特定のユーザーのデータをフィルターに掛ける
• ビューの変更または HTTP リクエストを発行したユーザーを確認する

デフォルトでは、Instana はユーザーが識別可能な情報をビーコンに関連付けません。

ユーザーを固有の状態に保つために、ユーザー ID を使用してユーザーを識別します。 Instana において、ユーザー ID は、特定のメトリクスの計算にのみ使用される透過的な String 識別子です。 より多くのフィルターにアクセスしたり、ユーザー情報をより快適に表示したりするために、userName と userEmail を使用することもできます。

匿名ユーザーを処理しているためにユーザー ID にアクセスできない場合は、代わりにセッション ID を使用することもできます。 セッション ID は、データをフィルタリングするためのユーザー ID ほど有用ではありませんが、影響を受けるユーザー・メトリックまたは固有のユーザー・メトリックを計算するための良い指標となります。 認証済みユーザーと非認証ユーザーを明確に区別するには、 Anonymous などのユーザー名を設定します。 セッション ID は、(使用するフレームワークまたはプラットフォームに応じて) 機密データにすることができます。 アクセス権を付与する可能性のあるデータが Instana に送信されるのを防ぐため、セッションIDのハッシュ化を検討してください。

static Future<void> setUserID(String userID) async
static Future<void> setUserName(String name) async
static Future<void> setUserEmail(String email) async
 

任意のデータを、 Instana に送信されるすべてのデータに、必要に応じて添付することができます。 メタデータを使用して、UI 構成値、設定、機能フラグ、および分析に役立つ可能性のある追加コンテキストを追跡することを検討してください。

static Future<void> setMeta({@required String key, @required String value}) async
 

カスタムイベントを使用すると、標準外のアクティビティ、重要なインタラクション、およびカスタムタイミングに関するレポートを Instana に送信できます。 これらのイベントのレポートは、キャッチされていないエラー (パンくずリスト) を分析し、より多くのパフォーマンス・メトリックを追跡する場合に役立ちます。

static Future<void> reportEvent({@required String name, EventOptions options}) async
 

必要に応じて、 Instana エージェントは、追跡対象となるすべてのリクエストまたはレスポンスの HTTP ヘッダーを取得することができます。

どのヘッダーをキャプチャーするかを決定するために、正規表現パターンのリストを定義できます。

要求とその応答の両方に同じヘッダー名が存在する場合は、応答のヘッダー値のみが保持されます。

static Future<void> setCaptureHeaders({@required List<String> regex}) async
 

収集された URL の照会パラメーターに機密データが含まれている可能性があります。 そのため、 Instana エージェントでは、値を非表示にする必要があるクエリパラメータのキーに対して、正規表現パターンの指定をサポートしています。 編集する必要がある値は、ストリング <redacted>で置き換えられます。 この編集処理は、 Instana エージェントが Instana バックエンドに報告を行う前に、同エージェント内で実行されます。 したがって、シークレットは処理のために Instana バックエンドに送信されず、 Instana のUIで分析したり、 Instana API を使用して取得したりすることはできません。

デフォルトでは、 Instana エージェントには、キー「password」、「key」、「secret」のクエリパラメータ値を自動的にマスキングするための3つの正規表現パターンが設定されています。

static Future<void> redactHTTPQuery({@required List<String> regex}) async
 

デフォルトでは HTTP のモニタリングは無効になっていますが、 iOS プラットフォーム内（ Swift またはObjective- C 言語）およびAndroidプラットフォーム内（ Kotlin または Java 言語）で行われる HTTP の呼び出しをキャプチャすることができます。

HTTP Dart言語で作成されたセッションは自動的にキャプチャされます。 以下の例に示すように、 HttpOverrides.global プロパティーを設定します。

低速送信モード機能は、デフォルトでは無効になっています。 必要に応じて、この機能を有効にすることができます。

デフォルトでは、ビーコンの送信に失敗した場合、 Instana エージェントは送信が成功するまでビーコンの再送信を試みます。 ビーコンの再送信は、一部のセルラー・ネットワークではうまく機能しません。 「低速送信モード」機能を有効にすると、ビーコンの送信間隔は、 パラメータ slowSendIntervalMillis に割り当てられた時間値に変更されます。 各ビーコン送信は、バッチ（1バッチあたり最大100個のビーコン）ではなく、1つのビーコンのみで構成されます。 Instana エージェントは、1つのビーコンが正常に送信されるまで、低速送信モードを維持します。

の有効な時間範囲は slowSendIntervalMillis 2～3600 秒です。

デフォルトでは、ユーザー・セッションは追跡され、ID はランダムに生成された Universally Unique Identifier (UUID) です。 この ID は、アプリのインストール中は変更されません。 パラメータ usiRefreshTimeIntervalInHrs を使用することで、ユーザーセッションIDの有効期限を設定できます。

以下のパラメーター値は、ユーザー・セッション ID の状況を示します。

• 負の数値: この値は、ユーザー・セッション ID の有効期限が切れないことを示します。 デフォルト値は -1 です。

• 正数: この値は、設定された時間が経過した後にユーザー・セッション ID がリフレッシュされることを意味します。つまり、新しい UUID が生成されて使用されます。

• ゼロ: この値 0.0 は、ユーザー・セッション ID が使用不可であることを意味します。

アプリケーションのナビゲーション戦略に応じて、 Instana にオブザーバーまたは go-routers を指定することで、スクリーン名を自動的に取得できます。

アプリケーションの基本UIがMaterialApp,CupertinoApp,または同様の基本ウィジェットには、navigatorObserversを追加することができますInstanaScreenNameObserver()オブザーバーのリストに追加すると、スクリーン名が自動的にキャプチャされ、ナビゲーション トラッキングが開始され、指定されたパスからスクリーン名が収集されます。

InstanaScreenNameObserver()高度なスクリーン名をキャプチャするための 3 つのパラメータをサポートします。 あなたが提供するbuildContextパラメータでは、ルート名が指定されていない場合、画面名はウィジェット、ウィジェットのタイトル、またはウィジェットの子から収集されます。 さらにカスタマイズできますScreenNameExtractorスクリーンネームを自動的にキャプチャし、RouteFilter 、デフォルトでは以下から名前を収集しますPageRoute。

アプリケーションの基本ナビゲーションが で管理されている go_router場合、 を使用して InstanaGoRouteObserver(yourRouterObject)、 Instana にルーターオブジェクトを渡すことができます。 Instana その後、ナビゲーションからスクリーンネームを取得します。

このパラメータを使用すると、特定の時間間隔内に送信できるビーコンの数の上限をカスタマイズできます。 次の表に、利用可能なオプションと、それに対応するビーコンの制限を一覧で示します。 デフォルトでは、 DEFAULT_LIMITS が選択されています。

( Boolean , enableW3CHeaders オプション) オプションを有効にすると、Flutterエージェントは、監視対象のすべての API 呼び出しに および tracestate ヘッダー traceparent を含めます。 これらのヘッダーを使用すると、バックエンドに Instana エージェントが導入されていなくても、バックエンドの相関分析が可能になります。 そのような場合は、 バックエンドのトレース詳細をInstana バックエンドにエクスポートするために、互換性のあるモニタリングツール（ OpenTelemetry など）を使用する必要があります。 このオプションが無効になっている場合、バックエンドの相関分析は、そのバックエンドが Instana エージェントによっても監視されている場合にのみ可能です。 デフォルト値はfalseです。