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.
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.iodengan token Pub.
Aplikasi Flutter
Tambahkan dua package ke pubspec.yaml. Keduanya dirilis bersamaan dan selalu berada di versi yang sama:
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.4Lakukan inisialisasi sekali, sebelum 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(),
));
}serviceNamememberi nama aplikasi Anda di Observatory. Pilih nama yang mudah dikenali; tidak harus sama dengan nama package Anda.app.build_idadalah 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.DartasticViewObservermencatat 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.
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 Anda | Android | iOS |
|---|---|---|
version: 1.4.0+27 di pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 di pubspec.yaml | 1.4.0+1 | 1.4.0 |
--build-name=1.4.0 --build-number=27 | 1.4.0+27 | 1.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:
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 ...
}Di server, kedua variabel yang sama berasal dari environment:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dartTelemetri 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:
// 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_LEVELmengatur 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).
| Yang Anda lihat | Yang perlu dilakukan |
|---|---|
| Tidak ada yang tiba | Periksa 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 401 | Token salah, dicabut, atau berasal dari organisasi atau deployment lain. Buat token OTLP baru di Control Room organisasi ini. |
| Flutter web tidak mengirim apa pun | Web 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.
| Sinyal | Variabel lingkungan | Saat aplikasi berjalan |
|---|---|---|
| Trace, di Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Trace, di engine | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Log | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metrik | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Perekaman layar RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.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
taillangsung 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
ERRORatau 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.flushMetricsdan 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.
| Fidelitas | Yang ditampilkan replay | Tambahan per menit |
|---|---|---|
| Events | Linimasa layar, ketukan, panggilan jaringan, span, error, dan crash. Tanpa gambar layar. | Tanpa byte replay |
| Outline | Kotak untuk setiap elemen utama. Tanpa teks dan tanpa ikon. | 62 KB |
| Wireframe | Teks, 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 |
| Shadow | Screenshot asli yang diburamkan menjadi blok-blok sehingga teks tidak dapat dibaca. | 430 KB |
| Pixel | Screenshot asli, seperti yang dilihat pengguna. | 597 KB |
| Pixel, teks yang diketik disembunyikan | Screenshot, dengan apa yang diketik pengguna ditutupi. | 516 KB |
| Pixel, semua teks disembunyikan | Screenshot, 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.
| Pengaturan | Variabel lingkungan | Saat aplikasi berjalan |
|---|---|---|
| Level aplikasi Anda | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Level satu layar | Tidak ada | setFidelity(level, route: '/checkout') |
| Level tertinggi yang boleh dikirim build | DARTASTIC_RUM_FIDELITY_MAX | Tidak ada |
| Teks yang disembunyikan di Pixel | Tidak ada | ReplayCaptureController.setMasking() |
| Replay aktif atau nonaktif | Tidak ada | ReplayCaptureController.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.textFieldsmenyembunyikan apa yang diketik pengguna, danReplayMasking.allTextmenyembunyikan semua teks. - Replay aktif atau nonaktif: replay nonaktif sampai aplikasi Anda mengatur mode.
ReplayMode.bufferUntilTriggermenyimpan 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.
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)
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.
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.