为您的应用添加OTel
只需三步即可将Dartastic OpenTelemetry添加到Flutter应用或Dart服务器:添加package,在启动时初始化一次,并将OTLP端点和令牌提供给构建。您的链路、日志和指标随即到达您的Observatory。
所需条件
- 合适的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。
Flutter应用
将这两个package添加到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中显示的名称。请选择一个大家都认得的名称;它不必是您的package名称。app.build_id是您应用的构建标识。 Flutter package会根据应用的版本号和构建号自动设置它(您的构建ID)。崩溃和版本对比都按它分组。DartasticViewObserver在每次推入路由时记录一次屏幕浏览,以及每个页面的打开时长。
使用--dart-define将端点和令牌提供给构建。手机应用看不到您shell中的环境变量,因此要通过define传入这些值。请勿将令牌放入源代码管理:将它放在您电脑或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服务器或命令行应用只需这一个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 ...
}在服务器上,同样的两个变量来自环境变量:
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 Web没有发送任何数据 | Web需要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() |
在手机和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_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。关键指标仍会到达,因为浏览器会缓冲它们。如果这些数据很重要,请使用flutter_inappwebview,它从文档开始加载时就进行捕获。
- Web Vitals: TTFB和FCP在所有平台上都能到达。LCP、CLS、INP和长任务只在平台能够测量它们的地方到达。Android WebView可测量全部四项。在iOS 27上,WKWebView不报告CLS或长任务,LCP和INP在那里也未经确认。桥接从不编造数值。
- 点击: 在平台视图(例如webview或地图)上的点击会被记录,但绝不会被算作无效点击或愤怒点击。