Estas páginas muestran las URL de Cloud. Inicie sesión en Dedicated y muestran las de su servidor.

Agregar OTel a su app

Agregue Dartastic OpenTelemetry a una app Flutter o a un servidor Dart en tres pasos: agregue los paquetes, inicialice una vez al arrancar y dé a la compilación su endpoint OTLP y su token. Sus trazas, logs y métricas llegan a su Observatory.

DESARROLLOARQUITECTURA DE DARTASTICUSUARIOStokensticketstoken de Pubpushintercambio de CIlas apps llegan a los usuarios: tiendas de apps, la web, servidoressímboloscrashespilas de llamadascódigo fuentetelemetríaEquipo del desarrolladorflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomcrear tokens · control de acceso por rolesPlano de controlorganizaciones · roles · tokensDartastic Pubpaquetes · código fuenteObservatorysesiones · trazas · logsSymbolizercrashes → líneas de códigoDartastic AIrespuestas a partir de ambosGestor de ticketsGitHub · Jira · LinearApps móviles y de escritorioteléfonos · tabletas · equiposenvía con un token OTLPApps weben navegadoresenvía con un token Browser OTLPServidores Dartbackends · serviciosenvía con un token OTLP

Lo que necesita

  • La versión correcta de Flutter y Dart. Crear su primera app indica lo que necesita cada paquete.
  • Un token OTLP. En el Control Room, abra Tokens, elija Generate y luego OTLP. Se muestra una sola vez: guárdelo en su gestor de contraseñas o en los secretos de su CI. Para Flutter web, use en su lugar un token Browser OTLP (Browser OTLP).
  • Su endpoint OTLP: https://otlp.cloud.dartastic.io.
  • Acceso a Dartastic Pub para los paquetes: dart pub token add https://pub.dartastic.io con un token de Pub.
[PENDIENTE: captura de pantalla de Control Room, “Tokens”: “Generate”, luego “OTLP”, y el nuevo token mostrado una sola vez]

Una app Flutter

Agregue los dos paquetes a pubspec.yaml. Se publican juntos y mantienen una misma versión:

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

Inicialice una vez, antes de 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 da nombre a su app en el Observatory. Elija un nombre que la gente reconozca; no tiene que ser el nombre de su paquete.
  • app.build_id es la identidad de compilación de su app. El paquete de Flutter lo define por usted, a partir de la versión y el número de compilación de su app (Su id de compilación). Los crashes y las comparaciones entre versiones se agrupan por él.
  • DartasticViewObserver registra una vista de pantalla cada vez que se agrega una ruta, y cuánto tiempo estuvo abierta cada pantalla.

Dé a la compilación su endpoint y su token con --dart-define. Una app de teléfono no ve el entorno de su terminal, así que los defines son la forma en que los valores le llegan. Mantenga el token fuera del control de código fuente: póngalo en una variable de entorno en su equipo o en su CI, y pase esa 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"

Son las variables estándar de OpenTelemetry. Escriba authorization en minúsculas: funciona con todos los protocolos. Un token OTLP solo puede enviar telemetría a su organización: no lee nada ni cambia nada.

Una vez que DOTel.initialize termina, registra sin más código:

  • una sesión por cada visita, en cada span y cada registro de log;
  • los toques, y la rapidez con que la app responde a ellos;
  • las vistas de pantalla, mediante DartasticViewObserver;
  • y, según lo que incluya su plan, crashes, UI congelada, jank y métricas vitales.

Su id de compilación

El id de compilación sale de la versión y el número de compilación que cada plataforma informa para su app:

La versión de su appAndroidiOS
version: 1.4.0+27 en pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 en pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.4.0+27

Android agrega +1 a una versión sin número de compilación, porque ese es el número de compilación predeterminado de Flutter allí. Para tener un mismo id de compilación en todas las plataformas, dé a su versión un número de compilación (1.4.0+27).

Un servidor Dart

Un servidor Dart o una app de línea de comandos necesita un solo paquete:

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

En un servidor, las mismas dos variables vienen del entorno:

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 telemetría nunca rompe su app

La regla de OpenTelemetry es que la telemetría nunca debe lanzar un error a su código en tiempo de ejecución. Dartastic la cumple en todas partes. Cuando algo falla dentro de la telemetría (un endpoint inalcanzable, un atributo con un valor incorrecto, una exportación que falla), el error se informa al gestor de errores de OpenTelemetry y se registra en el log, y su app sigue funcionando.

