這些頁面顯示的是Cloud的URL。在Dedicated上登入後,就會顯示您伺服器的URL。

在應用程式中加入OTel

只要三個步驟,就能在Flutter應用程式或Dart伺服器中加入Dartastic OpenTelemetry:加入套件、在啟動時初始化一次,再將OTLP端點和權杖提供給建置。您的追蹤、記錄和指標就會抵達您的Observatory。

建置DARTASTIC架構使用者權杖issuePub權杖pushCI交換應用程式交付給使用者:應用程式商店、Web、伺服器符號當機堆疊追蹤原始碼遙測開發者電腦flutter run · dart pub getCIGitHub Actions、GitLab…Control Room建立權杖 · 角色型存取控制控制平面組織 · 角色 · 權杖Dartastic Pub套件 · 原始碼Observatory工作階段 · 追蹤 · 記錄Symbolizer當機 → 原始碼行Dartastic AI綜合兩者作答Issue追蹤系統GitHub · Jira · Linear行動與桌面應用程式手機 · 平板 · 桌機以OTLP權杖傳送Web應用程式在瀏覽器中以Browser OTLP權杖傳送Dart伺服器後端 · 服務以OTLP權杖傳送

需要準備的項目

  • 合適的Flutter和Dart版本。 建置您的第一個應用程式列出每個套件的需求。
  • OTLP權杖。 在Control Room中開啟Tokens,選擇Generate,再選擇OTLP。權杖只會顯示一次:請保存在密碼管理工具或CI機密中。Flutter網頁版請改用Browser OTLP權杖(Browser OTLP)。
  • 您的OTLP端點: https://otlp.cloud.dartastic.io。
  • Dartastic Pub的存取權以取得套件:使用Pub權杖執行dart pub token add https://pub.dartastic.io。
[TODO:Control Room的「Tokens」:「Generate」,接著「OTLP」,以及只顯示一次的新權杖的螢幕截圖]

Flutter應用程式

將這兩個套件加入pubspec.yaml。它們一起發行,版本始終一致:

yaml
dependencies:
  dartastic_opentelemetry_native:
    hosted: https://pub.dartastic.io
    version: 1.22.4
  dartastic_opentelemetry_native_flutter:
    hosted: https://pub.dartastic.io
    version: 1.22.4

在runApp之前初始化一次:

dart
import 'package:dartastic_opentelemetry_native/dartastic_opentelemetry_native.dart';
import 'package:dartastic_opentelemetry_native_flutter/dartastic_opentelemetry_native_flutter.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await DOTel.initialize(
    serviceName: 'checkout-app',
    serviceVersion: '1.4.0',
  );
  runApp(MaterialApp(
    navigatorObservers: [DartasticViewObserver()], // screen views
    home: const HomeScreen(),
  ));
}
  • serviceName是您應用程式在Observatory中的名稱。請選一個大家認得的名稱;不一定要與套件名稱相同。
  • app.build_id是您應用程式的建置版本識別。 Flutter套件會依據應用程式的版本和建置編號自動設定(您的建置ID)。當機和版本比較都依此分組。
  • DartasticViewObserver會在每次推入路由時記錄一次畫面瀏覽,以及每個畫面開啟了多久。

使用--dart-define將端點和權杖提供給建置。手機應用程式看不到您shell的環境,因此要靠這些定義把值傳進去。請勿將權杖放入版本控制:把它放在您電腦或CI上的環境變數中,再傳入該變數。

shell
flutter run --release \
  --dart-define=OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io \
  --dart-define=OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"

這些是OpenTelemetry的標準變數。authorization請保持小寫:所有協定都適用。OTLP權杖只能將遙測資料傳送到您的組織:它無法讀取或變更任何內容。

DOTel.initialize完成後,不需要額外程式碼就會記錄:

  • 每次造訪的工作階段,附在每個span和記錄項目上;
  • 點擊,以及應用程式回應點擊的速度;
  • 畫面瀏覽,透過DartasticViewObserver;
  • 以及您方案所包含的當機、UI凍結、卡頓和關鍵指標。

