Te strony pokazują adresy URL Cloud. Po zalogowaniu się na Dedicated pokazują adresy własnego serwera: Zaloguj się.

Dodawanie OTel do aplikacji

Dartastic OpenTelemetry dodaje się do aplikacji Flutter lub serwera Dart w trzech krokach: dodanie pakietów, jednorazowa inicjalizacja przy starcie i przekazanie buildowi endpointu OTLP i tokenu. Trasy, logi i metryki trafiają wtedy do Observatory.

BUDOWANIEARCHITEKTURA DARTASTICUŻYTKOWNICYtokenyzgłoszeniatoken Pubpushwymiana w CIaplikacje trafiają do użytkowników: sklepy z aplikacjami, web, serwerysymboleawariestosy wywołańkod źródłowytelemetriaKomputer programistyflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomtworzenie tokenów · kontrola dostępu oparta na rolachPłaszczyzna sterowaniaorganizacje · role · tokenyDartastic Pubpakiety · kod źródłowyObservatorysesje · trasy · logiSymbolizerawarie → linie kodu źródłowegoDartastic AIodpowiedzi z obu źródełSystem zgłoszeńGitHub · Jira · LinearAplikacje mobilne i desktopowetelefony · tablety · komputerywysyła z tokenem OTLPAplikacje webowew przeglądarkachwysyła z tokenem Browser OTLPSerwery Dartbackendy · usługiwysyła z tokenem OTLP

Co jest potrzebne

  • Odpowiednie wersje Fluttera i Darta. Strona Tworzenie pierwszej aplikacji podaje, czego wymaga każdy pakiet.
  • Token OTLP. W Control Room należy otworzyć Tokens, wybrać Generate, a potem OTLP. Token jest pokazywany raz: należy przechować go w menedżerze haseł lub w sekretach CI. Dla Flutter Web należy zamiast niego użyć tokenu Browser OTLP (Browser OTLP).
  • Endpoint OTLP: https://otlp.cloud.dartastic.io.
  • Dostęp do Dartastic Pub dla pakietów: dart pub token add https://pub.dartastic.io z tokenem Pub.
[TODO: zrzut ekranu: Control Room, „Tokens”: „Generate”, potem „OTLP”, i nowy token pokazany raz]

Aplikacja Flutter

Należy dodać oba pakiety do pubspec.yaml. Są wydawane razem i zawsze mają tę samą wersję:

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

Inicjalizacja odbywa się raz, przed 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 to nazwa aplikacji w Observatory. Warto wybrać nazwę rozpoznawalną dla ludzi; nie musi to być nazwa pakietu.
  • app.build_id to tożsamość buildu aplikacji. Pakiet Flutter ustawia ją automatycznie na podstawie wersji i numeru buildu aplikacji (Identyfikator buildu). Awarie i porównania wersji są według niej grupowane.
  • DartasticViewObserver rejestruje wyświetlenie ekranu za każdym razem, gdy na stos nawigacji trafia nowa ścieżka, oraz czas, przez jaki każdy ekran był otwarty.

Endpoint i token przekazuje się buildowi przez --dart-define. Aplikacja na telefonie nie widzi środowiska powłoki, więc to właśnie definicje przekazują jej te wartości. Tokenu nie należy trzymać w systemie kontroli wersji: należy umieścić go w zmiennej środowiskowej na komputerze lub w CI i przekazać tę zmienną.

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"

To standardowe zmienne OpenTelemetry. authorization należy pisać małymi literami: tak działa w każdym protokole. Token OTLP może tylko wysyłać telemetrię do organizacji: niczego nie odczytuje i niczego nie zmienia.

Po zakończeniu DOTel.initialize bez dodatkowego kodu rejestrowane są:

  • sesja każdej wizyty, dołączana do każdego spanu i rekordu logu;
  • stuknięcia i to, jak szybko aplikacja na nie reaguje;
  • wyświetlenia ekranów, przez DartasticViewObserver;
  • oraz, jeśli obejmuje je plan, awarie, zamrożony interfejs, jank i wskaźniki vitals.

Identyfikator buildu

Identyfikator buildu pochodzi z wersji i numeru buildu, które każda platforma podaje dla aplikacji:

Wersja aplikacjiAndroidiOS
version: 1.4.0+27 w pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 w pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.4.0+27

Android dodaje +1 do wersji bez numeru buildu, bo to tam domyślny numer buildu Fluttera. Aby mieć jeden identyfikator buildu na każdej platformie, należy nadać wersji numer buildu (1.4.0+27).

Serwer Dart

Serwer Dart lub aplikacja wiersza poleceń potrzebuje tylko jednego pakietu:

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

Na serwerze te same dwie zmienne pochodzą ze środowiska:

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

Telemetria nigdy nie psuje aplikacji

Zasada OpenTelemetry mówi, że telemetria nie może nigdy rzucić błędu do kodu w runtime. Dartastic przestrzega jej wszędzie. Gdy coś pójdzie nie tak wewnątrz telemetrii (nieosiągalny endpoint, atrybut z błędną wartością, nieudany eksport), błąd trafia do handlera błędów OpenTelemetry i do logu, a aplikacja działa dalej.

