Flutter 監視 API

設定

建議儘早在 initState() 中起始設定應用程式狀態類別的 Instana:

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

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
    await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', null);

    // Alternatively with configuration options
    var options = SetupOptions();
    options.collectionEnabled = false;
    await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
}

支援的 Dart 及 Flutter 版本

目前支援所有具有 2.12.0 版或更高版本的 Dart SDK ，以及所有從 1.20.0 開始的 Flutter 版本。

已啟用或停用收集

您可以在執行時期隨時啟用或停用資料收集。 這會啟用延遲啟動資料收集 (例如，在使用者同意之後)。

| <div style="width:230px">Property</div>                              | Description                               |

| --------------------------------- | --------------------------------------------- | | setCollectionEnabled (Bool) | 啟用或停用資料收集的旗標 |

InstanaAgent.setCollectionEnabled(true);

錯誤處理

代理程式的所有介面都會傳回非同步 Future。 錯誤包裝在 PlatformException 類型的異常狀況中。

建議您遵循 Futures 的一般錯誤處理技術 ，並記載可能的錯誤。

例如：

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");
}

階段作業 ID

每一個 Instana 代理程式實例都有唯一的階段作業 ID ，您可以在應用程式中用於其他用途。

static Future<String> getSessionID() async

var sessionID = await Instana.getSessionID();

手動 HTTP 監視

使用 Flutter 時，必須手動擷取 HTTP 階段作業。 如需詳細資料，請參閱每一個平台特定的文件。

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

Future<Marker>

final url = 'http://www.example.com/album'
var marker = await InstanaAgent.startCapture(url: url, method: 'GET', viewName: 'Album');

設定回應詳細資料

完成回應之後，您可以在 Marker上設定回應大小及 HTTP 回應狀態碼。

marker.responseSizeHeader = 50; // Size of the HTTP header
marker.responseSizeBody = 1000; // Size of the http body
marker.responseSizeBodyDecoded = 2400; // // Size of the decoded http body

marker.responseStatusCode = 200; // The http status code 

marker.responseHeaders = response.headers;

marker.backendTracingID = 'be01a91da80e33'; // the backend tracing id

var Map<String,String> headers = getResponseHeaders(); // You need to get this map from your `response` object
var backendTracingID = BackendTracingIDParser.fromHeadersMap(headers);

marker.errorMessage = 'Download of album failed'; // the backend tracing id

完成 HTTP 擷取

設定回應詳細資料之後，您必須在 Marker 上呼叫 finish ，以完成擷取。

marker.finish();

取消 HTTP 擷取

您也可以取消擱置中 Marker

marker.cancel();

視圖

Instana 可以依邏輯視圖將行動式應用程式見解分段。 如果要這麼做，請透過 InstanaAgent.setView(String) 方法來設定視圖名稱。 然後，該視圖將與所有受監視信標相關聯，直到再次呼叫 setView 之後該視圖變更為止。

我們建議不要使用「類別」之類的技術或通用名稱 (例如 WebViewActivity) 以定義視圖。 建議使用視圖的可讀名稱，例如 product detail page 或 payment selection。 聚焦於使用者體驗，可讓團隊成員在對程式碼庫沒有深入瞭解的情況下，瞭解所提供的見解。

附註: 當畫面呈現給使用者時，應該會呼叫 InstanaAgent.setView(String) ，而不是在建立畫面時 (例如在可以建立一次但顯示多次的「片段」中)。 設定視圖名稱也會啟用 Instana ，以追蹤 除了頁面載入之外的頁面轉移。

static Future<void> setView(String name) async

await InstanaAgent.setView('Webview: FitBit authorization');

識別使用者

使用者特定資訊可以選擇性地與傳輸至 Instana 的資料一起傳送。 然後可以使用此資訊來解除鎖定其他功能，例如:

• 計算受錯誤影響的使用者數目，
• 過濾特定使用者的資料
• 以查看哪個使用者起始視圖變更或 HTTP 要求。

依預設， Instana 不會將任何使用者識別資訊關聯至信標。 在選擇這樣做時，請注意個別的資料保護法。 我們通常建議透過使用者 ID 來識別使用者。 對於 Instana ，這是完全透通的 String ，僅用於計算特定度量值。 userName 和 userEmail 也可以用來存取更多過濾器，以及更愉快地呈現使用者資訊。

在您處理匿名使用者因而無法存取使用者 ID 的情況下，您可以選擇使用階段作業 ID。 階段作業 ID 在過濾資料時沒有使用者 ID 那麼有用，但它們是計算受影響/唯一使用者度量值的良好指標。 建議設定使用者名稱 (例如 Anonymous ) ，以明確區分已鑑別與未經鑑別的使用者。 階段作業 ID 可以是機密資料 (視使用的架構/平台而定)。 請考量雜湊階段作業 ID ，以避免將資料傳輸至可授與存取權的 Instana。

請務必注意，已傳輸至 Instana 伺服器的資料無法追溯更新。 基於此原因，請務必在應用程式啟動程序中儘早呼叫此 API。

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

