Halaman ini menampilkan URL Cloud. Masuk di Dedicated, lalu halaman ini menampilkan URL server Anda.

Menambahkan OTel ke aplikasi Anda

Tambahkan Dartastic OpenTelemetry ke aplikasi Flutter atau server Dart dalam tiga langkah: tambahkan package, lakukan inisialisasi sekali saat startup, dan berikan endpoint dan token OTLP Anda ke build. Trace, log, dan metrik Anda tiba di Observatory Anda.

BUILDARSITEKTUR DARTASTICPENGGUNAtokentikettoken Pubpushpertukaran CIaplikasi sampai ke pengguna: toko aplikasi, web, serversimbolcrashstack tracekode sumbertelemetriKomputer developerflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roombuat token · kontrol akses berbasis peranControl Planeorganisasi · peran · tokenDartastic Pubpackage · kode sumberObservatorysesi · trace · logSymbolizercrash → baris kode sumberDartastic AIjawaban dari keduanyaIssue trackerGitHub · Jira · LinearAplikasi seluler + desktopponsel · tablet · desktopmengirim dengan token OTLPAplikasi webdi browsermengirim dengan token Browser OTLPServer Dartbackend · layananmengirim dengan token OTLP

Yang Anda butuhkan

  • Versi Flutter dan Dart yang tepat. Membangun aplikasi pertama Anda mencantumkan apa yang dibutuhkan setiap package.
  • Token OTLP. Di Control Room, buka Tokens, pilih Generate, lalu OTLP. Token ditampilkan sekali: simpan di pengelola sandi atau secret CI Anda. Untuk Flutter web, gunakan token Browser OTLP sebagai gantinya (Browser OTLP).
  • Endpoint OTLP Anda: https://otlp.cloud.dartastic.io.
  • Akses ke Dartastic Pub untuk package-nya: dart pub token add https://pub.dartastic.io dengan token Pub.
[TODO: screenshot Control Room, “Tokens”: “Generate”, lalu “OTLP”, dan token baru yang ditampilkan sekali]

Aplikasi Flutter

Tambahkan dua package ke pubspec.yaml. Keduanya dirilis bersamaan dan selalu berada di versi yang sama:

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

Lakukan inisialisasi sekali, sebelum 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 memberi nama aplikasi Anda di Observatory. Pilih nama yang mudah dikenali; tidak harus sama dengan nama package Anda.
  • app.build_id adalah identitas build aplikasi Anda. Package Flutter mengaturnya untuk Anda, dari versi dan nomor build aplikasi Anda (Build ID Anda). Crash dan perbandingan release dikelompokkan berdasarkan nilai ini.
  • DartasticViewObserver mencatat tampilan layar setiap kali sebuah route dibuka (push), dan berapa lama setiap layar terbuka.

Berikan endpoint dan token Anda ke build dengan --dart-define. Aplikasi ponsel tidak melihat environment shell Anda, jadi define adalah cara nilai-nilai itu sampai ke aplikasi. Jauhkan token dari source control: simpan di variabel lingkungan di komputer Anda atau di CI, lalu teruskan variabel itu.

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"

Ini adalah variabel standar OpenTelemetry. Tulis authorization dengan huruf kecil: cara ini berfungsi untuk setiap protokol. Token OTLP hanya dapat mengirim telemetri ke organisasi Anda: token ini tidak membaca dan tidak mengubah apa pun.

Setelah DOTel.initialize selesai, aplikasi mencatat tanpa kode tambahan:

  • sesi untuk setiap kunjungan, pada setiap span dan catatan log;
  • ketukan, dan seberapa cepat aplikasi meresponsnya;
  • tampilan layar, melalui DartasticViewObserver;
  • dan, sesuai yang termasuk dalam paket Anda, crash, UI yang membeku, jank, dan metrik vital.

Build ID Anda

Build ID berasal dari versi dan nomor build yang dilaporkan setiap platform untuk aplikasi Anda:

Versi aplikasi AndaAndroidiOS
version: 1.4.0+27 di pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 di pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.4.0+27

Android menambahkan +1 ke versi tanpa nomor build, karena itulah nomor build default Flutter di sana. Agar build ID sama di setiap platform, beri versi Anda nomor build (1.4.0+27).

Server Dart

Server Dart atau aplikasi command line hanya membutuhkan satu 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 ...
}

Di server, kedua variabel yang sama berasal dari environment:

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

Telemetri tidak pernah merusak aplikasi Anda

Aturan OpenTelemetry adalah telemetri tidak boleh melempar error ke kode Anda saat runtime. Dartastic mengikutinya di mana saja. Saat terjadi masalah di dalam telemetri (endpoint yang tidak dapat dijangkau, atribut dengan nilai yang salah, ekspor yang gagal), error dilaporkan ke error handler OpenTelemetry dan dicatat ke log, dan aplikasi Anda tetap berjalan.

