Aggiungere OTel alla sua app
Aggiunga Dartastic OpenTelemetry a un’app Flutter o a un server Dart in tre passaggi: aggiunga i pacchetti, inizializzi una volta all’avvio e passi alla build il suo endpoint OTLP e il suo token. Tracce, log e metriche arrivano nel suo Observatory.
Cosa serve
- Le versioni giuste di Flutter e Dart. Creare la prima app elenca ciò che serve a ogni pacchetto.
- Un token OTLP. Nella Control Room, apra Tokens, scelga Generate, poi OTLP. Viene mostrato una sola volta: lo conservi nel suo password manager o nei segreti della CI. Per Flutter web, usi invece un token Browser OTLP (Browser OTLP).
- Il suo endpoint OTLP:
https://otlp.cloud.dartastic.io. - Accesso a Dartastic Pub per i pacchetti:
dart pub token add https://pub.dartastic.iocon un token Pub.
Un’app Flutter
Aggiunga i due pacchetti a pubspec.yaml. Escono insieme e restano sulla stessa versione:
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.4Inizializzi una volta, prima di 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(),
));
}serviceNamedà il nome alla sua app nell’Observatory. Scelga un nome riconoscibile; non deve per forza coincidere con il nome del pacchetto.app.build_idè l’identità della build della sua app. Lo imposta il pacchetto Flutter, dalla versione e dal numero di build dell’app (Il build ID). I crash e i confronti tra release si raggruppano in base a esso.DartasticViewObserverregistra una visualizzazione di schermata ogni volta che viene inserita una route, e per quanto tempo ogni schermata è rimasta aperta.
Passi alla build endpoint e token con --dart-define. Un’app per telefono non vede l’ambiente della sua shell, quindi le define sono il modo in cui i valori la raggiungono. Tenga il token fuori dal controllo di versione: lo metta in una variabile d’ambiente sulla sua macchina o nella CI, e passi quella.
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"Sono le variabili standard di OpenTelemetry. Scriva authorization in minuscolo: funziona con ogni protocollo. Un token OTLP può solo inviare telemetria alla sua organizzazione: non legge nulla e non modifica nulla.
Quando DOTel.initialize è completato, registra senza altro codice:
- una sessione per ogni visita, su ogni span e ogni record di log;
- i tap, e la rapidità con cui l’app risponde;
- le visualizzazioni di schermata, tramite
DartasticViewObserver; - e, se il suo piano li include, crash, UI bloccata, jank e metriche vitali.
Il build ID
Il build ID deriva dalla versione e dal numero di build che ogni piattaforma riporta per la sua app:
| Versione dell’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 aggiunge +1 a una versione senza numero di build, perché lì è il numero di build predefinito di Flutter. Per avere lo stesso build ID su ogni piattaforma, dia un numero di build alla sua versione (1.4.0+27).
Un server Dart
Un server Dart o un’app a riga di comando ha bisogno di un solo pacchetto:
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 ...
}Su un server, le stesse due variabili arrivano dall’ambiente:
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 telemetria non rompe mai la sua app
La regola di OpenTelemetry è che la telemetria non deve mai sollevare un errore nel suo codice in fase di esecuzione. Dartastic la segue ovunque. Quando qualcosa va storto nella telemetria (un endpoint irraggiungibile, un attributo con un valore errato, un’esportazione che fallisce), l’errore viene segnalato al gestore degli errori di OpenTelemetry e registrato nel log, e la sua app continua a funzionare.
Per vedere queste segnalazioni nel suo sistema di log o di crash reporting, installi un suo gestore. Funziona sia che lo chiami prima sia dopo 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);
});- Senza un gestore, gli errori vengono registrati con il log di OpenTelemetry (
OTEL_LOG_LEVELne regola il dettaglio). - Un gestore suo è l’unico punto in cui un errore può essere rilanciato, per esempio per fallire subito in una build di test. In produzione, registri nel log e ritorni.
Vederla arrivare
Avvii l’app e la usi per un minuto, poi apra « Traces » o « Logs » nell’Observatory: il suo serviceName è lì (Observatory).
| Cosa vede | Cosa fare |
|---|---|
| Non arriva nulla | Controlli l’endpoint. Esegua una volta con --dart-define=OTEL_LOG_LEVEL=debug (o OTEL_LOG_LEVEL=debug su un server): il log riporta OTelEnv: Parsed 1 header(s) quando il token ha raggiunto l’app, con il valore nascosto. |
| Le esportazioni vengono rifiutate con 401 | Il token è errato, revocato, o di un’altra organizzazione o distribuzione. Generi un nuovo token OTLP nella Control Room di questa organizzazione. |
| Flutter web non invia nulla | Il web ha bisogno di un token Browser OTLP con l’origine del suo sito (Browser OTLP). |
Quanto inviare
Ciò che la sua app invia rientra nel traffico in ingresso del suo piano, sia su Cloud sia su Dedicated (Prezzi). Tracce, metriche e log sono attivi per impostazione predefinita e, se nessuna di queste impostazioni è definita, non viene scartato nulla dal campionamento. La cattura dello schermo RUM è disattivata per impostazione predefinita. Ognuna si imposta con una variabile d’ambiente e si può cambiare mentre l’app è in esecuzione. È la sua app a decidere quando cambiarla, chiamando il setter. Non esiste un’impostazione remota.
| Segnale | Variabile d’ambiente | Durante l’esecuzione |
|---|---|---|
| Tracce, in Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Tracce, nel motore | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Log | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Metriche | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Cattura dello schermo RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.setRumSampleRate() |
Su telefoni e web, una variabile d’ambiente è una --dart-define, impostata in fase di build. Un valore nel codice prevale sulla variabile d’ambiente, e una modifica durante l’esecuzione prevale su entrambi. Un valore errato viene segnalato per nome al gestore degli errori di OpenTelemetry, e resta in vigore il valore precedente.
- Tracce, nel motore: una modifica ha effetto dal batch successivo. Gli span ancora trattenuti da un campionatore
tailpassano subito attraverso il nuovo campionatore, quindi una modifica non li perde mai. - Log: la frequenza va da 0,0 a 1,0 ed è decisa per sessione, quindi una sessione viene conservata o scartata per intero e aumentare la frequenza aggiunge solo sessioni. Un record di livello
ERRORo superiore viene sempre inviato, quindi crash e ANR gravi arrivano sempre. Visualizzazioni di schermata e tap sono record di log, quindi una sessione scartata qui non ne ha nessuno sulla sua timeline. - Metriche: la frequenza va da 0,0 a 1,0 e dirada i cicli di esportazione: a 0,25 invia un ciclo periodico su quattro. I totali cumulativi restano corretti.
DOTel.flushMetricse lo spegnimento inviano sempre, tranne a 0, che non invia nulla. - Cattura dello schermo RUM: la frequenza va da 0,0 a 1,0, è decisa per sessione, e una modifica ha effetto immediato. Aumentarla aggiunge solo sessioni, ridurla ne toglie soltanto. Riguarda ciò che registra la cattura: sessioni, schermate e tap sono telemetria, e non li tocca. Una registrazione di supporto non viene mai scartata dal campionamento. Se la build e il codice impostano entrambi la frequenza, devono coincidere, altrimenti la cattura parte da 0. Quanto porta con sé ogni sessione catturata dipende dalla sua fedeltà.
Fedeltà RUM
La fedeltà indica quanta parte dello schermo porta con sé un replay. Un replay rientra nel traffico in ingresso del suo piano in base ai byte che archivia, quindi un livello più basso ne consuma meno.
| Fedeltà | Cosa mostra un replay | Un minuto aggiunge |
|---|---|---|
| Events | La timeline di schermate, tap, chiamate di rete, span, errori e crash. Nessuna immagine dello schermo. | Nessun byte di replay |
| Outline | Un riquadro per ogni elemento principale. Niente testo e niente icone. | 62 KB |
| Wireframe | Anche testo, icone e controlli più piccoli, ciascuno disegnato come un riquadro. Il testo appare come barre grigie e nessun carattere lascia il dispositivo. | 81 KB |
| Shadow | Uno screenshot reale, sfocato a blocchi in modo che il testo non sia leggibile. | 430 KB |
| Pixel | Lo screenshot reale, come lo ha visto l’utente. | 597 KB |
| Pixel, testo digitato nascosto | Lo screenshot, con il testo digitato dagli utenti coperto. | 516 KB |
| Pixel, tutto il testo nascosto | Lo screenshot, con tutto il testo coperto. | 438 KB |
Misurato sull’app demo Alpine Trails a novembre 2026. Una sessione Pixel di cinque minuti aggiunge circa 3 MB. Le schermate della sua app saranno diverse.
| Impostazione | Variabile d’ambiente | Durante l’esecuzione |
|---|---|---|
| Livello dell’app | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| Livello di una schermata | Nessuna | setFidelity(level, route: '/checkout') |
| Livello massimo che una build può inviare | DARTASTIC_RUM_FIDELITY_MAX | Nessuna |
| Testo nascosto a Pixel | Nessuna | ReplayCaptureController.setMasking() |
| Replay attivo o disattivo | Nessuna | ReplayCaptureController.setMode() |
I livelli sono events, outline, wireframe, shadow e pixel. Ogni variabile d’ambiente qui è una --dart-define, impostata in fase di build.
- Livello dell’app: se la build e il codice lo impostano entrambi, devono coincidere. Se non coincidono, o se un valore non è un livello, la cattura lo segnala e resta su Events. Una registrazione di supporto può alzare il livello, e un’impostazione più bassa su una schermata resta valida su quella schermata.
- Livello massimo: il motore scarta qualsiasi record di replay sopra questo livello, qualunque cosa chiedano la sua app o una registrazione. Lo usi per certificare una build, per esempio una che non può catturare pixel.
- Testo nascosto a Pixel:
ReplayMasking.textFieldsnasconde ciò che digitano gli utenti, eReplayMasking.allTextnasconde tutto il testo. - Replay attivo o disattivo: il replay è disattivato finché l’app non imposta una modalità.
ReplayMode.bufferUntilTriggerconserva i frame sul dispositivo e li carica solo quando qualcosa va storto, quindi una sessione in cui non si rompe nulla non carica alcun replay.
Webview
Una pagina web all’interno della sua app, come un flusso di pagamento o un centro assistenza, può inviare i suoi errori, le richieste, le web vitals e gli eventi nella sessione dell’app, contrassegnati dartastic.telemetry.source webview. La pagina non esporta mai, non conserva un token e non vede un endpoint. Invia i dati alla sua app, che controlla ogni campo e li manda attraverso la pipeline dell’app stessa. La telemetria delle webview è una funzionalità Pro.
Indichi gli host di cui si fida. Una pagina corrisponde all’host esatto o a un sottodominio di una voce, e un elenco vuoto mantiene il bridge disattivato.
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);Tutto ciò che invia una pagina consentita viaggia con le credenziali di telemetria della sua app, e nulla lo maschera sul server. L’elenco allowedHosts e i limiti di dimensione del bridge sono il contenimento.
Con webview_flutter (4.9.0 e successive)
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();Con flutter_inappwebview (6.1.5 e successive)
Imposti transport: DartasticWebviewTransport.inAppWebViewHandler sul bridge e lasci JavaScript attivo.
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);
}
},
)Cosa arriva
- iOS e macOS:
shimForCommittedPage(1.32.0 e successive) è obbligatorio su queste piattaforme e altrove non fa nulla. Senza, una pagina su queste piattaforme invia solo il suo span di pagina. - webview_flutter su iOS e macOS: errori e richieste precedenti al completamento del caricamento della pagina non vengono catturati, e una pagina che non termina mai il caricamento invia solo il suo span. Le web vitals arrivano comunque, perché il browser le mette in buffer. Quando contano, usi flutter_inappwebview, che cattura dall’inizio del documento.
- Web vitals: TTFB e FCP arrivano ovunque. LCP, CLS, INP e i long task arrivano dove la piattaforma li misura. Android WebView li misura tutti e quattro. Su iOS 27, WKWebView non riporta né CLS né long task, e LCP e INP non sono confermati. Il bridge non inventa mai un valore.
- Tap: un tap su una platform view, come una webview o una mappa, viene registrato ma non conta mai come tap senza effetto o rage tap.