Queste pagine mostrano gli URL di Cloud. Acceda su Dedicated e vedrà quelli del suo server.

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.

BUILDARCHITETTURA DARTASTICUTENTItokentickettoken Pubpushscambio CIle app arrivano agli utenti: app store, web, serversimbolicrashstack tracecodice sorgentetelemetriaComputer dello sviluppatoreflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomcreazione di token · controllo degli accessi basato sui ruoliPiano di controlloorganizzazioni · ruoli · tokenDartastic Pubpacchetti · codice sorgenteObservatorysessioni · tracce · logSymbolizercrash → righe di codice sorgenteDartastic AIrisposte da entrambiSistema di ticketingGitHub · Jira · LinearApp mobile e desktoptelefoni · tablet · computerinvia con un token OTLPApp webnei browserinvia con un token Browser OTLPServer Dartbackend · serviziinvia con un token OTLP

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.io con un token Pub.
[TODO: screenshot di Control Room, « Tokens »: « Generate », poi « OTLP », e il nuovo token mostrato una sola volta]

Un’app Flutter

Aggiunga i due pacchetti a pubspec.yaml. Escono insieme e restano sulla stessa versione:

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

Inizializzi una volta, prima di 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 dà 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.
  • DartasticViewObserver registra 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.

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"

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

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

Su un server, le stesse due variabili arrivano dall’ambiente:

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

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);
});
  • Senza un gestore, gli errori vengono registrati con il log di OpenTelemetry (OTEL_LOG_LEVEL ne 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).

[TODO: screenshot di la schermata « Traces » dell’Observatory con la prima traccia dell’app]
Cosa vedeCosa fare
Non arriva nullaControlli 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 401Il 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 nullaIl 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.

SegnaleVariabile d’ambienteDurante l’esecuzione
Tracce, in DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Tracce, nel motoreDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MetricheDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Cattura dello schermo RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.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 tail passano 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 ERROR o 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.flushMetrics e 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 replayUn minuto aggiunge
EventsLa timeline di schermate, tap, chiamate di rete, span, errori e crash. Nessuna immagine dello schermo.Nessun byte di replay
OutlineUn riquadro per ogni elemento principale. Niente testo e niente icone.62 KB
WireframeAnche 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
ShadowUno screenshot reale, sfocato a blocchi in modo che il testo non sia leggibile.430 KB
PixelLo screenshot reale, come lo ha visto l’utente.597 KB
Pixel, testo digitato nascostoLo screenshot, con il testo digitato dagli utenti coperto.516 KB
Pixel, tutto il testo nascostoLo 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.

ImpostazioneVariabile d’ambienteDurante l’esecuzione
Livello dell’appDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
Livello di una schermataNessunasetFidelity(level, route: '/checkout')
Livello massimo che una build può inviareDARTASTIC_RUM_FIDELITY_MAXNessuna
Testo nascosto a PixelNessunaReplayCaptureController.setMasking()
Replay attivo o disattivoNessunaReplayCaptureController.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.textFields nasconde ciò che digitano gli utenti, e ReplayMasking.allText nasconde tutto il testo.
  • Replay attivo o disattivo: il replay è disattivato finché l’app non imposta una modalità. ReplayMode.bufferUntilTrigger conserva 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.

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

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

Con flutter_inappwebview (6.1.5 e successive)

Imposti transport: DartasticWebviewTransport.inAppWebViewHandler sul bridge e lasci JavaScript attivo.

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

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.