Aby widzieć te zgłoszenia we własnym logowaniu lub raportowaniu awarii, należy zainstalować własny handler. Działa niezależnie od tego, czy zostanie wywołany przed DOTel.initialize, czy po nim:

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);
});
  • Bez własnego handlera błędy trafiają do logu samego OpenTelemetry (OTEL_LOG_LEVEL określa, ile w nim widać).
  • Własny handler to jedyne miejsce, w którym błąd może zostać rzucony ponownie, np. by szybko przerwać działanie w buildzie testowym. Na produkcji wystarczy zalogować błąd i wrócić.

Sprawdzenie, czy dane docierają

Należy uruchomić aplikację i używać jej przez minutę, a potem otworzyć „Traces” lub „Logs” w Observatory: serviceName już tam jest (Observatory).

[TODO: zrzut ekranu: ekran „Traces” w Observatory z pierwszą trasą aplikacji]
Co widaćCo zrobić
Nic nie docieraNależy sprawdzić endpoint. Warto uruchomić aplikację raz z --dart-define=OTEL_LOG_LEVEL=debug (lub OTEL_LOG_LEVEL=debug na serwerze): log pokazuje OTelEnv: Parsed 1 header(s), gdy token dotarł do aplikacji, z ukrytą wartością.
Eksporty odrzucane z kodem 401Token jest błędny, odwołany albo pochodzi z innej organizacji lub wdrożenia. Należy wygenerować nowy token OTLP w Control Room tej organizacji.
Flutter Web nic nie wysyłaWeb wymaga tokenu Browser OTLP z dodanym do niego originem witryny (Browser OTLP).

Ile się wysyła

To, co wysyła aplikacja, wlicza się do ruchu przychodzącego planu, zarówno w Cloud, jak i w Dedicated (Cennik). Trasy, metryki i logi są domyślnie włączone, a bez żadnego z tych ustawień próbkowanie niczego nie odrzuca. Przechwytywanie ekranu RUM jest domyślnie wyłączone. Każde z nich można ustawić zmienną środowiskową i zmienić w trakcie działania aplikacji. To aplikacja decyduje, kiedy coś zmienić, i wywołuje setter. Nie ma ustawienia zdalnego.

SygnałZmienna środowiskowaW trakcie działania aplikacji
Trasy (Dart)OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Trasy (silnik)DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogiDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MetrykiDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Przechwytywanie ekranu RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.setRumSampleRate()

Na telefonach i w przeglądarce zmienna środowiskowa to --dart-define, ustawiany przy budowaniu. Wartość w kodzie ma pierwszeństwo przed zmienną środowiskową, a zmiana w trakcie działania aplikacji przed obiema. Błędna wartość trafia, wraz z nazwą, do handlera błędów OpenTelemetry, a dotychczasowe ustawienie pozostaje w mocy.

  • Trasy w silniku: zmiana obowiązuje od następnej partii. Spany, które sampler tail jeszcze przechowuje, od razu przechodzą przez nowy sampler, więc zmiana nigdy ich nie gubi.
  • Logi: współczynnik wynosi od 0,0 do 1,0 i jest ustalany dla sesji, więc sesja jest zachowywana lub odrzucana w całości, a podniesienie współczynnika tylko dodaje sesje. Rekord na poziomie ERROR lub wyższym jest wysyłany zawsze, więc awarie i poważne ANR zawsze docierają. Wyświetlenia ekranów i stuknięcia to rekordy logu, więc sesja odrzucona tutaj nie ma ich na swojej osi czasu.
  • Metryki: współczynnik wynosi od 0,0 do 1,0 i rozrzedza cykle eksportu: przy 0,25 wysyłany jest co czwarty cykl okresowy. Sumy skumulowane pozostają poprawne. DOTel.flushMetrics i zamknięcie zawsze wysyłają dane, poza wartością 0, przy której nic nie jest wysyłane.
  • Przechwytywanie ekranu RUM: współczynnik wynosi od 0,0 do 1,0, jest ustalany dla sesji, a zmiana obowiązuje od razu. Podniesienie go tylko dodaje sesje, a obniżenie tylko je usuwa. Dotyczy tego, co rejestruje przechwytywanie: sesje, ekrany i stuknięcia to telemetria, której nie zmienia. Nagranie dla wsparcia nigdy nie jest odrzucane przez próbkowanie. Jeśli współczynnik ustawiają zarówno build, jak i kod, wartości muszą być zgodne, inaczej przechwytywanie startuje od 0. Ilość danych w każdej przechwyconej sesji określa jej szczegółowość.

Szczegółowość RUM

Szczegółowość określa, jak dużo ekranu zawiera nagranie. Nagranie wlicza się do ruchu przychodzącego planu według liczby zapisanych bajtów, więc niższy poziom zużywa go mniej.