Para ver esos informes en su propio sistema de logs o de informes de crashes, instale su propio gestor. Funciona tanto si lo llama antes como después de 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);
});
  • Sin un gestor, los errores se registran con el log propio de OpenTelemetry (OTEL_LOG_LEVEL define cuánto detalle da).
  • Un gestor propio es el único lugar donde un error se puede volver a lanzar, por ejemplo para fallar rápido en una compilación de prueba. En producción, registre el error y continúe.

Verla llegar

Ejecute su app y úsela durante un minuto; luego abra “Traces” o “Logs” en el Observatory: su serviceName está ahí (Observatory).

[PENDIENTE: captura de pantalla de la pantalla “Traces” del Observatory con la primera traza de la app]
Lo que veQué hacer
No llega nadaRevise el endpoint. Ejecute una vez con --dart-define=OTEL_LOG_LEVEL=debug (o OTEL_LOG_LEVEL=debug en un servidor): el log dice OTelEnv: Parsed 1 header(s) cuando su token llegó a la app, con su valor oculto.
Las exportaciones se rechazan con 401El token es incorrecto, está revocado o es de otra organización o de otro despliegue. Genere un nuevo token OTLP en el Control Room de esta organización.
Flutter web no envía nadaLa web necesita un token Browser OTLP con el origen de su sitio (Browser OTLP).

Cuánto envía

Lo que envía su app cuenta para el tráfico de entrada de su plan, tanto en Cloud como en Dedicated (Precios). Las trazas, las métricas y los logs están activados de forma predeterminada, y sin ninguno de estos ajustes no se descarta nada por muestreo. La captura de pantalla RUM está desactivada de forma predeterminada. Cada uno se puede definir con una variable de entorno y cambiar mientras su app se ejecuta. Su app decide cuándo cambiar uno y llama al setter. No hay ningún ajuste remoto.

SeñalVariable de entornoMientras su app se ejecuta
Trazas, en DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Trazas, en el motorDARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
LogsDARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
MétricasDARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
Captura de pantalla RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.setRumSampleRate()

En teléfonos y en la web, una variable de entorno es un --dart-define, definido al compilar. Un valor en el código tiene prioridad sobre la variable de entorno, y un cambio mientras su app se ejecuta tiene prioridad sobre ambos. Un valor incorrecto se informa por su nombre al gestor de errores de OpenTelemetry, y se mantiene lo que estaba en vigor.

  • Trazas, en el motor: un cambio se aplica en el siguiente lote. Los spans que un muestreador tail aún retiene pasan de inmediato por el nuevo muestreador, así que un cambio nunca los pierde.
  • Logs: la tasa va de 0.0 a 1.0 y se decide por sesión, así que una sesión se conserva o se descarta entera, y subir la tasa solo agrega sesiones. Un registro de ERROR o superior siempre sale, así que los crashes y los ANR graves siempre llegan. Las vistas de pantalla y los toques son registros de log, así que una sesión descartada aquí no tiene ninguno en su línea de tiempo.
  • Métricas: la tasa va de 0.0 a 1.0 y reduce los ciclos de exportación: con 0.25, envía uno de cada cuatro ciclos periódicos. Los totales acumulados siguen siendo correctos. DOTel.flushMetrics y el cierre siempre envían, salvo con 0, que no envía nada.
  • Captura de pantalla RUM: la tasa va de 0.0 a 1.0, se decide por sesión y un cambio se aplica de inmediato. Subirla solo agrega sesiones, y bajarla solo las quita. Abarca lo que registra la captura: las sesiones, las pantallas y los toques son telemetría, y no los afecta. Una grabación de soporte nunca se descarta por muestreo. Si la compilación y su código definen la tasa, deben coincidir; si no, la captura empieza en 0. Cuánto lleva cada sesión capturada depende de su fidelidad.

Fidelidad RUM

La fidelidad es cuánto de la pantalla lleva una reproducción. Una reproducción cuenta para el tráfico de entrada de su plan por los bytes que almacena, así que un nivel más bajo consume menos.

