这些页面显示的是Cloud的URL。在Dedicated上登录后,即显示您服务器的URL。

为您的应用添加OTel

只需三步即可将Dartastic OpenTelemetry添加到Flutter应用或Dart服务器:添加package,在启动时初始化一次,并将OTLP端点和令牌提供给构建。您的链路、日志和指标随即到达您的Observatory。

构建DARTASTIC架构用户令牌IssuePub令牌推送CI令牌交换应用发布给用户:应用商店、Web、服务器符号崩溃堆栈源代码遥测数据开发者电脑flutter run · dart pub getCIGitHub Actions、GitLab…Control Room生成令牌 · 基于角色的访问控制控制平面组织 · 角色 · 令牌Dartastic Pubpackage · 源代码Observatory会话 · 链路 · 日志Symbolizer崩溃 → 源代码行Dartastic AI综合两者作答Issue跟踪器GitHub · Jira · Linear移动和桌面应用手机 · 平板 · 电脑使用OTLP令牌发送Web应用运行在浏览器中使用Browser OTLP令牌发送Dart服务器后端 · 服务使用OTLP令牌发送

所需条件

  • 合适的Flutter和Dart版本。 构建您的第一个应用列出了每个package的要求。
  • 一个OTLP令牌。 在Control Room中打开Tokens,选择Generate,再选择OTLP。令牌只显示一次:请将其保存在密码管理器或CI密钥中。对于Flutter Web,请改用Browser OTLP令牌(Browser OTLP)。
  • 您的OTLP端点: https://otlp.cloud.dartastic.io。
  • Dartastic Pub的访问权限以获取package:使用Pub令牌执行dart pub token add https://pub.dartastic.io。
[TODO:Control Room的“Tokens”:先选“Generate”,再选“OTLP”,新令牌仅显示一次的屏幕截图]

Flutter应用

将这两个package添加到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中显示的名称。请选择一个大家都认得的名称;它不必是您的package名称。
  • app.build_id是您应用的构建标识。 Flutter package会根据应用的版本号和构建号自动设置它(您的构建ID)。崩溃和版本对比都按它分组。
  • DartasticViewObserver在每次推入路由时记录一次屏幕浏览,以及每个页面的打开时长。

使用--dart-define将端点和令牌提供给构建。手机应用看不到您shell中的环境变量,因此要通过define传入这些值。请勿将令牌放入源代码管理:将它放在您电脑或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服务器或命令行应用只需这一个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 ...
}

在服务器上,同样的两个变量来自环境变量:

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 Web没有发送任何数据Web需要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()

在手机和Web上,环境变量是在构建时设置的--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演示应用上测得。一个5分钟的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。关键指标仍会到达,因为浏览器会缓冲它们。如果这些数据很重要,请使用flutter_inappwebview,它从文档开始加载时就进行捕获。
  • Web Vitals: TTFB和FCP在所有平台上都能到达。LCP、CLS、INP和长任务只在平台能够测量它们的地方到达。Android WebView可测量全部四项。在iOS 27上,WKWebView不报告CLS或长任务,LCP和INP在那里也未经确认。桥接从不编造数值。
  • 点击: 在平台视图(例如webview或地图)上的点击会被记录,但绝不会被算作无效点击或愤怒点击。