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.
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.iocon un token de Pub.
Una app Flutter
Agregue los dos paquetes a pubspec.yaml. Se publican juntos y mantienen una misma versión:
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.4Inicialice una vez, antes de 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(),
));
}serviceNameda 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_ides 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.DartasticViewObserverregistra 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.
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 app | Android | iOS |
|---|---|---|
version: 1.4.0+27 en pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 en 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 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:
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 ...
}En un servidor, las mismas dos variables vienen del entorno:
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 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:
// 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_LEVELdefine 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).
| Lo que ve | Qué hacer |
|---|---|
| No llega nada | Revise 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 401 | El 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 nada | La 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ñal | Variable de entorno | Mientras su app se ejecuta |
|---|---|---|
| Trazas, en Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Trazas, en el motor | DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UP | DOTel.setEngineSampler() |
| Logs | DARTASTIC_LOGS_SAMPLE_RATE | DOTel.logsSampleRate |
| Métricas | DARTASTIC_METRICS_SAMPLE_RATE | DOTel.metricsSampleRate |
| Captura de pantalla RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.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
tailaú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
ERRORo 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.flushMetricsy 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.
| Fidelidad | Qué muestra una reproducción | Un minuto agrega |
|---|---|---|
| Events | La línea de tiempo de pantallas, toques, llamadas de red, spans, errores y crashes. Sin imagen de la pantalla. | Sin bytes de reproducción |
| Outline | Un recuadro por cada elemento principal. Sin texto ni iconos. | 62 KB |
| Wireframe | Tambié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 |
| Shadow | Una captura de pantalla real, difuminada en bloques para que el texto no se pueda leer. | 430 KB |
| Pixel | La captura de pantalla real, tal como la vio el usuario. | 597 KB |
| Pixel, texto escrito oculto | La captura, con lo que escriben los usuarios tapado. | 516 KB |
| Pixel, todo el texto oculto | La 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.
| Ajuste | Variable de entorno | Mientras su app se ejecuta |
|---|---|---|
| El nivel de su app | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| El nivel de una pantalla | No hay | setFidelity(level, route: '/checkout') |
| El nivel más alto que puede enviar una compilación | DARTASTIC_RUM_FIDELITY_MAX | No hay |
| Texto oculto en Pixel | No hay | ReplayCaptureController.setMasking() |
| Reproducción activada o desactivada | No hay | ReplayCaptureController.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.textFieldsoculta lo que escriben los usuarios, yReplayMasking.allTextoculta todo el texto. - Reproducción activada o desactivada: la reproducción está desactivada hasta que su app define un modo.
ReplayMode.bufferUntilTriggerguarda 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.
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)
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.
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.