在應用程式中加入OTel
只要三個步驟,就能在Flutter應用程式或Dart伺服器中加入Dartastic OpenTelemetry:加入套件、在啟動時初始化一次,再將OTLP端點和權杖提供給建置。您的追蹤、記錄和指標就會抵達您的Observatory。
需要準備的項目
- 合適的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。
Flutter應用程式
將這兩個套件加入pubspec.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之前初始化一次:
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上的環境變數中,再傳入該變數。
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來自各平台為您應用程式回報的版本和建置編號:
| 您應用程式的版本 | Android | iOS |
|---|---|---|
pubspec.yaml中的version: 1.4.0+27 | 1.4.0+27 | 1.4.0+27 |
pubspec.yaml中的version: 1.4.0 | 1.4.0+1 | 1.4.0 |
--build-name=1.4.0 --build-number=27 | 1.4.0+27 | 1.4.0+27 |
版本沒有建置編號時,Android會加上+1,因為那是Flutter在Android上的預設建置編號。若要讓所有平台使用同一個建置ID,請為版本加上建置編號(1.4.0+27)。
Dart伺服器
Dart伺服器或命令列應用程式只需要這一個套件:
dependencies:
dartastic_opentelemetry_native:
hosted: https://pub.dartastic.io
version: 1.22.4import '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 ...
}在伺服器上,同樣的兩個變數來自環境:
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之前或之後呼叫都有效:
// 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)。
| 您看到的情況 | 處理方式 |
|---|---|
| 沒有任何資料抵達 | 檢查端點。以--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_ARG | DOTel.tracesSampler |
| 追蹤(引擎) | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| 記錄 | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| 指標 | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| RUM畫面擷取 | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.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_FIDELITY | ReplayCaptureController.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功能。
列出您信任的主機。網頁的主機與項目完全相同,或是項目的子網域時才相符;清單為空時,橋接保持關閉。
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);允許的網頁所傳送的任何內容,都使用您應用程式的遙測憑證,且伺服器端不會遮蔽任何內容。您的allowedHosts清單和橋接的大小上限就是防護範圍。
使用webview_flutter(4.9.0及更新版本)
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開啟。
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或地圖)上的點擊會被記錄,但絕不會計為無效點擊或憤怒點擊。