您的建置ID

建置ID來自各平台為您應用程式回報的版本和建置編號:

您應用程式的版本AndroidiOS
pubspec.yaml中的version: 1.4.0+271.4.0+271.4.0+27
pubspec.yaml中的version: 1.4.01.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.4.0+27

版本沒有建置編號時,Android會加上+1,因為那是Flutter在Android上的預設建置編號。若要讓所有平台使用同一個建置ID,請為版本加上建置編號(1.4.0+27)。

Dart伺服器

Dart伺服器或命令列應用程式只需要這一個套件:

yaml
dependencies:
  dartastic_opentelemetry_native:
    hosted: https://pub.dartastic.io
    version: 1.22.4
dart
import 'package:dartastic_opentelemetry_native/dartastic_opentelemetry_native.dart';

Future<void> main() async {
  await DOTel.initialize(
    serviceName: 'orders-api',
    serviceVersion: '2.3.1',
  );
  // ... start your server ...
}

在伺服器上,同樣的兩個變數來自環境:

shell
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dart

遙測絕不會讓您的應用程式出錯

OpenTelemetry的規則是:遙測在執行階段絕不能向您的程式碼擲回錯誤。Dartastic處處遵循這項規則。當遙測內部出問題時(端點無法連線、屬性值有誤、匯出失敗),錯誤會回報給OpenTelemetry錯誤處理常式並記錄下來,而您的應用程式會繼續執行。

若要在您自己的記錄或當機回報中看到這些回報,請安裝您自己的處理常式。無論在DOTel.initialize之前或之後呼叫都有效:

dart
// Before DOTel.initialize: send telemetry's own errors to your logging
// or crash reporting. OTel calls it instead of throwing into your code.
OTelAPI.setErrorHandler((error, stackTrace) {
  myLogger.warning('OpenTelemetry: $error', error, stackTrace);
});
  • 沒有處理常式時,錯誤會以OpenTelemetry自己的記錄寫出(OTEL_LOG_LEVEL設定它輸出的詳細程度)。
  • 您自己的處理常式是唯一可以重新擲回錯誤的地方,例如在測試建置版本中快速失敗。在正式環境中,請記錄後返回。

確認資料抵達

執行應用程式並使用一分鐘,然後開啟Observatory的「Traces」或「Logs」:您的serviceName就在那裡(Observatory)。

[TODO:Observatory的「Traces」畫面,顯示應用程式的第一個追蹤的螢幕截圖]
您看到的情況處理方式
沒有任何資料抵達檢查端點。以--dart-define=OTEL_LOG_LEVEL=debug執行一次(在伺服器上則用OTEL_LOG_LEVEL=debug):權杖傳到應用程式時,記錄會顯示OTelEnv: Parsed 1 header(s),並隱藏其值。
匯出遭拒,傳回401權杖錯誤、已撤銷,或來自其他組織或部署。請在此組織的Control Room中產生新的OTLP權杖。
Flutter網頁版沒有傳送任何資料網頁版需要Browser OTLP權杖,且權杖上須列出您網站的來源(Browser OTLP)。

傳送多少資料

應用程式傳送的資料會計入方案的傳入流量,Cloud和Dedicated皆然(定價)。追蹤、指標和記錄預設為開啟,只要以下設定都未設定,就不會取樣捨棄任何資料。RUM畫面擷取預設為關閉。每一項都可以用環境變數設定,並在應用程式執行時變更。何時變更由您的應用程式決定,並呼叫對應的setter。沒有遠端設定。

訊號環境變數應用程式執行時
追蹤(Dart)OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
追蹤(引擎)DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
記錄DARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
指標DARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
RUM畫面擷取DARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.setRumSampleRate()