FidelidadQué muestra una reproducciónUn minuto agrega
EventsLa línea de tiempo de pantallas, toques, llamadas de red, spans, errores y crashes. Sin imagen de la pantalla.Sin bytes de reproducción
OutlineUn recuadro por cada elemento principal. Sin texto ni iconos.62 KB
WireframeTambién el texto, los iconos y los controles más pequeños, cada uno dibujado como un recuadro. El texto aparece como barras grises y ningún carácter sale del dispositivo.81 KB
ShadowUna captura de pantalla real, difuminada en bloques para que el texto no se pueda leer.430 KB
PixelLa captura de pantalla real, tal como la vio el usuario.597 KB
Pixel, texto escrito ocultoLa captura, con lo que escriben los usuarios tapado.516 KB
Pixel, todo el texto ocultoLa captura, con todo el texto tapado.438 KB

Medido en la app de demostración Alpine Trails en noviembre de 2026. Una sesión Pixel de cinco minutos agrega unos 3 MB. Con las pantallas de su app, la cifra varía.

AjusteVariable de entornoMientras su app se ejecuta
El nivel de su appDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
El nivel de una pantallaNo haysetFidelity(level, route: '/checkout')
El nivel más alto que puede enviar una compilaciónDARTASTIC_RUM_FIDELITY_MAXNo hay
Texto oculto en PixelNo hayReplayCaptureController.setMasking()
Reproducción activada o desactivadaNo hayReplayCaptureController.setMode()

Los niveles son events, outline, wireframe, shadow y pixel. Cada variable de entorno de aquí es un --dart-define, definido al compilar.

  • El nivel de su app: si la compilación y su código lo definen, deben coincidir. Si no coinciden, o un valor no es un nivel, la captura lo informa y se queda en Events. Una grabación de soporte puede subir el nivel, y un ajuste más bajo en una pantalla se mantiene en esa pantalla.
  • El nivel más alto: el motor descarta cualquier registro de reproducción por encima de él, pida lo que pida su app o una grabación. Úselo para certificar una compilación, por ejemplo una que no puede capturar píxeles.
  • Texto oculto en Pixel: ReplayMasking.textFields oculta lo que escriben los usuarios, y ReplayMasking.allText oculta todo el texto.
  • Reproducción activada o desactivada: la reproducción está desactivada hasta que su app define un modo. ReplayMode.bufferUntilTrigger guarda los fotogramas en el dispositivo y solo los sube cuando algo falla, así que una sesión en la que nada falla no sube ninguna reproducción.

Webviews

Una página web dentro de su app, como un proceso de pago o un centro de ayuda, puede enviar sus errores, solicitudes, métricas web vitals y eventos a la sesión de la app, marcados con dartastic.telemetry.source webview. La página nunca exporta, no tiene ningún token ni ve ningún endpoint. Envía sus datos a su app, que comprueba cada campo y los envía por la canalización propia de su app. La telemetría de webviews es una función Pro.

Indique los hosts de confianza. Una página coincide con el host exacto o con un subdominio de una entrada, y una lista vacía mantiene el puente desactivado.

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

Todo lo que envía una página permitida viaja con las credenciales de telemetría de su app, y nada lo enmascara en el servidor. Su lista allowedHosts y los límites de tamaño del puente son la contención.

Con webview_flutter (4.9.0 y posteriores)

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 y posteriores)

Defina transport: DartasticWebviewTransport.inAppWebViewHandler en el puente y deje JavaScript activado.

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

Qué llega

  • iOS y macOS: shimForCommittedPage (1.32.0 y posteriores) es obligatorio allí, y no hace nada en otras plataformas. Sin él, una página en esas plataformas solo envía su span de página.
  • webview_flutter en iOS y macOS: los errores y las solicitudes anteriores a que la página termine de cargar no se capturan, y una página que nunca termina solo envía su span. Las métricas web vitals sí llegan, porque el navegador las almacena. Cuando importan, use flutter_inappwebview, que captura desde el inicio del documento.
  • Web vitals: TTFB y FCP llegan en todas partes. LCP, CLS, INP y las tareas largas llegan donde la plataforma las mide. Android WebView mide las cuatro. En iOS 27, WKWebView no informa CLS ni tareas largas, y LCP e INP no están confirmados allí. El puente nunca inventa un valor.
  • Toques: un toque en una vista de plataforma, como un webview o un mapa, se registra, pero nunca cuenta como toque sin respuesta o de frustración.