アプリにOTelを追加する
FlutterアプリやDartサーバーに、Dartastic OpenTelemetryを3ステップで追加します:パッケージを追加し、起動時に一度だけ初期化し、OTLPのエンドポイントとトークンをビルドに渡します。トレース、ログ、メトリクスがお客様のObservatoryに届きます。
必要なもの
- 適切なバージョンのFlutterとDart。 各パッケージに必要なバージョンは初めてのアプリを作るに記載しています。
- OTLPトークン。 Control RoomでTokensを開き、Generate、OTLPの順に選びます。トークンは一度だけ表示されるので、パスワードマネージャーかCIのシークレットに保存してください。Flutter Webでは、代わりにBrowser OTLPトークンを使います(Browser OTLP)。
- OTLPエンドポイント:
https://otlp.cloud.dartastic.io。 - パッケージを取得するためのDartastic Pubへのアクセス:Pubトークンで
dart pub token add https://pub.dartastic.ioを実行済みであること。
Flutterアプリ
pubspec.yamlに2つのパッケージを追加します。2つは同時にリリースされ、常に同じバージョンです:
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.4runAppの前に、一度だけ初期化します:
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でビルドに渡します。スマートフォンのアプリはシェルの環境変数を参照できないため、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が完了すると、追加のコードなしで次のものを記録します:
- 訪問ごとのセッション。すべてのスパンとログレコードに付きます。
- タップと、それに対するアプリの応答の速さ。
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が付きます。それがAndroidでのFlutterのデフォルトのビルド番号だからです。すべてのプラットフォームで同じビルドIDにするには、バージョンにビルド番号を付けてください(1.4.0+27)。
Dartサーバー
Dartサーバーやコマンドラインアプリに必要なパッケージは1つだけです:
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 ...
}サーバーでは、同じ2つの変数を環境変数から取得します:
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で設定します)。 - エラーを再スローしてよいのは、独自のハンドラーの中だけです。たとえば、テストビルドですぐに失敗させたい場合です。本番環境では、ログに記録してreturnしてください。
届いたことを確認
アプリを実行して1分ほど操作し、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の画面キャプチャはデフォルトで無効です。それぞれ環境変数で設定でき、アプリの実行中に変更できます。変更のタイミングはアプリが決め、セッターを呼び出します。リモートからの設定はありません。
| シグナル | 環境変数 | アプリの実行中 |
|---|---|---|
| トレース(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サンプラーがまだ保持しているスパンはすぐに新しいサンプラーを通るため、変更によって失われることはありません。 - ログ: レートは0.0〜1.0で、セッション単位で判定されます。セッションはまるごと残るか捨てられるかのどちらかで、レートを上げるとセッションが増えるだけです。
ERROR以上のレコードは必ず送信されるため、クラッシュや重大なANRは必ず届きます。画面表示とタップはログレコードなので、ここで捨てられたセッションのタイムラインには、それらが表示されません。 - メトリクス: レートは0.0〜1.0で、エクスポートのサイクルを間引きます。0.25なら、定期サイクルの4回に1回が送信されます。累積の合計は正しく保たれます。
DOTel.flushMetricsとシャットダウン時は常に送信されますが、0の場合は何も送信しません。 - RUMの画面キャプチャ: レートは0.0〜1.0で、セッション単位で判定され、変更はすぐに適用されます。上げるとセッションが増えるだけ、下げると減るだけです。対象はキャプチャが記録するものです。セッション、画面、タップはテレメトリーなので、影響を受けません。サポート用の記録がサンプリングで間引かれることはありません。ビルドとコードの両方でレートを設定する場合は一致させてください。一致しないと、キャプチャは0で始まります。キャプチャした各セッションにどれだけの情報が含まれるかは、精細度で決まります。
RUMの精細度
精細度は、リプレイが画面をどこまで記録するかを表します。リプレイは保存するバイト数でプランの受信データに計上されるため、レベルが低いほど消費が少なくなります。
| 精細度 | リプレイの内容 | 1分あたりの増加量 |
|---|---|---|
| Events | 画面、タップ、ネットワーク呼び出し、スパン、エラー、クラッシュのタイムライン。画面の画像はありません。 | リプレイのデータなし |
| 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ページ(購入手続きやヘルプセンターなど)から、エラー、リクエスト、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以降)が必要で、ほかのプラットフォームでは何もしません。これがないと、これらのプラットフォームのページは、ページのスパンしか送信しません。 - iOSとmacOSのwebview_flutter: ページの読み込みが完了する前のエラーとリクエストはキャプチャされず、読み込みが完了しないページはスパンしか送信しません。Web Vitalsはブラウザーがバッファするため、それでも届きます。それらが重要な場合は、ドキュメントの開始時点からキャプチャするflutter_inappwebviewを使ってください。
- Web Vitals: TTFBとFCPはどこでも届きます。LCP、CLS、INP、ロングタスクは、プラットフォームが計測している場合に届きます。Android WebViewは4つすべてを計測します。iOS 27のWKWebViewはCLSとロングタスクを報告せず、LCPとINPもそこでは確認されていません。ブリッジが値を作り出すことはありません。
- タップ: プラットフォームビュー(WebViewや地図など)へのタップは記録されますが、デッドタップやレイジタップとして数えられることはありません。