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.
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.ioz tokenem Pub.
Aplikacja Flutter
Należy dodać oba pakiety do pubspec.yaml. Są wydawane razem i zawsze mają tę samą wersję:
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.4Inicjalizacja odbywa się raz, przed 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(),
));
}serviceNameto nazwa aplikacji w Observatory. Warto wybrać nazwę rozpoznawalną dla ludzi; nie musi to być nazwa pakietu.app.build_idto 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.DartasticViewObserverrejestruje 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ą.
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 aplikacji | Android | iOS |
|---|---|---|
version: 1.4.0+27 w pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 w 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 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:
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 ...
}Na serwerze te same dwie zmienne pochodzą ze środowiska:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dartTelemetria 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:
// 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_LEVELokreś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).
| Co widać | Co zrobić |
|---|---|
| Nic nie dociera | Należ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 401 | Token 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ła | Web 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 środowiskowa | W trakcie działania aplikacji |
|---|---|---|
| Trasy (Dart) | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Trasy (silnik) | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Logi | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metryki | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Przechwytywanie ekranu RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.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
tailjeszcze 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
ERRORlub 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.flushMetricsi 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 nagranie | Minuta dodaje |
|---|---|---|
| Events | Oś czasu ekranów, stuknięć, wywołań sieciowych, spanów, błędów i awarii. Bez obrazu ekranu. | Brak danych nagrania |
| Outline | Prostokąt dla każdego głównego elementu. Bez tekstu i bez ikon. | 62 KB |
| Wireframe | Takż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 |
| Shadow | Prawdziwy zrzut ekranu, rozmyty w bloki tak, że tekstu nie da się odczytać. | 430 KB |
| Pixel | Prawdziwy zrzut ekranu, taki, jaki widział użytkownik. | 597 KB |
| Pixel, wpisywany tekst ukryty | Zrzut ekranu z zamalowanym tekstem wpisywanym przez użytkowników. | 516 KB |
| Pixel, cały tekst ukryty | Zrzut 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.
| Ustawienie | Zmienna środowiskowa | W trakcie działania aplikacji |
|---|---|---|
| Poziom aplikacji | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Poziom jednego ekranu | Brak | setFidelity(level, route: '/checkout') |
| Najwyższy poziom, jaki może wysłać build | DARTASTIC_RUM_FIDELITY_MAX | Brak |
| Tekst ukrywany na poziomie Pixel | Brak | ReplayCaptureController.setMasking() |
| Odtwarzanie włączone lub wyłączone | Brak | ReplayCaptureController.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.textFieldsukrywa to, co wpisują użytkownicy, aReplayMasking.allTextukrywa cały tekst. - Odtwarzanie włączone lub wyłączone: odtwarzanie jest wyłączone, dopóki aplikacja nie ustawi trybu.
ReplayMode.bufferUntilTriggerprzechowuje 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.
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)
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.
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.