Bu sayfalar Cloud'un URL'lerini gösterir. Dedicated'da giriş yapın, sayfalar sunucunuzun URL'lerini göstersin.

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.

GELİŞTİRMEDARTASTIC MİMARİSİKULLANICILARtoken'larissue'larPub token'ıpushCI token değişimiuygulamalar kullanıcılara ulaşır: uygulama mağazaları, web, sunucularsembollerçökmelerstack trace'lerkaynak kodtelemetriGeliştirici bilgisayarıflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomtoken oluşturma · rol tabanlı erişim denetimiControl Planekuruluşlar · roller · token'larDartastic Pubpaketler · kaynak kodObservatoryoturumlar · trace'ler · loglarSymbolizerçökmeler → kaynak kod satırlarıDartastic AIikisinden de beslenen yanıtlarIssue takip aracıGitHub · Jira · LinearMobil ve masaüstü uygulamalartelefonlar · tabletler · masaüstleriOTLP token'ı ile gönderirWeb uygulamalarıtarayıcılardaBrowser OTLP token'ı ile gönderirDart sunucularıbackend'ler · servislerOTLP token'ı ile gönderir

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.
[TODO: Control Room, “Tokens”: “Generate”, ardından “OTLP” ve yalnızca bir kez gösterilen yeni token ekran görüntüsü]

Bir Flutter uygulaması

İki paketi pubspec.yaml dosyasına ekleyin. Birlikte yayımlanırlar ve aynı sürümde kalırlar:

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 çağrısından önce bir kez başlatın:

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

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"

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;
  • DartasticViewObserver aracı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üAndroidiOS
pubspec.yaml içinde version: 1.4.0+271.4.0+271.4.0+27
pubspec.yaml içinde version: 1.4.01.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.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:

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

Bir sunucuda aynı iki değişken ortamdan gelir:

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 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:

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);
});
  • Bir işleyici olmadan hatalar OpenTelemetry'nin kendi loguyla loglanır (OTEL_LOG_LEVEL ne 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).

[TODO: uygulamanın ilk trace'ini gösteren Observatory “Traces” ekranı ekran görüntüsü]
Ne görüyorsunuzNe yapmalı
Hiçbir şey gelmiyorEndpoint'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 reddediliyorToken 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öndermiyorWeb, 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.

SinyalOrtam değişkeniUygulamanız çalışırken
Trace'ler, Dart'taOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Trace'ler, motordaDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LoglarDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MetriklerDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
RUM ekran yakalamaDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.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. ERROR veya ü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.flushMetrics ve 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üzeyiBir replay ne gösterirBir dakika ne ekler
EventsEkranlar, dokunmalar, ağ çağrıları, span'lar, hatalar ve çökmelerden oluşan zaman çizelgesi. Ekranın görüntüsü yok.Replay baytı yok
OutlineHer ana öğe için bir dikdörtgen. Metin ve simge yok.62 KB
WireframeMetin, 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
ShadowMetin okunamasın diye bloklar halinde bulanıklaştırılmış gerçek bir ekran görüntüsü.430 KB
PixelKullanıcının gördüğü haliyle gerçek ekran görüntüsü.597 KB
Pixel, yazılan metin gizliKullanıcıların yazdıklarının üzeri boyanmış ekran görüntüsü.516 KB
Pixel, tüm metin gizliTü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.

AyarOrtam değişkeniUygulamanız çalışırken
Uygulamanızın düzeyiDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Tek bir ekranın düzeyiYoksetFidelity(level, route: '/checkout')
Bir build'in gönderebileceği en yüksek düzeyDARTASTIC_RUM_FIDELITY_MAXYok
Pixel düzeyinde gizlenen metinYokReplayCaptureController.setMasking()
Replay açık veya kapalıYokReplayCaptureController.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.textFields kullanıcıların yazdıklarını, ReplayMasking.allText ise 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.

dart
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ı)

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 ile (6.1.5 ve sonrası)

Köprüde transport: DartasticWebviewTransport.inAppWebViewHandler ayarını yapın ve JavaScript'i açık bırakın.

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

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.