Ces pages affichent les URL de Cloud. Connectez-vous sur Dedicated et elles affichent celles de votre serveur.

Ajouter OTel à votre application

Ajoutez Dartastic OpenTelemetry à une application Flutter ou à un serveur Dart en trois étapes : ajoutez les packages, initialisez une fois au démarrage, et donnez au build votre endpoint OTLP et votre jeton. Vos traces, logs et métriques arrivent dans votre Observatory.

BUILDARCHITECTURE DARTASTICUTILISATEURSjetonsticketsjeton Pubpushéchange CIles applis sont livrées aux utilisateurs : stores d’applications, web, serveurssymbolescrashspiles d’appelscode sourcetélémétriePoste développeurflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomcréation de jetons · contrôle d’accès par rôlePlan de contrôleorganisations · rôles · jetonsDartastic Pubpackages · code sourceObservatorysessions · traces · logsSymbolizercrashs → lignes de codeDartastic AIrépond à partir des deuxSuivi des ticketsGitHub · Jira · LinearApplis mobiles + bureautéléphones · tablettes · ordinateursenvoie avec un jeton OTLPApplis webdans les navigateursenvoie avec un jeton Browser OTLPServeurs Dartbackends · servicesenvoie avec un jeton OTLP

Ce qu’il vous faut

  • Les bonnes versions de Flutter et de Dart. Créer votre première application indique ce dont chaque package a besoin.
  • Un jeton OTLP. Dans le Control Room, ouvrez Tokens, choisissez Generate, puis OTLP. Il n’est affiché qu’une fois : conservez-le dans votre gestionnaire de mots de passe ou dans les secrets de votre CI. Pour Flutter web, utilisez plutôt un jeton Browser OTLP (Browser OTLP).
  • Votre endpoint OTLP : https://otlp.cloud.dartastic.io.
  • Un accès à Dartastic Pub pour les packages : dart pub token add https://pub.dartastic.io avec un jeton Pub.
[TODO : capture d’écran de Control Room, « Tokens » : « Generate », puis « OTLP », et le nouveau jeton affiché une seule fois]

Une application Flutter

Ajoutez les deux packages à pubspec.yaml. Ils sont publiés ensemble et restent sur la même version :

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

Initialisez une fois, avant 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 nomme votre application dans l’Observatory. Choisissez un nom que tout le monde reconnaît ; ce n’est pas forcément le nom de votre package.
  • app.build_id est l’identité de build de votre application. Le package Flutter la définit pour vous, à partir de la version et du numéro de build de votre application (Votre identifiant de build). Les crashs et les comparaisons entre versions sont regroupés selon cette identité.
  • DartasticViewObserver enregistre une vue d’écran à chaque fois qu’une route est poussée, et la durée pendant laquelle chaque écran est resté ouvert.

Donnez au build votre endpoint et votre jeton avec --dart-define. Une application mobile ne voit pas l’environnement de votre shell : les defines sont le moyen de lui transmettre ces valeurs. Gardez le jeton hors du contrôle de version : placez-le dans une variable d’environnement sur votre machine ou dans votre CI, et transmettez cette variable.

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"

Ce sont les variables standard d’OpenTelemetry. Gardez authorization en minuscules : cela fonctionne avec tous les protocoles. Un jeton OTLP peut seulement envoyer de la télémétrie à votre organisation : il ne lit rien et ne modifie rien.

Une fois DOTel.initialize terminé, il enregistre sans aucun code supplémentaire :

  • une session pour chaque visite, sur chaque span et chaque enregistrement de log ;
  • les taps, et la rapidité avec laquelle l’application y répond ;
  • les vues d’écran, grâce à DartasticViewObserver ;
  • et, selon ce que comprend votre offre, les crashs, les interfaces figées, le jank et les métriques vitales.

Votre identifiant de build

L’identifiant de build provient de la version et du numéro de build que chaque plateforme indique pour votre application :

Version de votre applicationAndroidiOS
version: 1.4.0+27 dans pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 dans pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.4.0+27

Android ajoute +1 à une version sans numéro de build, car c’est le numéro de build par défaut de Flutter sur cette plateforme. Pour obtenir le même identifiant de build sur toutes les plateformes, donnez un numéro de build à votre version (1.4.0+27).

Un serveur Dart

Un serveur Dart ou une application en ligne de commande n’a besoin que d’un seul package :

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

Sur un serveur, les deux mêmes variables viennent de l’environnement :

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

La télémétrie ne casse jamais votre application