SzczegółowośćCo pokazuje nagranieMinuta dodaje
EventsOś czasu ekranów, stuknięć, wywołań sieciowych, spanów, błędów i awarii. Bez obrazu ekranu.Brak danych nagrania
OutlineProstokąt dla każdego głównego elementu. Bez tekstu i bez ikon.62 KB
WireframeTakże tekst, ikony i mniejsze kontrolki, każdy element jako prostokąt. Tekst jest pokazywany jako szare paski, a żadne znaki nie opuszczają urządzenia.81 KB
ShadowPrawdziwy zrzut ekranu, rozmyty w bloki tak, że tekstu nie da się odczytać.430 KB
PixelPrawdziwy zrzut ekranu, taki, jaki widział użytkownik.597 KB
Pixel, wpisywany tekst ukrytyZrzut ekranu z zamalowanym tekstem wpisywanym przez użytkowników.516 KB
Pixel, cały tekst ukrytyZrzut ekranu z zamalowanym całym tekstem.438 KB

Pomiar w aplikacji demonstracyjnej Alpine Trails w listopadzie 2026 r. Pięciominutowa sesja na poziomie Pixel to ok. 3 MB więcej. Ekrany każdej aplikacji dają inne wyniki.

UstawienieZmienna środowiskowaW trakcie działania aplikacji
Poziom aplikacjiDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Poziom jednego ekranuBraksetFidelity(level, route: '/checkout')
Najwyższy poziom, jaki może wysłać buildDARTASTIC_RUM_FIDELITY_MAXBrak
Tekst ukrywany na poziomie PixelBrakReplayCaptureController.setMasking()
Odtwarzanie włączone lub wyłączoneBrakReplayCaptureController.setMode()

Poziomy to events, outline, wireframe, shadow i pixel. Każda zmienna środowiskowa tutaj to --dart-define, ustawiany przy budowaniu.

  • Poziom aplikacji: jeśli ustawiają go zarówno build, jak i kod, wartości muszą być zgodne. Jeśli nie są albo wartość nie jest poziomem, przechwytywanie zgłasza to i pozostaje na poziomie Events. Nagranie dla wsparcia może podnieść poziom, a niższe ustawienie na danym ekranie nadal na nim obowiązuje.
  • Najwyższy poziom: silnik odrzuca każdy rekord nagrania powyżej niego, niezależnie od tego, o co prosi aplikacja lub nagranie. Służy do certyfikacji buildu, np. takiego, który nie może przechwytywać pikseli.
  • Tekst ukrywany na poziomie Pixel: ReplayMasking.textFields ukrywa to, co wpisują użytkownicy, a ReplayMasking.allText ukrywa cały tekst.
  • Odtwarzanie włączone lub wyłączone: odtwarzanie jest wyłączone, dopóki aplikacja nie ustawi trybu. ReplayMode.bufferUntilTrigger przechowuje klatki na urządzeniu i wysyła je tylko wtedy, gdy coś pójdzie nie tak, więc sesja, w której nic się nie psuje, nie wysyła żadnego nagrania.

Webview

Strona internetowa wewnątrz aplikacji, np. proces płatności albo centrum pomocy, może wysyłać swoje błędy, żądania, wskaźniki Web Vitals i zdarzenia do sesji aplikacji, oznaczone dartastic.telemetry.source webview. Strona nigdy nie eksportuje danych, nie przechowuje tokenu ani nie widzi endpointu. Przekazuje dane aplikacji, która sprawdza każde pole i wysyła je własnym potokiem aplikacji. Telemetria z webview to funkcja Pro.

Należy wymienić zaufane hosty. Strona pasuje, gdy jej host jest dokładnie równy wpisowi albo jest subdomeną wpisu, a pusta lista wyłącza most.

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

Wszystko, co wyśle dozwolona strona, korzysta z danych uwierzytelniających telemetrii aplikacji i nic tego nie maskuje na serwerze. Zabezpieczeniem są lista allowedHosts i limity rozmiaru mostu.

Z webview_flutter (4.9.0 i nowsze)

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

Z flutter_inappwebview (6.1.5 i nowsze)

Na moście należy ustawić transport: DartasticWebviewTransport.inAppWebViewHandler i pozostawić włączony 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);
    }
  },
)

Co dociera

  • iOS i macOS: shimForCommittedPage (1.32.0 i nowsze) jest tam wymagany, a na innych platformach nic nie robi. Bez niego strona na tych platformach wysyła tylko swój span strony.
  • webview_flutter na iOS i macOS: błędy i żądania sprzed zakończenia ładowania strony nie są przechwytywane, a strona, która nigdy nie kończy ładowania, wysyła tylko swój span. Wskaźniki vitals nadal docierają, bo przeglądarka je buforuje. Gdy są ważne, należy użyć flutter_inappwebview, który przechwytuje od początku dokumentu.
  • Web Vitals: TTFB i FCP docierają wszędzie. LCP, CLS, INP i długie zadania docierają tam, gdzie mierzy je platforma. Android WebView mierzy wszystkie cztery. W iOS 27 WKWebView nie zgłasza CLS ani długich zadań, a LCP i INP nie są tam potwierdzone. Most nigdy nie wymyśla wartości.
  • Stuknięcia: stuknięcie w widok platformy, np. webview lub mapę, jest rejestrowane, ale nigdy nie jest liczone jako martwe stuknięcie ani stuknięcie z frustracji.