在手機和網頁上,環境變數是在建置時設定的--dart-define。程式碼中的值優先於環境變數,而執行時的變更又優先於兩者。無效的值會以名稱回報給OpenTelemetry錯誤處理常式,原本生效的設定保持不變。

  • 追蹤(引擎): 變更會在下一個批次生效。tail取樣器仍保留的span會立即經過新的取樣器,因此變更絕不會遺失它們。
  • 記錄: 比率為0.0至1.0,依工作階段決定,因此工作階段會整個保留或整個捨棄,提高比率只會增加工作階段。ERROR或以上的記錄項目一律送出,因此當機和嚴重的ANR一定會抵達。畫面瀏覽和點擊都是記錄項目,因此在此被捨棄的工作階段,其時間軸上不會有這些項目。
  • 指標: 比率為0.0至1.0,用來減少匯出週期:設為0.25時,每四個定期週期送出一次。累計總數保持正確。DOTel.flushMetrics和關閉時一律送出,但比率為0時則不送出任何資料。
  • RUM畫面擷取: 比率為0.0至1.0,依工作階段決定,變更立即生效。提高比率只會增加工作階段,降低比率只會減少工作階段。它涵蓋擷取所記錄的內容:工作階段、畫面和點擊屬於遙測資料,不受其影響。支援錄製絕不會被取樣捨棄。如果建置和程式碼都設定了比率,兩者必須一致,否則擷取會從0開始。每個被擷取的工作階段包含多少內容,取決於其精細度。

RUM精細度

精細度是重播包含多少畫面內容。重播依其儲存的位元組數計入方案的傳入流量,因此等級越低,用量越少。

精細度重播呈現的內容每分鐘增加
Events由畫面、點擊、網路呼叫、span、錯誤和當機組成的時間軸。沒有螢幕畫面。沒有重播位元組
Outline每個主要元素一個方框。不含文字和圖示。62KB
Wireframe也包含文字、圖示和較小的控制項,每個都畫成方框。文字以灰色長條呈現,任何字元都不會離開裝置。81KB
Shadow真實的螢幕截圖,模糊成色塊,讓文字無法辨識。430KB
Pixel真實的螢幕截圖,就是使用者看到的畫面。597KB
Pixel,隱藏輸入文字螢幕截圖,使用者輸入的內容會被塗蓋。516KB
Pixel,隱藏所有文字螢幕截圖,所有文字都會被塗蓋。438KB

於2026年11月在Alpine Trails示範應用程式上測得。一段五分鐘的Pixel工作階段約增加3MB。您應用程式的畫面會有所不同。

設定環境變數應用程式執行時
應用程式的等級DARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
單一畫面的等級無setFidelity(level, route: '/checkout')
建置版本可傳送的最高等級DARTASTIC_RUM_FIDELITY_MAX無
Pixel時隱藏的文字無ReplayCaptureController.setMasking()
開啟或關閉重播無ReplayCaptureController.setMode()

等級為events、outline、wireframe、shadow和pixel。此處的每個環境變數都是在建置時設定的--dart-define。

  • 應用程式的等級: 如果建置和程式碼都設定了等級,兩者必須一致。若不一致,或值不是有效的等級,擷取會回報此問題並停留在Events。支援錄製可以提高等級,而某個畫面上較低的設定仍會在該畫面上生效。
  • 最高等級: 無論應用程式或錄製要求什麼,引擎都會捨棄高於此等級的任何重播記錄。可用來認證建置版本,例如無法擷取像素的建置版本。
  • Pixel時隱藏的文字: ReplayMasking.textFields會隱藏使用者輸入的內容,ReplayMasking.allText會隱藏所有文字。
  • 開啟或關閉重播: 在應用程式設定模式之前,重播都是關閉的。ReplayMode.bufferUntilTrigger會將影格保留在裝置上,只在出問題時才上傳,因此沒有出錯的工作階段完全不會上傳重播。

Webview