La règle d’OpenTelemetry veut que la télémétrie ne lève jamais d’erreur dans votre code à l’exécution. Dartastic la respecte partout. Quand quelque chose échoue dans la télémétrie (un endpoint injoignable, un attribut avec une valeur invalide, un export qui échoue), l’erreur est signalée au gestionnaire d’erreurs d’OpenTelemetry et journalisée, et votre application continue de tourner.

Pour voir ces signalements dans votre propre journalisation ou votre propre outil de rapport de crash, installez votre propre gestionnaire. Il fonctionne que vous l’appeliez avant ou après DOTel.initialize :

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);
});
  • Sans gestionnaire, les erreurs sont journalisées par le log propre d’OpenTelemetry (OTEL_LOG_LEVEL règle son niveau de détail).
  • Votre propre gestionnaire est le seul endroit où une erreur peut être relancée, par exemple pour échouer immédiatement dans un build de test. En production, journalisez et retournez.

La voir arriver

Lancez votre application et utilisez-la une minute, puis ouvrez « Traces » ou « Logs » dans l’Observatory : votre serviceName y figure (Observatory).

[TODO : capture d’écran de l’écran « Traces » de l’Observatory avec la première trace de l’application]
Ce que vous voyezQue faire
Rien n’arriveVérifiez l’endpoint. Lancez une fois avec --dart-define=OTEL_LOG_LEVEL=debug (ou OTEL_LOG_LEVEL=debug sur un serveur) : le log affiche OTelEnv: Parsed 1 header(s) quand votre jeton a atteint l’application, avec sa valeur masquée.
Les exports sont refusés avec une erreur 401Le jeton est incorrect, révoqué, ou provient d’une autre organisation ou d’un autre déploiement. Générez un nouveau jeton OTLP dans le Control Room de cette organisation.
Flutter web n’envoie rienLe web demande un jeton Browser OTLP portant l’origine de votre site (Browser OTLP).

Combien vous envoyez

Ce que votre application envoie compte dans le trafic entrant de votre offre, sur Cloud comme sur Dedicated (Tarifs). Les traces, les métriques et les logs sont activés par défaut, et sans aucun de ces réglages, rien n’est écarté par échantillonnage. La capture d’écran RUM est désactivée par défaut. Chaque réglage peut être défini par une variable d’environnement et modifié pendant l’exécution de votre application. C’est votre application qui décide quand en changer un, et qui appelle le setter. Il n’existe aucun réglage à distance.

SignalVariable d’environnementPendant l’exécution
Traces, côté DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Traces, côté moteurDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogsDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MétriquesDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Capture d’écran RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.setRumSampleRate()

Sur les téléphones et le web, une variable d’environnement est un --dart-define, défini au build. Une valeur dans le code l’emporte sur la variable d’environnement, et un changement pendant l’exécution l’emporte sur les deux. Une valeur invalide est signalée par son nom au gestionnaire d’erreurs d’OpenTelemetry, et le réglage en vigueur reste inchangé.

  • Traces, côté moteur : un changement s’applique au lot suivant. Les spans encore retenus par un échantillonneur tail passent aussitôt par le nouvel échantillonneur : un changement ne les perd jamais.
  • Logs : le taux va de 0.0 à 1.0 et se décide par session : une session est conservée ou écartée en entier, et augmenter le taux ne fait qu’ajouter des sessions. Un enregistrement de niveau ERROR ou supérieur part toujours : les crashs et les ANR graves arrivent toujours. Les vues d’écran et les taps sont des enregistrements de log : une session écartée ici n’en a aucun dans sa chronologie.
  • Métriques : le taux va de 0.0 à 1.0 et espace les cycles d’export : à 0.25, un cycle périodique sur quatre envoie. Les totaux cumulés restent justes. DOTel.flushMetrics et l’arrêt envoient toujours, sauf à 0, qui n’envoie rien.
  • Capture d’écran RUM : le taux va de 0.0 à 1.0, se décide par session, et un changement s’applique aussitôt. L’augmenter ne fait qu’ajouter des sessions, le baisser ne fait qu’en retirer. Il porte sur ce que la capture enregistre : les sessions, les écrans et les taps relèvent de la télémétrie, et il n’y touche pas. Un enregistrement demandé par le support n’est jamais écarté par échantillonnage. Si le build et votre code définissent tous deux le taux, ils doivent concorder, sinon la capture démarre à 0. La quantité d’informations de chaque session capturée dépend de sa fidélité.

Fidélité RUM

La fidélité désigne la part de l’écran que transporte un replay. Un replay compte dans le trafic entrant de votre offre selon les octets qu’il stocke : un niveau plus bas en consomme moins.

