Deze pagina’s tonen de URL’s van Cloud. Log in op Dedicated, dan tonen ze die van uw server.

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.

BUILDDARTASTIC-ARCHITECTUURGEBRUIKERStokensissuesPub-tokenpushCI-uitwisselingapps bereiken gebruikers via appstores, het web en serverssymbolencrashesstacktracesbroncodetelemetrieOntwikkelaarscomputerflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomtokens aanmaken · rolgebaseerd toegangsbeheerControl Planeorganisaties · rollen · tokensDartastic Pubpackages · broncodeObservatorysessies · traces · logsSymbolizercrashes → broncoderegelsDartastic AIantwoorden uit beideIssuetrackerGitHub · Jira · LinearMobiele en desktopappstelefoons · tablets · desktopsverstuurt met een OTLP-tokenWebappsin browsersverstuurt met een Browser OTLP-tokenDart-serversbackends · servicesverstuurt met een OTLP-token

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.io met een Pub-token.
[TODO: screenshot van Control Room, “Tokens”: “Generate”, daarna “OTLP”, en het nieuwe token dat één keer wordt getoond]

Een Flutter-app

Voeg de twee packages toe aan pubspec.yaml. Ze worden samen uitgebracht en blijven op één versie:

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

Initialiseer één keer, vóór 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 geeft 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_id is 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.
  • DartasticViewObserver legt 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.

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"

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 appAndroidiOS
version: 1.4.0+27 in pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 in pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.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:

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

Op een server komen dezelfde twee variabelen uit de omgeving:

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

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

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);
});
  • Zonder handler worden de fouten gelogd met de eigen log van OpenTelemetry (OTEL_LOG_LEVEL bepaalt 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).

[TODO: screenshot van het scherm “Traces” van het Observatory met de eerste trace van de app]
Wat u zietWat u doet
Er komt niets binnenControleer 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 401Het 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 nietsWeb 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.

SignaalOmgevingsvariabeleTerwijl uw app draait
Traces, in DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Traces, in de engineDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogsDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MetricsDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Schermopname voor RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.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 ERROR of 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.flushMetrics en 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.

DetailniveauWat een replay laat zienEén minuut voegt toe
EventsDe tijdlijn van schermen, tikken, netwerkaanroepen, spans, fouten en crashes. Geen beeld van het scherm.Geen replay-bytes
OutlineEen rechthoek voor elk belangrijk element. Geen tekst en geen iconen.62 KB
WireframeOok tekst, iconen en kleinere bedieningselementen, elk getekend als een rechthoek. Tekst verschijnt als grijze balken, en er verlaten geen tekens het apparaat.81 KB
ShadowEen echte screenshot, vervaagd tot blokken zodat tekst onleesbaar is.430 KB
PixelDe echte screenshot, zoals de gebruiker die zag.597 KB
Pixel, getypte tekst verborgenDe screenshot, met wat gebruikers typen overgeschilderd.516 KB
Pixel, alle tekst verborgenDe 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.

InstellingOmgevingsvariabeleTerwijl uw app draait
Het niveau van uw appDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Het niveau van één schermGeensetFidelity(level, route: '/checkout')
Het hoogste niveau dat een build mag versturenDARTASTIC_RUM_FIDELITY_MAXGeen
Tekst verborgen bij PixelGeenReplayCaptureController.setMasking()
Replay aan of uitGeenReplayCaptureController.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.textFields verbergt wat gebruikers typen, en ReplayMasking.allText verbergt alle tekst.
  • Replay aan of uit: replay staat uit totdat uw app een modus instelt. ReplayMode.bufferUntilTrigger houdt 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.

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

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

Met flutter_inappwebview (6.1.5 en later)

Stel transport: DartasticWebviewTransport.inAppWebViewHandler in op de bridge, en laat JavaScript aan.

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

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.