Untuk melihat laporan tersebut di sistem logging atau pelaporan crash Anda sendiri, pasang handler Anda sendiri. Handler ini berfungsi baik dipanggil sebelum maupun sesudah 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);
});
  • Tanpa handler, error dicatat dengan log OpenTelemetry sendiri (OTEL_LOG_LEVEL mengatur seberapa banyak yang ditulisnya).
  • Handler milik Anda sendiri adalah satu-satunya tempat error boleh dilempar ulang, misalnya untuk langsung gagal di build pengujian. Di produksi, catat ke log lalu kembalikan.

Lihat datanya tiba

Jalankan aplikasi Anda dan gunakan selama satu menit, lalu buka “Traces” atau “Logs” di Observatory: serviceName Anda ada di sana (Observatory).

[TODO: screenshot layar “Traces” di Observatory yang menampilkan trace pertama aplikasi]
Yang Anda lihatYang perlu dilakukan
Tidak ada yang tibaPeriksa endpoint. Jalankan sekali dengan --dart-define=OTEL_LOG_LEVEL=debug (atau OTEL_LOG_LEVEL=debug di server): log menampilkan OTelEnv: Parsed 1 header(s) saat token Anda sampai ke aplikasi, dengan nilainya disembunyikan.
Ekspor ditolak dengan 401Token salah, dicabut, atau berasal dari organisasi atau deployment lain. Buat token OTLP baru di Control Room organisasi ini.
Flutter web tidak mengirim apa punWeb membutuhkan token Browser OTLP dengan origin situs Anda terdaftar di dalamnya (Browser OTLP).

Seberapa banyak yang Anda kirim

Apa yang dikirim aplikasi Anda dihitung sebagai data masuk paket Anda, baik di Cloud maupun Dedicated (Harga). Trace, metrik, dan log aktif secara default, dan jika tidak ada yang diatur, tidak ada yang dibuang oleh sampling. Perekaman layar RUM nonaktif secara default. Masing-masing dapat diatur dengan variabel lingkungan dan diubah saat aplikasi Anda berjalan. Aplikasi Anda yang memutuskan kapan mengubahnya, lalu memanggil setter-nya. Tidak ada pengaturan jarak jauh.

SinyalVariabel lingkunganSaat aplikasi berjalan
Trace, di DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Trace, di engineDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MetrikDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Perekaman layar RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.setRumSampleRate()

Di ponsel dan web, variabel lingkungan adalah --dart-define yang diatur saat build. Nilai di kode mengalahkan variabel lingkungan, dan perubahan saat aplikasi berjalan mengalahkan keduanya. Nilai yang salah dilaporkan ke error handler OpenTelemetry beserta namanya, dan nilai yang berlaku sebelumnya tetap dipakai.

  • Trace, di engine: perubahan berlaku pada batch berikutnya. Span yang masih ditahan sampler tail langsung melewati sampler baru, jadi perubahan tidak pernah menghilangkannya.
  • Log: tingkatnya 0.0 hingga 1.0, ditentukan per sesi, jadi sebuah sesi disimpan atau dibuang secara utuh, dan menaikkan tingkatnya hanya menambah sesi. Catatan dengan tingkat ERROR atau lebih tinggi selalu dikirim, jadi crash dan ANR yang parah selalu tiba. Tampilan layar dan ketukan adalah catatan log, jadi sesi yang dibuang di sini tidak memilikinya di linimasa.
  • Metrik: tingkatnya 0.0 hingga 1.0 dan menjarangkan siklus ekspor: pada 0.25, satu dari empat siklus berkala yang mengirim. Total kumulatif tetap benar. DOTel.flushMetrics dan shutdown selalu mengirim, kecuali pada 0, yang tidak mengirim apa pun.
  • Perekaman layar RUM: tingkatnya 0.0 hingga 1.0, ditentukan per sesi, dan perubahan langsung berlaku. Menaikkannya hanya menambah sesi, dan menurunkannya hanya mengurangi sesi. Ini mencakup apa yang direkam oleh perekaman: sesi, layar, dan ketukan adalah telemetri, dan tidak terpengaruh olehnya. Rekaman untuk dukungan tidak pernah dibuang oleh sampling. Jika build dan kode Anda sama-sama mengatur tingkatnya, keduanya harus sama, atau perekaman dimulai pada 0. Seberapa banyak isi setiap sesi yang direkam ditentukan oleh fidelitas.

Fidelitas RUM

Fidelitas adalah seberapa banyak isi layar yang dibawa sebuah replay. Replay dihitung sebagai data masuk paket Anda berdasarkan byte yang disimpannya, jadi level yang lebih rendah memakai lebih sedikit.

FidelitasYang ditampilkan replayTambahan per menit
EventsLinimasa layar, ketukan, panggilan jaringan, span, error, dan crash. Tanpa gambar layar.Tanpa byte replay
OutlineKotak untuk setiap elemen utama. Tanpa teks dan tanpa ikon.62 KB
WireframeTeks, ikon, dan kontrol yang lebih kecil juga, masing-masing digambar sebagai kotak. Teks ditampilkan sebagai batang abu-abu, dan tidak ada karakter yang meninggalkan perangkat.81 KB
ShadowScreenshot asli yang diburamkan menjadi blok-blok sehingga teks tidak dapat dibaca.430 KB
PixelScreenshot asli, seperti yang dilihat pengguna.597 KB
Pixel, teks yang diketik disembunyikanScreenshot, dengan apa yang diketik pengguna ditutupi.516 KB
Pixel, semua teks disembunyikanScreenshot, dengan semua teks ditutupi.438 KB