@override
void initState() {
  super.initState();

  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL');
  await InstanaAgent.setUserID('1234567890');
  await InstanaAgent.setUserName('John Appleseed');
  await InstanaAgent.setUserEmail('john@appleseed.com');
}

meta 資料

任意 meta 資料可以選擇性地附加至傳輸至 Instana 的所有資料。 請考量使用此項目來追蹤使用者介面配置值、設定、特性旗標 ... 任何可能有助於分析的其他環境定義。

附註: 我們目前最多支援 50 個 meta 鍵值組。

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

await InstanaAgent.setMeta(key: 'exampleKey', value: 'Some Value');

報告自訂事件

自訂事件可讓您向 Instana 報告非標準活動、重要互動及自訂計時。 這在分析未捕捉的錯誤 (瀏覽途徑) 及追蹤其他效能度量時特別有用。

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

await InstanaAgent.reportEvent(
      name: 'advancedCustomEvent',
      options: EventOptions()
        ..viewName = 'customViewName'
        ..startTime = DateTime.now().millisecondsSinceEpoch
        ..duration = 3 * 1000
        ..meta = {
          'customKey1': 'customValue1',
          'customKey2': 'customValue2'
        });

擷取 HTTP 標頭

Instana 代理程式可以選擇性地擷取每一個追蹤要求/回應的 HTTP 標頭。

可以定義正規表示式型樣清單，以決定將擷取哪些標頭。

如果要求及其回應中都有相同的標頭名稱，則只會保留回應的標頭值。

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

InstanaAgent.setCaptureHeaders(regex: [
      'x-ratelimit-limit',
      'x-ratelimit-remaining',
      'x-ratelimit-reset'
    ]);

編寫 URL 查詢參數

所收集 URL 中的查詢參數可能包含機密資料。 因此， Instana 代理程式支援為需要編寫其值的查詢參數索引鍵指定 regex 型樣。 任何需要編寫的值都將取代為字串 <redacted>。 在 Instana 代理程式向 Instana 伺服器報告之前，會先在 Instana 代理程式內進行編寫。 因此，密鑰將無法到達 Instana 伺服器進行處理，且無法在 Instana 使用者介面中進行分析或使用 Instana API 進行擷取。

依預設， Instana 代理程式會配置三個正規表示式型樣的清單，以自動編寫索引鍵 "password"、"key" 及 "secret" 的查詢參數值。

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

InstanaAgent.redactHTTPQuery(regex: [
      'user',
      'id',
      'key'
    ]);

原生 HTTP 監視

雖然預設會停用 HTTP 監視，但您可以擷取在 iOS 平台 (Swift 或 Objective C 語言) 及 Android 平台 (Kotlin 或 Java 語言) 內進行的 HTTP 呼叫。

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions(captureNativeHttp: true);
  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
  if (!ret) {
    // Error handling here
    if (kDebugMode) {
      print("InstanaAgent setup failed");
    }
  }
}

自動 HTTP 監視

可以自動擷取以 Dart 語言建立的 HTTP 階段作業。 設定 HttpOverrides.global 內容，如下列範例所示:

@override
void main() {
  HttpOverrides.global = InstanaHttpOverrides();
  runApp(const MyApp());
}

慢速傳送模式

依預設會停用慢速傳送模式特性。 必要的話，您可以啟用此特性。

依預設，如果信標傳送失敗， Instana 代理程式會嘗試重新傳送信標，直到傳送成功為止。 這在某些行動網路上並不奏效。 透過啟用慢速傳送模式特性，信標傳送間隔會變更為指派給 slowSendIntervalMillis 參數的時間值。 每一個引標傳送只包含一個引標而非批次 (批次中最多 100 個引標)。 Instana 代理程式會保持慢速傳送模式，直到順利傳送一個引標為止。

slowSendIntervalMillis 的有效時間範圍是 2-3600 秒。

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions();
  options.slowSendInterval = 60.0;
  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
  if (!ret) {
    // Error handling here
    if (kDebugMode) {
      print("InstanaAgent setup failed");
    }
  }
}

使用者階段作業 ID

依預設，會追蹤使用者階段作業，且 ID 是隨機產生的「通用唯一 ID (UUID)」。 安裝應用程式時，此 ID 保持不變。 您可以使用 usiRefreshTimeIntervalInHrs 參數來配置使用者階段作業 ID 的有效期限。 下列參數值指出使用者階段作業 ID 的狀態:

• 負數: 此值指出使用者階段作業 ID 永不到期。 預設值為 -1。

• 正數: 此值表示在設定時間之後重新整理使用者階段作業 ID ，亦即產生並使用新的 UUID。

• 零: 以 0.0 表示的這個值表示已停用使用者階段作業 ID。

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions();
  options.usiRefreshTimeIntervalInHrs = 24.0;
  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
  if (!ret) {
    // Error handling here
    if (kDebugMode) {
      print("InstanaAgent setup failed");
    }
  }
}