Thêm OTel vào ứng dụng của bạn
Thêm Dartastic OpenTelemetry vào một ứng dụng Flutter hoặc một máy chủ Dart trong ba bước: thêm các package, khởi tạo một lần khi khởi động, và cung cấp cho bản build endpoint OTLP cùng token của bạn. Trace, log và metric của bạn đến Observatory.
Bạn cần gì
- Đúng phiên bản Flutter và Dart. Xây dựng ứng dụng đầu tiên liệt kê những gì mỗi package cần.
- Một token OTLP. Trong Control Room, mở màn hình Tokens, chọn Generate, rồi OTLP. Token chỉ hiển thị một lần: hãy lưu nó trong trình quản lý mật khẩu hoặc trong secret của CI. Với Flutter web, hãy dùng token Browser OTLP thay thế (Browser OTLP).
- Endpoint OTLP của bạn:
https://otlp.cloud.dartastic.io. - Quyền truy cập Dartastic Pub để lấy các package:
dart pub token add https://pub.dartastic.iovới một token Pub.
Ứng dụng Flutter
Thêm hai package vào pubspec.yaml. Chúng được phát hành cùng nhau và luôn cùng một phiên bản:
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.4Khởi tạo một lần, trước 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đặt tên cho ứng dụng của bạn trong Observatory. Hãy chọn một tên mọi người nhận ra; không nhất thiết phải là tên package.app.build_idlà định danh build của ứng dụng. Package Flutter tự đặt giá trị này cho bạn, từ phiên bản và số build của ứng dụng (Build id của bạn). Crash và việc so sánh các bản phát hành được nhóm theo nó.DartasticViewObserverghi một lượt xem màn hình mỗi khi một route được push, cùng thời gian mỗi màn hình được mở.
Cung cấp endpoint và token cho bản build bằng --dart-define. Ứng dụng điện thoại không thấy biến môi trường trong shell của bạn, nên define là cách đưa các giá trị đến ứng dụng. Đừng đưa token vào hệ thống quản lý mã nguồn: hãy đặt nó trong một biến môi trường trên máy bạn hoặc trong CI, rồi truyền biến đó.
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"Đây là các biến chuẩn của OpenTelemetry. Giữ authorization viết thường: cách này dùng được với mọi giao thức. Một token OTLP chỉ gửi được telemetry đến tổ chức của bạn: nó không đọc gì và không thay đổi gì.
Khi DOTel.initialize hoàn tất, nó ghi lại những thứ sau mà không cần thêm mã:
- một phiên cho mỗi lượt dùng, trên mọi span và bản ghi log;
- các lượt chạm, và ứng dụng phản hồi chúng nhanh đến đâu;
- các lượt xem màn hình, qua
DartasticViewObserver; - và, khi gói của bạn bao gồm chúng, crash, UI bị đơ, jank và vitals.
Build id của bạn
Build id đến từ phiên bản và số build mà mỗi nền tảng báo cáo cho ứng dụng của bạn:
| Phiên bản ứng dụng | Android | iOS |
|---|---|---|
version: 1.4.0+27 trong pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 trong pubspec.yaml | 1.4.0+1 | 1.4.0 |
--build-name=1.4.0 --build-number=27 | 1.4.0+27 | 1.4.0+27 |
Android thêm +1 vào một phiên bản không có số build, vì đó là số build mặc định của Flutter trên Android. Để có một build id trên mọi nền tảng, hãy cho phiên bản của bạn một số build (1.4.0+27).
Máy chủ Dart
Một máy chủ Dart hoặc ứng dụng dòng lệnh chỉ cần một package:
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 ...
}Trên máy chủ, hai biến đó được lấy từ môi trường:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dartTelemetry không bao giờ làm hỏng ứng dụng của bạn
Quy tắc của OpenTelemetry là telemetry không bao giờ được ném lỗi vào mã của bạn lúc runtime. Dartastic tuân theo quy tắc này ở mọi nơi. Khi có gì trục trặc bên trong telemetry (một endpoint không truy cập được, một thuộc tính có giá trị sai, một lần export thất bại), lỗi được báo cho error handler của OpenTelemetry và được ghi log, còn ứng dụng của bạn vẫn tiếp tục chạy.
Để thấy các báo cáo đó trong hệ thống log hoặc báo cáo crash của riêng bạn, hãy cài handler của bạn. Nó hoạt động dù bạn gọi trước hay sau 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);
});- Không có handler, các lỗi được ghi bằng log riêng của OpenTelemetry (
OTEL_LOG_LEVELđặt mức chi tiết của log đó). - Handler của riêng bạn là nơi duy nhất một lỗi có thể được ném lại, chẳng hạn để dừng ngay trong một bản build kiểm thử. Trong production, hãy ghi log rồi return.
Xem dữ liệu đến
Chạy ứng dụng và dùng thử khoảng một phút, rồi mở “Traces” hoặc “Logs” của Observatory: serviceName của bạn có ở đó (Observatory).
| Bạn thấy gì | Cần làm gì |
|---|---|
| Không có gì đến | Kiểm tra endpoint. Chạy một lần với --dart-define=OTEL_LOG_LEVEL=debug (hoặc OTEL_LOG_LEVEL=debug trên máy chủ): log ghi OTelEnv: Parsed 1 header(s) khi token của bạn đã đến ứng dụng, với giá trị được ẩn. |
| Export bị từ chối với mã 401 | Token sai, đã bị thu hồi, hoặc thuộc một tổ chức hay bản deploy khác. Tạo một token OTLP mới trong Control Room của tổ chức này. |
| Flutter web không gửi gì | Web cần một token Browser OTLP có origin của trang web bạn (Browser OTLP). |
Bạn gửi bao nhiêu
Những gì ứng dụng của bạn gửi được tính vào dữ liệu vào của gói, trên cả Cloud lẫn Dedicated (Bảng giá). Trace, metric và log được bật mặc định, và khi không đặt biến nào trong số này thì không có gì bị loại do lấy mẫu. Ghi màn hình RUM tắt theo mặc định. Mỗi mục có thể đặt bằng một biến môi trường và thay đổi trong khi ứng dụng chạy. Ứng dụng của bạn quyết định khi nào thay đổi và gọi setter. Không có cài đặt từ xa.
| Tín hiệu | Biến môi trường | Khi ứng dụng đang chạy |
|---|---|---|
| Trace, trong Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Trace, trong engine | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Log | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metric | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Ghi màn hình RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.setRumSampleRate() |
Trên điện thoại và web, biến môi trường là một --dart-define, đặt lúc build. Giá trị trong mã được ưu tiên hơn biến môi trường, và thay đổi khi ứng dụng đang chạy được ưu tiên hơn cả hai. Một giá trị sai được gửi đến error handler của OpenTelemetry kèm tên biến, và giá trị đang có hiệu lực được giữ nguyên.
- Trace, trong engine: thay đổi có hiệu lực từ lô tiếp theo. Các span mà một sampler
tailcòn giữ đi qua sampler mới ngay lập tức, nên một thay đổi không bao giờ làm mất chúng. - Log: tỷ lệ từ 0,0 đến 1,0, quyết định theo phiên, nên một phiên được giữ hoặc bỏ trọn vẹn, và tăng tỷ lệ chỉ thêm phiên. Một bản ghi từ mức
ERRORtrở lên luôn được gửi, nên crash và ANR nghiêm trọng luôn đến. Lượt xem màn hình và lượt chạm là bản ghi log, nên một phiên bị bỏ ở đây không có chúng trên dòng thời gian. - Metric: tỷ lệ từ 0,0 đến 1,0 và giảm số chu kỳ export: ở 0,25, cứ bốn chu kỳ định kỳ thì một chu kỳ gửi. Tổng tích lũy vẫn đúng.
DOTel.flushMetricsvà lúc tắt luôn gửi, trừ ở mức 0, khi đó không gửi gì. - Ghi màn hình RUM: tỷ lệ từ 0,0 đến 1,0, quyết định theo phiên, và thay đổi có hiệu lực ngay. Tăng tỷ lệ chỉ thêm phiên, giảm tỷ lệ chỉ bớt phiên. Tỷ lệ này áp dụng cho những gì việc ghi màn hình ghi lại: phiên, màn hình và lượt chạm là telemetry, và nó không động đến chúng. Một bản ghi hỗ trợ không bao giờ bị loại do lấy mẫu. Nếu cả bản build lẫn mã của bạn đều đặt tỷ lệ, hai giá trị phải khớp nhau, nếu không việc ghi bắt đầu ở 0. Lượng dữ liệu mỗi phiên được ghi mang theo là mức chi tiết của phiên đó.
Mức chi tiết RUM
Mức chi tiết là lượng nội dung màn hình mà một bản phát lại mang theo. Bản phát lại được tính vào dữ liệu vào của gói theo số byte nó lưu, nên mức thấp hơn dùng ít hơn.
| Mức chi tiết | Bản phát lại cho thấy gì | Mỗi phút thêm |
|---|---|---|
| Events | Dòng thời gian của màn hình, lượt chạm, lệnh gọi mạng, span, lỗi và crash. Không có hình ảnh màn hình. | Không có byte phát lại |
| Outline | Một khung cho mỗi phần tử chính. Không có chữ, không có biểu tượng. | 62 KB |
| Wireframe | Thêm cả chữ, biểu tượng và các thành phần điều khiển nhỏ hơn, mỗi thứ vẽ thành một khung. Chữ hiện thành các thanh xám, và không ký tự nào rời khỏi thiết bị. | 81 KB |
| Shadow | Ảnh chụp màn hình thật, được làm mờ thành các khối để không đọc được chữ. | 430 KB |
| Pixel | Ảnh chụp màn hình thật, đúng như người dùng đã thấy. | 597 KB |
| Pixel, che nội dung nhập | Ảnh chụp màn hình, với nội dung người dùng nhập bị tô che. | 516 KB |
| Pixel, che toàn bộ chữ | Ảnh chụp màn hình, với toàn bộ chữ bị tô che. | 438 KB |
Đo trên ứng dụng demo Alpine Trails vào tháng 11 năm 2026. Một phiên Pixel dài năm phút thêm khoảng 3 MB. Các màn hình trong ứng dụng của bạn có thể khác.
| Cài đặt | Biến môi trường | Khi ứng dụng đang chạy |
|---|---|---|
| Mức của ứng dụng | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Mức của một màn hình | Không có | setFidelity(level, route: '/checkout') |
| Mức cao nhất một bản build được gửi | DARTASTIC_RUM_FIDELITY_MAX | Không có |
| Văn bản bị ẩn ở mức Pixel | Không có | ReplayCaptureController.setMasking() |
| Bật hoặc tắt phát lại | Không có | ReplayCaptureController.setMode() |
Các mức là events, outline, wireframe, shadow và pixel. Mỗi biến môi trường ở đây là một --dart-define, đặt lúc build.
- Mức của ứng dụng: nếu cả bản build lẫn mã của bạn đều đặt mức, hai giá trị phải khớp nhau. Nếu không khớp, hoặc một giá trị không phải là một mức, việc ghi báo lỗi đó và giữ ở mức Events. Một bản ghi hỗ trợ có thể nâng mức, còn một cài đặt thấp hơn trên một màn hình vẫn giữ nguyên trên màn hình đó.
- Mức cao nhất: engine bỏ mọi bản ghi phát lại cao hơn mức này, bất kể ứng dụng hay một bản ghi hỗ trợ yêu cầu gì. Dùng nó để chứng nhận một bản build, chẳng hạn một bản build không thể ghi pixel.
- Văn bản bị ẩn ở mức Pixel:
ReplayMasking.textFieldsẩn những gì người dùng gõ, cònReplayMasking.allTextẩn toàn bộ văn bản. - Bật hoặc tắt phát lại: phát lại tắt cho đến khi ứng dụng đặt một chế độ.
ReplayMode.bufferUntilTriggergiữ các frame trên thiết bị và chỉ tải lên khi có sự cố, nên một phiên không có gì hỏng thì không tải lên bản phát lại nào.
Webview
Một trang web bên trong ứng dụng của bạn, chẳng hạn trang thanh toán hay trung tâm trợ giúp, có thể gửi lỗi, request, web vitals và sự kiện của nó vào phiên của ứng dụng, được đánh dấu dartastic.telemetry.source webview. Trang không bao giờ export, không giữ token và không thấy endpoint. Nó gửi đến ứng dụng của bạn, ứng dụng kiểm tra từng trường rồi gửi qua pipeline riêng của ứng dụng. Telemetry webview là tính năng Pro.
Liệt kê các host bạn tin cậy. Một trang khớp khi host trùng chính xác hoặc là tên miền phụ của một mục, và danh sách trống thì bridge tắt.
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);Mọi thứ một trang được phép gửi đều dùng thông tin xác thực telemetry của ứng dụng, và không có gì che dữ liệu đó trên máy chủ. Danh sách allowedHosts và giới hạn kích thước của bridge là hàng rào ngăn chặn.
Với webview_flutter (4.9.0 trở lên)
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();Với flutter_inappwebview (6.1.5 trở lên)
Đặt transport: DartasticWebviewTransport.inAppWebViewHandler trên bridge, và để JavaScript bật.
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);
}
},
)Những gì đến
- iOS và macOS:
shimForCommittedPage(1.32.0 trở lên) là bắt buộc trên các nền tảng này, và không làm gì ở nơi khác. Thiếu nó, một trang trên các nền tảng này chỉ gửi span của trang. - webview_flutter trên iOS và macOS: lỗi và request xảy ra trước khi trang tải xong không được ghi lại, và một trang không bao giờ tải xong chỉ gửi span của nó. Vitals vẫn đến, vì trình duyệt lưu đệm chúng. Khi những dữ liệu đó quan trọng, hãy dùng flutter_inappwebview, vốn ghi lại từ lúc tài liệu bắt đầu.
- Web vitals: TTFB và FCP đến trên mọi nền tảng. LCP, CLS, INP và long task đến ở nơi nền tảng đo được chúng. Android WebView đo cả bốn. Trên iOS 27, WKWebView không báo CLS hay long task, còn LCP và INP chưa được xác nhận ở đó. Bridge không bao giờ tự bịa ra một giá trị.
- Lượt chạm: một lượt chạm trên platform view, chẳng hạn webview hay bản đồ, được ghi lại nhưng không bao giờ được tính là chạm vô hiệu hay chạm giận dữ.