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.
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.ioavec un jeton Pub.
Une application Flutter
Ajoutez les deux packages à pubspec.yaml. Ils sont publiés ensemble et restent sur la même 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.4Initialisez une fois, avant 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(),
));
}serviceNamenomme 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_idest 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é.DartasticViewObserverenregistre 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.
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 application | Android | iOS |
|---|---|---|
version: 1.4.0+27 dans pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 dans 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 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 :
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 ...
}Sur un serveur, les deux mêmes variables viennent de l’environnement :
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dartLa 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 :
// 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_LEVELrè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).
| Ce que vous voyez | Que faire |
|---|---|
| Rien n’arrive | Vé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 401 | Le 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 rien | Le 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.
| Signal | Variable d’environnement | Pendant l’exécution |
|---|---|---|
| Traces, côté Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Traces, côté moteur | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Logs | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Métriques | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Capture d’écran RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.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
tailpassent 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
ERRORou 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.flushMetricset 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 replay | Ajout par minute |
|---|---|---|
| Events | La chronologie des écrans, taps, appels réseau, spans, erreurs et crashs. Aucune image de l’écran. | Aucun octet de replay |
| Outline | Un rectangle pour chaque élément principal. Ni texte ni icônes. | 62 Ko |
| Wireframe | Le 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 |
| Shadow | Une vraie capture d’écran, floutée en blocs pour que le texte soit illisible. | 430 Ko |
| Pixel | La vraie capture d’écran, telle que l’utilisateur l’a vue. | 597 Ko |
| Pixel, saisie masquée | La 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églage | Variable d’environnement | Pendant l’exécution |
|---|---|---|
| Niveau de votre application | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Niveau d’un écran | Aucune | setFidelity(level, route: '/checkout') |
| Niveau maximal qu’un build peut envoyer | DARTASTIC_RUM_FIDELITY_MAX | Aucune |
| Texte masqué en Pixel | Aucune | ReplayCaptureController.setMasking() |
| Replay activé ou désactivé | Aucune | ReplayCaptureController.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.textFieldsmasque ce que saisissent les utilisateurs, etReplayMasking.allTextmasque tout le texte. - Replay activé ou désactivé : le replay est désactivé tant que votre application ne définit pas de mode.
ReplayMode.bufferUntilTriggergarde 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é.
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)
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é.
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.