Uygulamanıza OTel ekleme
Dartastic OpenTelemetry'yi bir Flutter uygulamasına veya bir Dart sunucusuna üç adımda ekleyin: paketleri ekleyin, başlangıçta bir kez başlatın ve build'e OTLP endpoint'inizi ve token'ınızı verin. Trace'leriniz, loglarınız ve metrikleriniz Observatory'nize ulaşır.
Neye ihtiyacınız var
- Doğru Flutter ve Dart sürümleri. Her paketin neye ihtiyaç duyduğunu İlk uygulamanızı oluşturma sayfası listeler.
- Bir OTLP token'ı. Control Room'da “Tokens” ekranını açın, “Generate”, ardından “OTLP” seçeneğini seçin. Token yalnızca bir kez gösterilir: Parola yöneticinizde veya CI sırlarınızda saklayın. Flutter web için bunun yerine bir Browser OTLP token'ı kullanın (Browser OTLP).
- OTLP endpoint'iniz:
https://otlp.cloud.dartastic.io. - Paketler için Dartastic Pub erişimi: bir Pub token'ı ile
dart pub token add https://pub.dartastic.io.
Bir Flutter uygulaması
İki paketi pubspec.yaml dosyasına ekleyin. Birlikte yayımlanırlar ve aynı sürümde kalırlar:
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 çağrısından önce bir kez başlatın:
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, uygulamanızın adıdır ve Observatory'de bu adla görünür. İnsanların tanıyacağı bir ad seçin; paket adınız olması gerekmez.app.build_id, uygulamanızın build kimliğidir. Flutter paketi onu sizin için, uygulamanızın sürümünden ve build numarasından ayarlar (Build kimliğiniz). Çökmeler ve sürüm karşılaştırmaları ona göre gruplanır.DartasticViewObserver, bir route her push edildiğinde bir ekran görüntüleme ve her ekranın ne kadar süre açık kaldığını kaydeder.
Endpoint'inizi ve token'ınızı build'e --dart-define ile verin. Bir telefon uygulaması kabuğunuzun ortamını görmez; değerler ona define'lar aracılığıyla ulaşır. Token'ı kaynak kontrolünün dışında tutun: Onu makinenizde veya CI'da bir ortam değişkenine koyun ve onu aktarın.
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"Bunlar standart OpenTelemetry değişkenleridir. authorization adını küçük harfle yazın: Her protokolde çalışır. Bir OTLP token'ı yalnızca kuruluşunuza telemetri gönderebilir: Hiçbir şey okumaz ve hiçbir şeyi değiştirmez.
DOTel.initialize tamamlandıktan sonra, başka kod gerekmeden şunları kaydeder:
- her ziyaret için bir oturum, her span ve log kaydında;
- dokunmalar ve uygulamanın onlara ne kadar hızlı yanıt verdiği;
DartasticViewObserveraracılığıyla ekran görüntülemeler;- ve planınız içeriyorsa çökmeler, arayüz donmaları, jank ve temel metrikler.
Build kimliğiniz
Build kimliği, her platformun uygulamanız için bildirdiği sürüm ve build numarasından gelir:
| Uygulamanızın sürümü | Android | iOS |
|---|---|---|
pubspec.yaml içinde version: 1.4.0+27 | 1.4.0+27 | 1.4.0+27 |
pubspec.yaml içinde 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, build numarası olmayan bir sürüme +1 ekler, çünkü orada Flutter'ın varsayılan build numarası budur. Her platformda tek bir build kimliği için sürümünüze bir build numarası verin (1.4.0+27).
Bir Dart sunucusu
Bir Dart sunucusu veya komut satırı uygulaması tek bir pakete ihtiyaç duyar:
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 ...
}Bir sunucuda aynı iki değişken ortamdan gelir:
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 uygulamanızı asla bozmaz
OpenTelemetry'nin kuralı, telemetrinin çalışma zamanında kodunuza asla hata fırlatmamasıdır. Dartastic bu kurala her yerde uyar. Telemetrinin içinde bir şey ters gittiğinde (ulaşılamayan bir endpoint, hatalı değerli bir öznitelik, başarısız olan bir dışa aktarma), hata OpenTelemetry hata işleyicisine bildirilir ve loglanır; uygulamanız çalışmaya devam eder.
Bu bildirimleri kendi loglama veya çökme raporlama sisteminizde görmek için kendi işleyicinizi kurun. DOTel.initialize çağrısından önce veya sonra çağırmanız fark etmez:
// 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);
});- Bir işleyici olmadan hatalar OpenTelemetry'nin kendi loguyla loglanır (
OTEL_LOG_LEVELne kadar ayrıntı vereceğini belirler). - Kendi işleyiciniz, bir hatanın yeniden fırlatılabileceği tek yerdir; örneğin bir test build'inde hemen başarısız olmak için. Üretimde loglayın ve geri dönün.
Verilerin geldiğini görün
Uygulamanızı çalıştırıp bir dakika kullanın, ardından Observatory'nin “Traces” veya “Logs” ekranını açın: serviceName oradadır (Observatory).
| Ne görüyorsunuz | Ne yapmalı |
|---|---|
| Hiçbir şey gelmiyor | Endpoint'i kontrol edin. Bir kez --dart-define=OTEL_LOG_LEVEL=debug ile (sunucuda OTEL_LOG_LEVEL=debug ile) çalıştırın: Token'ınız uygulamaya ulaştığında log, değeri gizlenmiş olarak OTelEnv: Parsed 1 header(s) yazar. |
| Dışa aktarmalar 401 ile reddediliyor | Token yanlış, iptal edilmiş veya başka bir kuruluşa ya da dağıtıma ait. Bu kuruluşun Control Room'unda yeni bir OTLP token'ı oluşturun. |
| Flutter web hiçbir şey göndermiyor | Web, bir Browser OTLP token'ı ve bu token'da sitenizin origin'ini gerektirir (Browser OTLP). |
Ne kadar veri gönderirsiniz
Uygulamanızın gönderdikleri, Cloud'da da Dedicated'da da planınızın gelen veri kotasından sayılır (Fiyatlandırma). Trace'ler, metrikler ve loglar varsayılan olarak açıktır ve bunların hiçbiri ayarlanmadığında hiçbir şey örnekleme ile elenmez. RUM ekran yakalama varsayılan olarak kapalıdır. Her biri bir ortam değişkeniyle ayarlanabilir ve uygulamanız çalışırken değiştirilebilir. Ne zaman değiştireceğine uygulamanız karar verir ve setter'ı çağırır. Uzaktan ayar yoktur.
| Sinyal | Ortam değişkeni | Uygulamanız çalışırken |
|---|---|---|
| Trace'ler, Dart'ta | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Trace'ler, motorda | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Loglar | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metrikler | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| RUM ekran yakalama | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.setRumSampleRate() |
Telefonlarda ve web'de ortam değişkeni, build sırasında ayarlanan bir --dart-define değeridir. Koddaki bir değer ortam değişkenini geçersiz kılar, uygulamanız çalışırken yapılan bir değişiklik de ikisini birden. Hatalı bir değer adıyla birlikte OpenTelemetry hata işleyicisine gider ve geçerli olan ayar korunur.
- Trace'ler, motorda: bir değişiklik bir sonraki batch'te geçerli olur. Bir
tailörnekleyicisinin hâlâ tuttuğu span'lar hemen yeni örnekleyiciden geçer; bu yüzden bir değişiklik onları asla kaybetmez. - Loglar: oran 0,0 ile 1,0 arasındadır ve oturum bazında karar verilir; böylece bir oturum bütünüyle tutulur veya atılır, oranı yükseltmek yalnızca oturum ekler.
ERRORveya üstü bir kayıt her zaman gönderilir; böylece çökmeler ve ciddi ANR'ler her zaman ulaşır. Ekran görüntülemeler ve dokunmalar log kaydıdır; bu yüzden burada atılan bir oturumun zaman çizelgesinde bunların hiçbiri olmaz. - Metrikler: oran 0,0 ile 1,0 arasındadır ve dışa aktarma döngülerini seyreltir: 0,25'te periyodik dört döngüden biri gönderir. Kümülatif toplamlar doğru kalır.
DOTel.flushMetricsve kapatma her zaman gönderir; yalnızca hiçbir şey göndermeyen 0 hariç. - RUM ekran yakalama: oran 0,0 ile 1,0 arasındadır, oturum bazında karar verilir ve bir değişiklik hemen geçerli olur. Oranı yükseltmek yalnızca oturum ekler, düşürmek yalnızca oturum çıkarır. Yakalamanın kaydettiklerini kapsar: Oturumlar, ekranlar ve dokunmalar telemetridir ve oran onlara dokunmaz. Bir destek kaydı asla örnekleme ile elenmez. Oranı hem build hem de kodunuz ayarlıyorsa ikisi aynı olmalıdır; değilse yakalama 0 ile başlar. Yakalanan her oturumun ne kadar veri taşıdığı onun ayrıntı düzeyi ile belirlenir.
RUM ayrıntı düzeyi
Ayrıntı düzeyi, bir replay'in ekranın ne kadarını taşıdığıdır. Bir replay, sakladığı bayt kadar planınızın gelen veri kotasından sayılır; bu yüzden daha düşük bir düzey kotanın daha azını kullanır.
| Ayrıntı düzeyi | Bir replay ne gösterir | Bir dakika ne ekler |
|---|---|---|
| Events | Ekranlar, dokunmalar, ağ çağrıları, span'lar, hatalar ve çökmelerden oluşan zaman çizelgesi. Ekranın görüntüsü yok. | Replay baytı yok |
| Outline | Her ana öğe için bir dikdörtgen. Metin ve simge yok. | 62 KB |
| Wireframe | Metin, simgeler ve daha küçük kontroller de, her biri bir dikdörtgen olarak çizilir. Metin gri çubuklar olarak görünür ve hiçbir karakter cihazdan çıkmaz. | 81 KB |
| Shadow | Metin okunamasın diye bloklar halinde bulanıklaştırılmış gerçek bir ekran görüntüsü. | 430 KB |
| Pixel | Kullanıcının gördüğü haliyle gerçek ekran görüntüsü. | 597 KB |
| Pixel, yazılan metin gizli | Kullanıcıların yazdıklarının üzeri boyanmış ekran görüntüsü. | 516 KB |
| Pixel, tüm metin gizli | Tüm metnin üzeri boyanmış ekran görüntüsü. | 438 KB |
Kasım 2026'da Alpine Trails demo uygulamasında ölçülmüştür. Beş dakikalık bir Pixel oturumu yaklaşık 3 MB ekler. Uygulamanızın ekranları farklılık gösterir.
| Ayar | Ortam değişkeni | Uygulamanız çalışırken |
|---|---|---|
| Uygulamanızın düzeyi | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Tek bir ekranın düzeyi | Yok | setFidelity(level, route: '/checkout') |
| Bir build'in gönderebileceği en yüksek düzey | DARTASTIC_RUM_FIDELITY_MAX | Yok |
| Pixel düzeyinde gizlenen metin | Yok | ReplayCaptureController.setMasking() |
| Replay açık veya kapalı | Yok | ReplayCaptureController.setMode() |
Düzeyler şunlardır: events, outline, wireframe, shadow ve pixel. Buradaki her ortam değişkeni, build sırasında ayarlanan bir --dart-define değeridir.
- Uygulamanızın düzeyi: hem build hem de kodunuz ayarlıyorsa ikisi aynı olmalıdır. Aynı değilse veya bir değer geçerli bir düzey değilse yakalama bunu bildirir ve Events düzeyinde kalır. Bir destek kaydı düzeyi yükseltebilir; bir ekranda ayarlanmış daha düşük bir düzey o ekranda yine geçerli olur.
- En yüksek düzey: motor, uygulamanız veya bir kayıt ne isterse istesin, bu düzeyin üstündeki her replay kaydını atar. Bir build'i onaylamak için kullanın; örneğin piksel yakalayamayan bir build.
- Pixel düzeyinde gizlenen metin:
ReplayMasking.textFieldskullanıcıların yazdıklarını,ReplayMasking.allTextise tüm metni gizler. - Replay açık veya kapalı: uygulamanız bir mod ayarlayana kadar replay kapalıdır.
ReplayMode.bufferUntilTrigger, frame'leri cihazda tutar ve yalnızca bir şey ters gittiğinde yükler; böylece hiçbir şeyin bozulmadığı bir oturum hiç replay yüklemez.
Webview'lar
Uygulamanızın içindeki bir web sayfası (örneğin bir ödeme akışı veya bir yardım merkezi), hatalarını, isteklerini, Web Vitals metriklerini ve olaylarını dartastic.telemetry.source webview olarak işaretlenmiş şekilde uygulamanın oturumuna gönderebilir. Sayfa asla dışa aktarma yapmaz, token tutmaz ve endpoint görmez. Uygulamanıza post eder; uygulamanız her alanı kontrol eder ve uygulamanızın kendi işlem hattından gönderir. Webview telemetrisi bir Pro özelliğidir.
Güvendiğiniz host'ları adlandırın. Bir sayfa, bir girdinin tam host'u veya bir alt alan adıyla eşleşir; boş bir liste köprüyü kapalı tutar.
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);İzin verilen bir sayfanın gönderdiği her şey uygulamanızın telemetri kimlik bilgileriyle gider ve sunucuda hiçbir şey onu maskelemez. Sınırlamayı allowedHosts listeniz ve köprünün boyut sınırları sağlar.
webview_flutter ile (4.9.0 ve sonrası)
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 ile (6.1.5 ve sonrası)
Köprüde transport: DartasticWebviewTransport.inAppWebViewHandler ayarını yapın ve JavaScript'i açık bırakın.
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);
}
},
)Neler ulaşır
- iOS ve macOS:
shimForCommittedPage(1.32.0 ve sonrası) orada gereklidir, başka yerlerde hiçbir şey yapmaz. O olmadan, bu platformlardaki bir sayfa yalnızca kendi sayfa span'ını gönderir. - iOS ve macOS'ta webview_flutter: sayfa yüklenmeyi bitirmeden önceki hatalar ve istekler yakalanmaz; yüklenmeyi hiç bitirmeyen bir sayfa yalnızca span'ını gönderir. Tarayıcı onları arabelleğe aldığı için Web Vitals yine ulaşır. Bunlar önemliyse belgenin başından itibaren yakalayan flutter_inappwebview paketini kullanın.
- Web Vitals: TTFB ve FCP her yerde ulaşır. LCP, CLS, INP ve uzun görevler, platformun onları ölçtüğü yerde ulaşır. Android WebView dördünü de ölçer. iOS 27'de WKWebView CLS veya uzun görev bildirmez; LCP ve INP de orada doğrulanmamıştır. Köprü asla bir değer uydurmaz.
- Dokunmalar: bir platform görünümüne (örneğin bir webview veya bir harita) yapılan dokunma kaydedilir, ancak asla sonuçsuz veya öfkeli dokunma olarak sayılmaz.