Những trang này hiển thị URL của Cloud. Đăng nhập trên Dedicated để các trang hiển thị URL máy chủ của bạn.

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.

XÂY DỰNGKIẾN TRÚC DARTASTICNGƯỜI DÙNGtokentickettoken Pubpushtrao đổi từ CIứng dụng đến tay người dùng: kho ứng dụng, web, máy chủsymbolcrashstack tracemã nguồntelemetryMáy tính nhà phát triểnflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomtạo token · phân quyền theo vai tròControl Planetổ chức · vai trò · tokenDartastic Pubpackage · mã nguồnObservatoryphiên · trace · logSymbolizercrash → dòng mã nguồnDartastic AItrả lời từ cả haiHệ thống quản lý ticketGitHub · Jira · LinearỨng dụng di động + desktopđiện thoại · máy tính bảng · máy tínhgửi bằng token OTLPỨng dụng webtrong trình duyệtgửi bằng token Browser OTLPMáy chủ Dartbackend · dịch vụgửi bằng token OTLP

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.io với một token Pub.
[TODO: ảnh chụp màn hình Control Room, “Tokens”: “Generate”, rồi “OTLP”, và token mới được hiển thị một lần]

Ứ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:

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

Khởi tạo một lần, trước 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 đặ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_id là đị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ó.
  • DartasticViewObserver ghi 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 đó.

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"

Đâ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ụngAndroidiOS
version: 1.4.0+27 trong pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 trong pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.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:

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 ...
}

Trên máy chủ, hai biến đó được lấy từ môi trường:

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

Telemetry 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:

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);
});
  • 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).

[TODO: ảnh chụp màn hình màn hình “Traces” của Observatory hiển thị trace đầu tiên của ứng dụng]
Bạn thấy gìCần làm gì
Không có gì đếnKiể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ã 401Token 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ệuBiến môi trườngKhi ứng dụng đang chạy
Trace, trong DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Trace, trong engineDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MetricDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Ghi màn hình RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.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 tail cò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 ERROR trở 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.flushMetrics và 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ếtBản phát lại cho thấy gìMỗi phút thêm
EventsDò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
OutlineMột khung cho mỗi phần tử chính. Không có chữ, không có biểu tượng.62 KB
WireframeThê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 đặtBiến môi trườngKhi ứng dụng đang chạy
Mức của ứng dụngDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Mức của một màn hìnhKhông cósetFidelity(level, route: '/checkout')
Mức cao nhất một bản build được gửiDARTASTIC_RUM_FIDELITY_MAXKhông có
Văn bản bị ẩn ở mức PixelKhông cóReplayCaptureController.setMasking()
Bật hoặc tắt phát lạiKhô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òn ReplayMasking.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.bufferUntilTrigger giữ 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.

dart
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)

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();

Với flutter_inappwebview (6.1.5 trở lên)

Đặt transport: DartasticWebviewTransport.inAppWebViewHandler trên bridge, và để JavaScript bật.

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

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ữ.