OTel zu Ihrer App hinzufügen
Fügen Sie Dartastic OpenTelemetry in drei Schritten zu einer Flutter-App oder einem Dart-Server hinzu: Packages hinzufügen, einmal beim Start initialisieren und dem Build Ihren OTLP-Endpunkt und Ihr Token mitgeben. Ihre Traces, Logs und Metriken kommen in Ihrem Observatory an.
Was Sie brauchen
- Die passenden Flutter- und Dart-Versionen. Ihre erste App erstellen führt auf, was jedes Package braucht.
- Ein OTLP-Token. Öffnen Sie im Control Room Tokens, wählen Sie Generate und dann OTLP. Es wird nur einmal angezeigt: Bewahren Sie es in Ihrem Passwortmanager oder in den Secrets Ihrer CI auf. Für Flutter Web verwenden Sie stattdessen ein Browser-OTLP-Token (Browser OTLP).
- Ihr OTLP-Endpunkt:
https://otlp.cloud.dartastic.io. - Zugriff auf Dartastic Pub für die Packages:
dart pub token add https://pub.dartastic.iomit einem Pub-Token.
Eine Flutter-App
Fügen Sie die beiden Packages zu pubspec.yaml hinzu. Sie werden gemeinsam veröffentlicht und haben immer dieselbe Version:
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.4Initialisieren Sie einmal, vor 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(),
));
}serviceNamebenennt Ihre App im Observatory. Wählen Sie einen Namen, den Menschen wiedererkennen; er muss nicht Ihr Package-Name sein.app.build_idist die Build-Identität Ihrer App. Das Flutter-Package setzt sie für Sie, aus der Version und der Build-Nummer Ihrer App (Ihre Build-ID). Abstürze und Release-Vergleiche werden danach gruppiert.DartasticViewObserverzeichnet bei jedem Push einer Route einen Bildschirmaufruf auf und misst, wie lange jeder Bildschirm geöffnet war.
Geben Sie dem Build Ihren Endpunkt und Ihr Token mit --dart-define mit. Eine Smartphone-App sieht die Umgebung Ihrer Shell nicht, daher gelangen die Werte über die Defines in die App. Halten Sie das Token aus der Versionsverwaltung heraus: Legen Sie es auf Ihrem Rechner oder in der CI in einer Umgebungsvariablen ab und übergeben Sie diese.
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"Das sind die Standardvariablen von OpenTelemetry. Schreiben Sie authorization klein: So funktioniert es mit jedem Protokoll. Ein OTLP-Token kann nur Telemetrie an Ihre Organisation senden: Es liest nichts und ändert nichts.
Sobald DOTel.initialize abgeschlossen ist, zeichnet es ohne weiteren Code auf:
- eine Sitzung für jeden Besuch, an jedem Span und jedem Log-Eintrag;
- Taps und wie schnell die App darauf reagiert;
- Bildschirmaufrufe, über
DartasticViewObserver; - und, soweit Ihr Tarif sie umfasst, Abstürze, eingefrorene UI, Jank und Vitalmetriken.
Ihre Build-ID
Die Build-ID ergibt sich aus der Version und der Build-Nummer, die jede Plattform für Ihre App meldet:
| Version Ihrer App | Android | iOS |
|---|---|---|
version: 1.4.0+27 in pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 in 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 ergänzt eine Version ohne Build-Nummer um +1, weil das dort die Standard-Build-Nummer von Flutter ist. Für eine einheitliche Build-ID auf jeder Plattform geben Sie Ihrer Version eine Build-Nummer (1.4.0+27).
Ein Dart-Server
Ein Dart-Server oder eine Kommandozeilen-App braucht nur das eine 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 ...
}Auf einem Server kommen dieselben beiden Variablen aus der Umgebung:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dartTelemetrie bringt Ihre App nie zum Absturz
Die Regel von OpenTelemetry lautet: Telemetrie darf zur Laufzeit niemals einen Fehler in Ihren Code werfen. Dartastic hält sich überall daran. Geht innerhalb der Telemetrie etwas schief (ein Endpunkt ist nicht erreichbar, ein Attribut hat einen ungültigen Wert, ein Export schlägt fehl), wird der Fehler an den OpenTelemetry-Error-Handler gemeldet und geloggt, und Ihre App läuft weiter.
Um diese Meldungen in Ihrem eigenen Logging oder Absturzreporting zu sehen, installieren Sie einen eigenen Handler. Er funktioniert unabhängig davon, ob Sie ihn vor oder nach DOTel.initialize aufrufen:
// 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);
});- Ohne Handler werden die Fehler mit dem eigenen Log von OpenTelemetry protokolliert (
OTEL_LOG_LEVELlegt fest, wie ausführlich es ist). - Ein eigener Handler ist die einzige Stelle, an der ein Fehler erneut geworfen werden darf, etwa um in einem Test-Build sofort fehlzuschlagen. In der Produktion: loggen und zurückkehren.
Sehen, wie es ankommt
Führen Sie Ihre App aus und nutzen Sie sie eine Minute lang. Öffnen Sie dann im Observatory „Traces“ oder „Logs“: Ihr serviceName ist dort (Observatory).
| Was Sie sehen | Was zu tun ist |
|---|---|
| Es kommt nichts an | Prüfen Sie den Endpunkt. Führen Sie einmal mit --dart-define=OTEL_LOG_LEVEL=debug aus (oder mit OTEL_LOG_LEVEL=debug auf einem Server): Das Log meldet OTelEnv: Parsed 1 header(s), wenn Ihr Token die App erreicht hat, mit verborgenem Wert. |
| Exporte werden mit 401 abgelehnt | Das Token ist falsch, widerrufen oder stammt aus einer anderen Organisation oder einem anderen Deployment. Erstellen Sie im Control Room dieser Organisation ein neues OTLP-Token. |
| Flutter Web sendet nichts | Web braucht ein Browser-OTLP-Token, in dem der Origin Ihrer Website eingetragen ist (Browser OTLP). |
Wie viel Sie senden
Was Ihre App sendet, zählt zu den eingehenden Daten Ihres Tarifs, bei Cloud wie bei Dedicated (Preise). Traces, Metriken und Logs sind standardmäßig aktiv, und ohne eine dieser Einstellungen wird nichts durch Sampling verworfen. Die RUM-Bildschirmaufnahme ist standardmäßig aus. Jede Einstellung lässt sich über eine Umgebungsvariable setzen und ändern, während Ihre App läuft. Ihre App entscheidet, wann sie eine ändert, und ruft den Setter auf. Es gibt keine Ferneinstellung.
| Signal | Umgebungsvariable | Während Ihre App läuft |
|---|---|---|
| Traces, in Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Traces, in der Engine | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Logs | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metriken | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| RUM-Bildschirmaufnahme | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.setRumSampleRate() |
Auf Smartphones und im Web ist eine Umgebungsvariable ein --dart-define, beim Build gesetzt. Ein Wert im Code hat Vorrang vor der Umgebungsvariablen, und eine Änderung zur Laufzeit hat Vorrang vor beiden. Ein ungültiger Wert wird mit seinem Namen an den OpenTelemetry-Error-Handler gemeldet, und der bisher geltende Wert bleibt bestehen.
- Traces, in der Engine: Eine Änderung wirkt ab dem nächsten Batch. Spans, die ein
tail-Sampler noch zurückhält, laufen sofort durch den neuen Sampler, sodass eine Änderung sie nie verliert. - Logs: Die Rate liegt zwischen 0,0 und 1,0 und wird pro Sitzung entschieden: Eine Sitzung wird ganz behalten oder ganz verworfen, und eine höhere Rate fügt nur Sitzungen hinzu. Ein Eintrag ab
ERRORwird immer gesendet, sodass Abstürze und schwere ANRs immer ankommen. Bildschirmaufrufe und Taps sind Log-Einträge, daher hat eine hier verworfene Sitzung keine davon in ihrer Zeitleiste. - Metriken: Die Rate liegt zwischen 0,0 und 1,0 und dünnt Exportzyklen aus: Bei 0,25 sendet einer von vier periodischen Zyklen. Kumulative Summen bleiben korrekt.
DOTel.flushMetricsund das Herunterfahren senden immer, außer bei 0, dann wird nichts gesendet. - RUM-Bildschirmaufnahme: Die Rate liegt zwischen 0,0 und 1,0, wird pro Sitzung entschieden, und eine Änderung wirkt sofort. Eine höhere Rate fügt nur Sitzungen hinzu, eine niedrigere entfernt nur welche. Sie betrifft, was die Aufnahme aufzeichnet: Sitzungen, Bildschirme und Taps sind Telemetrie und bleiben unberührt. Eine Support-Aufnahme wird nie durch Sampling verworfen. Setzen sowohl der Build als auch Ihr Code die Rate, müssen beide übereinstimmen, sonst beginnt die Aufnahme bei 0. Wie viel jede aufgenommene Sitzung enthält, bestimmt ihre Detailstufe.
RUM-Detailstufe
Die Detailstufe bestimmt, wie viel vom Bildschirm ein Replay enthält. Ein Replay zählt mit den gespeicherten Bytes zu den eingehenden Daten Ihres Tarifs, eine niedrigere Stufe verbraucht also weniger davon.
| Detailstufe | Was ein Replay zeigt | Pro Minute |
|---|---|---|
| Events | Die Zeitleiste der Bildschirme, Taps, Netzwerkaufrufe, Spans, Fehler und Abstürze. Kein Bild des Bildschirms. | Keine Replay-Bytes |
| Outline | Ein Rechteck für jedes größere Element. Kein Text und keine Icons. | 62 KB |
| Wireframe | Auch Text, Icons und kleinere Bedienelemente, jeweils als Rechteck gezeichnet. Text erscheint als graue Balken, und kein Zeichen verlässt das Gerät. | 81 KB |
| Shadow | Ein echter Screenshot, zu Blöcken verwischt, sodass Text nicht lesbar ist. | 430 KB |
| Pixel | Der echte Screenshot, so wie der Nutzer ihn gesehen hat. | 597 KB |
| Pixel, Eingaben ausgeblendet | Der Screenshot, Eingaben der Nutzer übermalt. | 516 KB |
| Pixel, sämtlicher Text ausgeblendet | Der Screenshot, sämtlicher Text übermalt. | 438 KB |
Gemessen mit der Demo-App Alpine Trails im November 2026. Eine fünfminütige Pixel-Sitzung fügt etwa 3 MB hinzu. Die Bildschirme Ihrer App sehen anders aus.
| Einstellung | Umgebungsvariable | Während Ihre App läuft |
|---|---|---|
| Stufe Ihrer App | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Stufe eines Bildschirms | Keine | setFidelity(level, route: '/checkout') |
| Höchste Stufe, die ein Build senden darf | DARTASTIC_RUM_FIDELITY_MAX | Keine |
| Bei Pixel verborgener Text | Keine | ReplayCaptureController.setMasking() |
| Replay an oder aus | Keine | ReplayCaptureController.setMode() |
Die Stufen sind events, outline, wireframe, shadow und pixel. Jede Umgebungsvariable hier ist ein --dart-define, beim Build gesetzt.
- Stufe Ihrer App: Setzen sowohl der Build als auch Ihr Code sie, müssen beide übereinstimmen. Tun sie das nicht oder ist ein Wert keine Stufe, meldet die Aufnahme das und bleibt bei Events. Eine Support-Aufnahme kann die Stufe anheben, und eine niedrigere Einstellung auf einem Bildschirm gilt auf diesem Bildschirm weiterhin.
- Die höchste Stufe: Die Engine verwirft jeden Replay-Eintrag darüber, gleich was Ihre App oder eine Aufnahme anfordert. Damit zertifizieren Sie einen Build, etwa einen, der keine Pixel erfassen kann.
- Bei Pixel verborgener Text:
ReplayMasking.textFieldsverbirgt, was Nutzer eingeben, undReplayMasking.allTextverbirgt jeden Text. - Replay an oder aus: Replay ist aus, bis Ihre App einen Modus setzt.
ReplayMode.bufferUntilTriggerbehält Frames auf dem Gerät und lädt sie nur hoch, wenn etwas schiefgeht, sodass eine Sitzung ohne Fehler gar kein Replay hochlädt.
Webviews
Eine Webseite in Ihrer App, etwa ein Checkout oder ein Hilfecenter, kann ihre Fehler, Anfragen, Web Vitals und Events in die Sitzung der App senden, markiert mit dartastic.telemetry.source webview. Die Seite exportiert nie selbst, hält kein Token und sieht keinen Endpunkt. Sie sendet an Ihre App, die jedes Feld prüft und es über die eigene Pipeline Ihrer App weiterleitet. Webview-Telemetrie ist eine Pro-Funktion.
Nennen Sie die Hosts, denen Sie vertrauen. Eine Seite passt bei exakt gleichem Host oder bei einer Subdomain eines Eintrags; eine leere Liste lässt die Bridge ausgeschaltet.
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);Was eine zugelassene Seite sendet, läuft über die Telemetrie-Zugangsdaten Ihrer App, und auf dem Server maskiert nichts davon. Ihre Liste allowedHosts und die Größenlimits der Bridge sind die Eingrenzung.
Mit webview_flutter (ab 4.9.0)
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();Mit flutter_inappwebview (ab 6.1.5)
Setzen Sie transport: DartasticWebviewTransport.inAppWebViewHandler auf der Bridge und lassen Sie JavaScript aktiviert.
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);
}
},
)Was ankommt
- iOS und macOS:
shimForCommittedPage(ab 1.32.0) ist dort erforderlich und tut anderswo nichts. Ohne diesen Aufruf sendet eine Seite auf diesen Plattformen nur ihren Seiten-Span. - webview_flutter auf iOS und macOS: Fehler und Anfragen, bevor die Seite fertig geladen ist, werden nicht erfasst, und eine Seite, die nie fertig lädt, sendet nur ihren Span. Vitals kommen trotzdem an, weil der Browser sie puffert. Wenn diese wichtig sind, verwenden Sie flutter_inappwebview, das ab Dokumentbeginn erfasst.
- Web Vitals: TTFB und FCP kommen überall an. LCP, CLS, INP und Long Tasks kommen dort an, wo die Plattform sie misst. Android WebView misst alle vier. Unter iOS 27 meldet WKWebView weder CLS noch Long Tasks, und LCP und INP sind dort nicht bestätigt. Die Bridge erfindet nie einen Wert.
- Taps: Ein Tap auf eine Platform View, etwa eine Webview oder eine Karte, wird aufgezeichnet, aber nie als Dead-Tap oder Rage-Tap gezählt.