應用程式內的網頁(例如結帳流程或說明中心)可以將其錯誤、請求、Web Vitals和事件傳入應用程式的工作階段,並標記為dartastic.telemetry.source webview。網頁本身從不匯出、不持有權杖,也看不到端點。它會傳送給您的應用程式,由應用程式檢查每個欄位,再透過應用程式自己的管線送出。Webview遙測是Pro功能。

列出您信任的主機。網頁的主機與項目完全相同,或是項目的子網域時才相符;清單為空時,橋接保持關閉。

dart
final bridge = DartasticWebviewBridge(
  allowedHosts: ['checkout.example.com', 'example.com'],
  serviceName: 'web-checkout',
  transport: DartasticWebviewTransport.javaScriptChannel,
);

允許的網頁所傳送的任何內容,都使用您應用程式的遙測憑證,且伺服器端不會遮蔽任何內容。您的allowedHosts清單和橋接的大小上限就是防護範圍。

使用webview_flutter(4.9.0及更新版本)

dart
controller
  // Required on Android: without unrestricted JavaScript there is no
  // channel and no bridge.
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..addJavaScriptChannel(
    bridge.channelName,
    onMessageReceived: (m) => bridge.handleMessage(m.message),
  )
  ..setNavigationDelegate(NavigationDelegate(
    onPageStarted: (url) {
      final shim = bridge.shimForUrl(url);
      if (shim != null) controller.runJavaScript(shim);
    },
    // Required on iOS and macOS, and does nothing elsewhere.
    onPageFinished: (url) {
      final shim = bridge.shimForCommittedPage(url);
      if (shim != null) controller.runJavaScript(shim);
    },
  ));
// When the webview goes away:
bridge.notifyPageEnded();

使用flutter_inappwebview(6.1.5及更新版本)

在橋接上設定transport: DartasticWebviewTransport.inAppWebViewHandler,並保持JavaScript開啟。

dart
InAppWebView(
  initialUrlRequest: URLRequest(url: WebUri('https://checkout.example.com/')),
  // Installed once: it captures from document start, and holds what it
  // captures until the page is armed below.
  initialUserScripts: UnmodifiableListView([
    if (bridge.shimSource case final source?)
      UserScript(
        source: source,
        injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START,
        forMainFrameOnly: true,
      ),
  ]),
  onWebViewCreated: (controller) {
    controller.addJavaScriptHandler(
      handlerName: bridge.channelName,
      callback: (args) =>
          bridge.handleMessage(args.isEmpty ? '' : args.first as String),
    );
  },
  onLoadStart: (controller, url) async {
    if (url == null) return;
    final source = bridge.shimForUrl(url.toString());
    if (source != null) {
      await controller.evaluateJavascript(source: source);
    }
  },
  // Required on iOS and macOS, and does nothing elsewhere.
  onPageCommitVisible: (controller, url) async {
    if (url == null) return;
    final source = bridge.shimForCommittedPage(url.toString());
    if (source != null) {
      await controller.evaluateJavascript(source: source);
    }
  },
)

會抵達的資料

  • iOS和macOS: 這兩個平台必須使用shimForCommittedPage(1.32.0及更新版本),在其他平台上它不起作用。沒有它,這兩個平台上的網頁只會傳送其網頁span。
  • iOS和macOS上的webview_flutter: 網頁載入完成前的錯誤和請求不會被擷取,而從未載入完成的網頁只會傳送其span。Web Vitals仍會抵達,因為瀏覽器會暫存它們。若這些資料很重要,請使用從文件開始時就擷取的flutter_inappwebview。
  • Web Vitals: TTFB和FCP在所有平台上都會抵達。LCP、CLS、INP和長時間工作,則在平台有量測時才會抵達。Android WebView四項都會量測。在iOS 27上,WKWebView不回報CLS或長時間工作,LCP和INP在該平台也尚未確認。橋接絕不會自行捏造數值。
  • 點擊: 在平台檢視(例如webview或地圖)上的點擊會被記錄,但絕不會計為無效點擊或憤怒點擊。