Diukur pada aplikasi demo Alpine Trails pada November 2026. Sesi Pixel selama lima menit menambah sekitar 3 MB. Hasil untuk layar aplikasi Anda bisa berbeda.

PengaturanVariabel lingkunganSaat aplikasi berjalan
Level aplikasi AndaDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Level satu layarTidak adasetFidelity(level, route: '/checkout')
Level tertinggi yang boleh dikirim buildDARTASTIC_RUM_FIDELITY_MAXTidak ada
Teks yang disembunyikan di PixelTidak adaReplayCaptureController.setMasking()
Replay aktif atau nonaktifTidak adaReplayCaptureController.setMode()

Level-levelnya adalah events, outline, wireframe, shadow, dan pixel. Setiap variabel lingkungan di sini adalah --dart-define yang diatur saat build.

  • Level aplikasi Anda: jika build dan kode Anda sama-sama mengaturnya, keduanya harus sama. Jika tidak, atau jika sebuah nilai bukan level yang valid, perekaman melaporkannya dan tetap di Events. Rekaman untuk dukungan dapat menaikkan level, dan pengaturan yang lebih rendah pada sebuah layar tetap berlaku di layar itu.
  • Level tertinggi: engine membuang setiap catatan replay di atas level ini, apa pun yang diminta aplikasi Anda atau sebuah rekaman. Gunakan untuk menyertifikasi build, misalnya build yang tidak dapat merekam piksel.
  • Teks yang disembunyikan di Pixel: ReplayMasking.textFields menyembunyikan apa yang diketik pengguna, dan ReplayMasking.allText menyembunyikan semua teks.
  • Replay aktif atau nonaktif: replay nonaktif sampai aplikasi Anda mengatur mode. ReplayMode.bufferUntilTrigger menyimpan frame di perangkat dan hanya mengunggahnya saat terjadi masalah, jadi sesi yang berjalan tanpa masalah sama sekali tidak mengunggah replay.

Webview

Halaman web di dalam aplikasi Anda, seperti checkout atau pusat bantuan, dapat mengirim error, permintaan, web vitals, dan event-nya ke sesi aplikasi, dengan tanda dartastic.telemetry.source webview. Halaman itu tidak pernah melakukan ekspor, memegang token, atau melihat endpoint. Halaman mengirimkannya ke aplikasi Anda, yang memeriksa setiap field dan meneruskannya melalui pipeline aplikasi Anda sendiri. Telemetri webview adalah fitur Pro.

Sebutkan host yang Anda percayai. Sebuah halaman cocok jika host-nya sama persis atau merupakan subdomain dari salah satu entri, dan daftar kosong membuat bridge tetap nonaktif.

dart
final bridge = DartasticWebviewBridge(
  allowedHosts: ['checkout.example.com', 'example.com'],
  serviceName: 'web-checkout',
  transport: DartasticWebviewTransport.javaScriptChannel,
);

Apa pun yang dikirim halaman yang diizinkan memakai kredensial telemetri aplikasi Anda, dan tidak ada yang menyamarkannya di server. Daftar allowedHosts Anda dan batas ukuran bridge adalah pembatasnya.

Dengan webview_flutter (4.9.0 dan yang lebih baru)

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

Dengan flutter_inappwebview (6.1.5 dan yang lebih baru)

Atur transport: DartasticWebviewTransport.inAppWebViewHandler pada bridge, dan biarkan JavaScript tetap aktif.

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

Yang tiba

  • iOS dan macOS: shimForCommittedPage (1.32.0 dan yang lebih baru) wajib di sana, dan tidak berpengaruh di platform lain. Tanpanya, halaman di platform tersebut hanya mengirim span halamannya.
  • webview_flutter di iOS dan macOS: error dan permintaan dari sebelum halaman selesai dimuat tidak terekam, dan halaman yang tidak pernah selesai dimuat hanya mengirim span-nya. Metrik vital tetap tiba, karena browser menyimpannya di buffer. Jika hal itu penting, gunakan flutter_inappwebview, yang merekam sejak dokumen mulai dimuat.
  • Web vitals: TTFB dan FCP tiba di semua platform. LCP, CLS, INP, dan long task tiba di platform yang mengukurnya. Android WebView mengukur keempatnya. Di iOS 27, WKWebView tidak melaporkan CLS atau long task, dan LCP serta INP belum terkonfirmasi di sana. Bridge tidak pernah mengarang nilai.
  • Ketukan: ketukan pada platform view, seperti webview atau peta, dicatat tetapi tidak pernah dihitung sebagai ketukan tanpa efek atau ketukan kesal.