このヘルプにはCloudのURLが表示されています。Dedicatedでログインすると、お客様のサーバーのURLが表示されます。

アプリにOTelを追加する

FlutterアプリやDartサーバーに、Dartastic OpenTelemetryを3ステップで追加します:パッケージを追加し、起動時に一度だけ初期化し、OTLPのエンドポイントとトークンをビルドに渡します。トレース、ログ、メトリクスがお客様のObservatoryに届きます。

ビルドDartasticアーキテクチャユーザートークンIssuePubトークンプッシュCIトークン交換アプリをユーザーへ配布:アプリストア、Web、サーバーシンボルクラッシュスタックトレースソーステレメトリー開発用コンピューターflutter run · dart pub getCIGitHub Actions、GitLab、…Control Roomトークン発行 · ロールベースのアクセス制御コントロールプレーン組織 · ロール · トークンDartastic Pubパッケージ · ソースObservatoryセッション · トレース · ログSymbolizerクラッシュ → ソースコードの行Dartastic AI両方のデータから回答IssueトラッカーGitHub · Jira · Linearモバイル・デスクトップアプリスマートフォン · タブレット · デスクトップOTLPトークンで送信Webアプリブラウザーで動作Browser OTLPトークンで送信Dartサーバーバックエンド · サービスOTLPトークンで送信

必要なもの

  • 適切なバージョンの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を実行済みであること。
[TODO:スクリーンショット(Control Roomの「Tokens」:「Generate」から「OTLP」を選び、一度だけ表示される新しいトークン)]

Flutterアプリ

pubspec.yamlに2つのパッケージを追加します。2つは同時にリリースされ、常に同じバージョンです:

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に表示されます。誰が見てもわかる名前を付けてください。パッケージ名と同じである必要はありません。
  • app.build_idは、アプリのビルドを識別します。 Flutterのパッケージが、アプリのバージョンとビルド番号から自動で設定します(ビルドID)。クラッシュとリリースの比較は、この値でグループ化されます。
  • DartasticViewObserverは、ルートがプッシュされるたびに画面表示を記録し、各画面が開いていた時間も記録します。

エンドポイントとトークンは、--dart-defineでビルドに渡します。スマートフォンのアプリはシェルの環境変数を参照できないため、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が完了すると、追加のコードなしで次のものを記録します:

  • 訪問ごとのセッション。すべてのスパンとログレコードに付きます。
  • タップと、それに対するアプリの応答の速さ。
  • 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が付きます。それがAndroidでのFlutterのデフォルトのビルド番号だからです。すべてのプラットフォームで同じビルドIDにするには、バージョンにビルド番号を付けてください(1.4.0+27)。

Dartサーバー

Dartサーバーやコマンドラインアプリに必要なパッケージは1つだけです:

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

サーバーでは、同じ2つの変数を環境変数から取得します:

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で設定します)。
  • エラーを再スローしてよいのは、独自のハンドラーの中だけです。たとえば、テストビルドですぐに失敗させたい場合です。本番環境では、ログに記録してreturnしてください。

届いたことを確認

アプリを実行して1分ほど操作し、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の画面キャプチャはデフォルトで無効です。それぞれ環境変数で設定でき、アプリの実行中に変更できます。変更のタイミングはアプリが決め、セッターを呼び出します。リモートからの設定はありません。

シグナル環境変数アプリの実行中
トレース(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サンプラーがまだ保持しているスパンはすぐに新しいサンプラーを通るため、変更によって失われることはありません。
  • ログ: レートは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_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ページ(購入手続きやヘルプセンターなど)から、エラー、リクエスト、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以降)が必要で、ほかのプラットフォームでは何もしません。これがないと、これらのプラットフォームのページは、ページのスパンしか送信しません。
  • 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や地図など)へのタップは記録されますが、デッドタップやレイジタップとして数えられることはありません。