FidélitéCe que montre un replayAjout par minute
EventsLa chronologie des écrans, taps, appels réseau, spans, erreurs et crashs. Aucune image de l’écran.Aucun octet de replay
OutlineUn rectangle pour chaque élément principal. Ni texte ni icônes.62 Ko
WireframeLe texte, les icônes et les contrôles plus petits aussi, chacun dessiné sous forme de rectangle. Le texte apparaît en barres grises, et aucun caractère ne quitte l’appareil.81 Ko
ShadowUne vraie capture d’écran, floutée en blocs pour que le texte soit illisible.430 Ko
PixelLa vraie capture d’écran, telle que l’utilisateur l’a vue.597 Ko
Pixel, saisie masquéeLa capture d’écran, avec la saisie des utilisateurs recouverte.516 Ko
Pixel, tout le texte masquéLa capture d’écran, avec tout le texte recouvert.438 Ko

Mesuré sur l’application de démo Alpine Trails en novembre 2026. Une session Pixel de cinq minutes ajoute environ 3 Mo. Les écrans de votre application diffèrent.

RéglageVariable d’environnementPendant l’exécution
Niveau de votre applicationDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Niveau d’un écranAucunesetFidelity(level, route: '/checkout')
Niveau maximal qu’un build peut envoyerDARTASTIC_RUM_FIDELITY_MAXAucune
Texte masqué en PixelAucuneReplayCaptureController.setMasking()
Replay activé ou désactivéAucuneReplayCaptureController.setMode()

Les niveaux sont events, outline, wireframe, shadow et pixel. Chaque variable d’environnement ici est un --dart-define, défini au build.

  • Niveau de votre application : si le build et votre code le définissent tous deux, ils doivent concorder. Sinon, ou si une valeur n’est pas un niveau, la capture le signale et reste à Events. Un enregistrement demandé par le support peut relever le niveau, et un réglage plus bas sur un écran reste appliqué sur cet écran.
  • Le niveau maximal : le moteur écarte tout enregistrement de replay au-dessus de ce niveau, quoi que demande votre application ou un enregistrement. Servez-vous-en pour certifier un build, par exemple un build incapable de capturer des pixels.
  • Texte masqué en Pixel : ReplayMasking.textFields masque ce que saisissent les utilisateurs, et ReplayMasking.allText masque tout le texte.
  • Replay activé ou désactivé : le replay est désactivé tant que votre application ne définit pas de mode. ReplayMode.bufferUntilTrigger garde les frames sur l’appareil et ne les envoie qu’en cas de problème : une session où rien ne casse n’envoie aucun replay.

Webviews

Une page web intégrée à votre application, comme un parcours de paiement ou un centre d’aide, peut envoyer ses erreurs, ses requêtes, ses web vitals et ses événements dans la session de l’application, marqués dartastic.telemetry.source webview. La page n’exporte jamais rien, ne détient aucun jeton et ne voit aucun endpoint. Elle poste ses données à votre application, qui vérifie chaque champ et les envoie par son propre pipeline. La télémétrie des webviews est une fonctionnalité Pro.

Nommez les hôtes auxquels vous faites confiance. Une page correspond si son hôte est exactement une entrée ou un sous-domaine d’une entrée, et une liste vide laisse le pont désactivé.

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

Tout ce qu’envoie une page autorisée utilise les identifiants de télémétrie de votre application, et rien ne le masque côté serveur. Votre liste allowedHosts et les limites de taille du pont sont les seules barrières.

Avec webview_flutter (4.9.0 et versions ultérieures)

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

Avec flutter_inappwebview (6.1.5 et versions ultérieures)

Définissez transport: DartasticWebviewTransport.inAppWebViewHandler sur le pont, et laissez JavaScript activé.

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

Ce qui arrive

  • iOS et macOS : shimForCommittedPage (1.32.0 et versions ultérieures) y est requis, et ne fait rien ailleurs. Sans lui, une page sur ces plateformes n’envoie que son span de page.
  • webview_flutter sur iOS et macOS : les erreurs et les requêtes antérieures à la fin du chargement de la page ne sont pas capturées, et une page qui ne finit jamais de charger n’envoie que son span. Les web vitals arrivent quand même, car le navigateur les met en mémoire tampon. Quand ces mesures comptent, utilisez flutter_inappwebview, qui capture dès le début du document.
  • Web vitals : TTFB et FCP arrivent partout. LCP, CLS, INP et les tâches longues arrivent là où la plateforme les mesure. La WebView d’Android mesure les quatre. Sur iOS 27, WKWebView ne signale ni CLS ni tâches longues, et LCP et INP n’y sont pas confirmés. Le pont n’invente jamais de valeur.
  • Taps : un tap sur une vue de plateforme, comme une webview ou une carte, est enregistré mais jamais compté comme un tap sans effet ni comme un tap rageur.