OTel aan uw app toevoegen
Voeg Dartastic OpenTelemetry in drie stappen toe aan een Flutter-app of een Dart-server: voeg de packages toe, initialiseer één keer bij het opstarten en geef de build uw OTLP-endpoint en token. Uw traces, logs en metrics komen binnen in uw Observatory.
Wat u nodig heeft
- De juiste Flutter en Dart. Uw eerste app bouwen vermeldt wat elk package nodig heeft.
- Een OTLP-token. Open in de Control Room Tokens, kies Generate en daarna OTLP. Het token wordt één keer getoond: bewaar het in uw wachtwoordmanager of in de secrets van uw CI. Gebruik voor Flutter-web in plaats daarvan een Browser OTLP-token (Browser OTLP).
- Uw OTLP-endpoint:
https://otlp.cloud.dartastic.io. - Toegang tot Dartastic Pub voor de packages:
dart pub token add https://pub.dartastic.iomet een Pub-token.
Een Flutter-app
Voeg de twee packages toe aan pubspec.yaml. Ze worden samen uitgebracht en blijven op één versie:
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.4Initialiseer één keer, vóór 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(),
));
}serviceNamegeeft uw app de naam in het Observatory. Kies een naam die mensen herkennen; het hoeft niet de naam van uw package te zijn.app.build_idis de build-identiteit van uw app. Het Flutter-package stelt die voor u in, op basis van de versie en het buildnummer van uw app (Uw build-id). Crashes en releasevergelijkingen worden erop gegroepeerd.DartasticViewObserverlegt een schermweergave vast telkens wanneer een route wordt gepusht, en hoe lang elk scherm open was.
Geef de build uw endpoint en token met --dart-define. Een telefoonapp ziet de omgeving van uw shell niet, dus via de defines bereiken de waarden de app. Houd het token buiten versiebeheer: zet het in een omgevingsvariabele op uw computer of in CI, en geef die door.
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"Dit zijn de standaardvariabelen van OpenTelemetry. Schrijf authorization in kleine letters: zo werkt het voor elk protocol. Een OTLP-token kan alleen telemetrie naar uw organisatie sturen: het leest niets en wijzigt niets.
Zodra DOTel.initialize klaar is, legt het zonder verdere code het volgende vast:
- een sessie voor elk bezoek, op elke span en elk logrecord;
- tikken, en hoe snel de app erop reageert;
- schermweergaven, via
DartasticViewObserver; - en, voor zover uw abonnement ze omvat, crashes, bevroren UI, jank en vitals.
Uw build-id
Het build-id komt uit de versie en het buildnummer die elk platform voor uw app meldt:
| Versie van uw 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 voegt +1 toe aan een versie zonder buildnummer, omdat dat daar het standaardbuildnummer van Flutter is. Wilt u één build-id op elk platform, geef uw versie dan een buildnummer (1.4.0+27).
Een Dart-server
Een Dart-server of commandlineapp heeft het ene package nodig:
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 ...
}Op een server komen dezelfde twee variabelen uit de omgeving:
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 breekt uw app nooit
De regel van OpenTelemetry is dat telemetrie tijdens runtime nooit een fout in uw code mag gooien. Dartastic volgt die regel overal. Gaat er binnen de telemetrie iets mis (een endpoint dat niet bereikbaar is, een attribuut met een ongeldige waarde, een export die mislukt), dan wordt de fout gemeld aan de error handler van OpenTelemetry en gelogd, en blijft uw app draaien.
Wilt u die meldingen in uw eigen logging of crashrapportage zien, installeer dan een eigen handler. Dat werkt of u hem nu vóór of na DOTel.initialize aanroept:
// 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);
});- Zonder handler worden de fouten gelogd met de eigen log van OpenTelemetry (
OTEL_LOG_LEVELbepaalt hoeveel die meldt). - Een eigen handler is de enige plek waar een fout opnieuw mag worden gegooid, bijvoorbeeld om in een testbuild snel te falen. Log in productie en keer terug.
Zie het binnenkomen
Draai uw app en gebruik hem een minuut, open dan “Traces” of “Logs” in het Observatory: uw serviceName staat daar (Observatory).
| Wat u ziet | Wat u doet |
|---|---|
| Er komt niets binnen | Controleer het endpoint. Draai één keer met --dart-define=OTEL_LOG_LEVEL=debug (of OTEL_LOG_LEVEL=debug op een server): de log meldt OTelEnv: Parsed 1 header(s) wanneer uw token de app heeft bereikt, met de waarde verborgen. |
| Exports worden geweigerd met 401 | Het token is onjuist, ingetrokken of van een andere organisatie of deployment. Maak een nieuw OTLP-token aan in de Control Room van deze organisatie. |
| Flutter-web stuurt niets | Web heeft een Browser OTLP-token nodig, met de origin van uw site erop (Browser OTLP). |
Hoeveel u verstuurt
Wat uw app verstuurt, telt mee voor het inkomend verkeer van uw abonnement, op Cloud en Dedicated gelijk (Prijzen). Traces, metrics en logs staan standaard aan, en zolang geen van deze variabelen is ingesteld, wordt er niets weggesampled. Schermopname voor RUM staat standaard uit. Elk kan worden ingesteld met een omgevingsvariabele en worden gewijzigd terwijl uw app draait. Uw app bepaalt wanneer er een wijzigt, en roept de setter aan. Er is geen instelling op afstand.
| Signaal | Omgevingsvariabele | Terwijl uw app draait |
|---|---|---|
| Traces, in Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Traces, in de engine | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Logs | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metrics | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Schermopname voor RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.setRumSampleRate() |
Op telefoons en op het web is een omgevingsvariabele een --dart-define, ingesteld bij de build. Een waarde in code gaat voor de omgevingsvariabele, en een wijziging terwijl uw app draait gaat voor beide. Een ongeldige waarde gaat met naam naar de error handler van OpenTelemetry, en wat van kracht was, blijft staan.
- Traces, in de engine: een wijziging geldt vanaf de volgende batch. Spans die een
tail-sampler nog vasthoudt, gaan meteen door de nieuwe sampler, dus een wijziging verliest ze nooit. - Logs: de rate ligt tussen 0.0 en 1.0 en wordt per sessie bepaald, dus een sessie wordt in haar geheel bewaard of weggelaten, en een hogere rate voegt alleen sessies toe. Een record van
ERRORof hoger gaat altijd uit, dus crashes en ernstige ANR’s komen altijd binnen. Schermweergaven en tikken zijn logrecords, dus een sessie die hier wordt weggelaten, heeft er geen op haar tijdlijn. - Metrics: de rate ligt tussen 0.0 en 1.0 en dunt exportcycli uit: bij 0.25 verstuurt één op de vier periodieke cycli. Cumulatieve totalen blijven kloppen.
DOTel.flushMetricsen afsluiten versturen altijd, behalve bij 0, dat niets verstuurt. - Schermopname voor RUM: de rate ligt tussen 0.0 en 1.0, wordt per sessie bepaald, en een wijziging geldt meteen. Een hogere rate voegt alleen sessies toe, een lagere haalt er alleen weg. De rate geldt voor wat de opname vastlegt: sessies, schermen en tikken zijn telemetrie, en die raakt ze niet. Een supportopname wordt nooit weggesampled. Stellen de build en uw code allebei de rate in, dan moeten ze overeenkomen, anders begint de opname bij 0. Hoeveel elke opgenomen sessie bevat, is haar detailniveau.
RUM-detailniveau
Het detailniveau bepaalt hoeveel van het scherm een replay bevat. Een replay telt mee voor het inkomend verkeer van uw abonnement naar het aantal bytes dat ze opslaat, dus een lager niveau gebruikt er minder van.
| Detailniveau | Wat een replay laat zien | Eén minuut voegt toe |
|---|---|---|
| Events | De tijdlijn van schermen, tikken, netwerkaanroepen, spans, fouten en crashes. Geen beeld van het scherm. | Geen replay-bytes |
| Outline | Een rechthoek voor elk belangrijk element. Geen tekst en geen iconen. | 62 KB |
| Wireframe | Ook tekst, iconen en kleinere bedieningselementen, elk getekend als een rechthoek. Tekst verschijnt als grijze balken, en er verlaten geen tekens het apparaat. | 81 KB |
| Shadow | Een echte screenshot, vervaagd tot blokken zodat tekst onleesbaar is. | 430 KB |
| Pixel | De echte screenshot, zoals de gebruiker die zag. | 597 KB |
| Pixel, getypte tekst verborgen | De screenshot, met wat gebruikers typen overgeschilderd. | 516 KB |
| Pixel, alle tekst verborgen | De screenshot, met alle tekst overgeschilderd. | 438 KB |
Gemeten op de demo-app Alpine Trails in november 2026. Een Pixel-sessie van vijf minuten voegt ongeveer 3 MB toe. De schermen van uw app wijken af.
| Instelling | Omgevingsvariabele | Terwijl uw app draait |
|---|---|---|
| Het niveau van uw app | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Het niveau van één scherm | Geen | setFidelity(level, route: '/checkout') |
| Het hoogste niveau dat een build mag versturen | DARTASTIC_RUM_FIDELITY_MAX | Geen |
| Tekst verborgen bij Pixel | Geen | ReplayCaptureController.setMasking() |
| Replay aan of uit | Geen | ReplayCaptureController.setMode() |
De niveaus zijn events, outline, wireframe, shadow en pixel. Elke omgevingsvariabele hier is een --dart-define, ingesteld bij de build.
- Het niveau van uw app: stellen de build en uw code het allebei in, dan moeten ze overeenkomen. Doen ze dat niet, of is een waarde geen niveau, dan meldt de opname dat en blijft ze op Events. Een supportopname kan het niveau verhogen, en een lagere instelling op een scherm blijft op dat scherm gelden.
- Het hoogste niveau: de engine laat elk replayrecord boven dit niveau vallen, wat uw app of een opname ook vraagt. Gebruik het om een build te certificeren, bijvoorbeeld een build die geen pixels kan vastleggen.
- Tekst verborgen bij Pixel:
ReplayMasking.textFieldsverbergt wat gebruikers typen, enReplayMasking.allTextverbergt alle tekst. - Replay aan of uit: replay staat uit totdat uw app een modus instelt.
ReplayMode.bufferUntilTriggerhoudt frames op het apparaat en uploadt ze alleen wanneer er iets misgaat, dus een sessie waarin niets misgaat, uploadt helemaal geen replay.
Webviews
Een webpagina in uw app, zoals een afrekenproces of een helpcentrum, kan haar fouten, requests, web vitals en events in de sessie van de app sturen, gemarkeerd met dartastic.telemetry.source webview. De pagina exporteert nooit, bewaart geen token en ziet geen endpoint. Ze post naar uw app, die elk veld controleert en het via de eigen pipeline van uw app verstuurt. Webviewtelemetrie is een Pro-functie.
Noem de hosts die u vertrouwt. Een pagina komt overeen bij de exacte host of een subdomein van een vermelding, en een lege lijst houdt de bridge uit.
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);Alles wat een toegestane pagina verstuurt, gaat mee op de inloggegevens voor telemetrie van uw app, en niets maskeert het op de server. Uw lijst allowedHosts en de groottelimieten van de bridge zijn de afscherming.
Met webview_flutter (4.9.0 en later)
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();Met flutter_inappwebview (6.1.5 en later)
Stel transport: DartasticWebviewTransport.inAppWebViewHandler in op de bridge, en laat JavaScript aan.
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);
}
},
)Wat er binnenkomt
- iOS en macOS:
shimForCommittedPage(1.32.0 en later) is daar vereist en doet elders niets. Zonder dit stuurt een pagina op die platforms alleen haar paginaspan. - webview_flutter op iOS en macOS: fouten en requests van voordat de pagina klaar is met laden, worden niet vastgelegd, en een pagina die nooit klaar is, stuurt alleen haar span. Vitals komen wel binnen, omdat de browser ze buffert. Zijn die belangrijk, gebruik dan flutter_inappwebview, dat vanaf het begin van het document vastlegt.
- Web vitals: TTFB en FCP komen overal binnen. LCP, CLS, INP en lange taken komen binnen waar het platform ze meet. Android WebView meet ze alle vier. Op iOS 27 meldt WKWebView geen CLS of lange taken, en LCP en INP zijn daar niet bevestigd. De bridge verzint nooit een waarde.
- Tikken: een tik op een platformweergave, zoals een webview of een kaart, wordt vastgelegd maar nooit geteld als dode tik of woedende tik.