Adicionar OTel ao seu app
Adicione o Dartastic OpenTelemetry a um app Flutter ou a um servidor Dart em três passos: adicione os packages, inicialize uma vez na inicialização e passe ao build seu endpoint OTLP e seu token. Seus traces, logs e métricas chegam ao seu Observatory.
Do que você precisa
- As versões certas de Flutter e Dart. Como criar seu primeiro app lista o que cada package exige.
- Um token OTLP. No Control Room, abra Tokens, escolha Generate e depois OTLP. Ele é mostrado uma única vez: guarde-o no seu gerenciador de senhas ou nos secrets do seu CI. Para Flutter web, use um token Browser OTLP (Browser OTLP).
- Seu endpoint OTLP:
https://otlp.cloud.dartastic.io. - Acesso ao Dartastic Pub para os packages:
dart pub token add https://pub.dartastic.iocom um token do Pub.
Um app Flutter
Adicione os dois packages ao pubspec.yaml. Eles são lançados juntos e ficam sempre na mesma versão:
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.4Inicialize uma 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(),
));
}serviceNamedá nome ao seu app no Observatory. Escolha um nome que as pessoas reconheçam; não precisa ser o nome do seu package.app.build_idé a identidade do build do seu app. O package Flutter define esse valor para você, a partir da versão e do número de build do seu app (Seu build id). Crashes e comparações entre versões são agrupados por ele.DartasticViewObserverregistra uma visualização de tela sempre que uma rota é empilhada, e quanto tempo cada tela ficou aberta.
Passe ao build seu endpoint e seu token com --dart-define. Um app de celular não vê as variáveis de ambiente do seu shell, então os defines são o caminho para os valores chegarem a ele. Mantenha o token fora do controle de versão: coloque-o em uma variável de ambiente na sua máquina ou no CI e passe essa variável.
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"Estas são as variáveis padrão do OpenTelemetry. Mantenha authorization em minúsculas: assim funciona em todos os protocolos. Um token OTLP só pode enviar telemetria para a sua organização: ele não lê nada e não altera nada.
Depois que DOTel.initialize termina, ele registra sem nenhum código adicional:
- uma sessão para cada visita, em cada span e registro de log;
- toques, e com que rapidez o app responde a eles;
- visualizações de tela, por meio de
DartasticViewObserver; - e, conforme o seu plano os inclua, crashes, UI congelada, jank e métricas vitais.
Seu build id
O build id vem da versão e do número de build que cada plataforma informa para o seu app:
| A versão do seu app | Android | iOS |
|---|---|---|
version: 1.4.0+27 em pubspec.yaml | 1.4.0+27 | 1.4.0+27 |
version: 1.4.0 em 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 |
O Android acrescenta +1 a uma versão sem número de build, porque esse é o número de build padrão do Flutter lá. Para ter um único build id em todas as plataformas, dê um número de build à sua versão (1.4.0+27).
Um servidor Dart
Um servidor Dart ou um app de linha de comando precisa de um único 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 ...
}Em um servidor, as mesmas duas variáveis vêm do 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.dartA telemetria nunca quebra seu app
A regra do OpenTelemetry é que a telemetria nunca deve lançar um erro no seu código em tempo de execução. A Dartastic segue essa regra em todo lugar. Quando algo dá errado dentro da telemetria (um endpoint inacessível, um atributo com valor inválido, uma exportação que falha), o erro é informado ao error handler do OpenTelemetry e registrado em log, e seu app continua rodando.
Para ver esses erros no seu próprio sistema de logs ou de relatório de crashes, instale seu próprio handler. Ele funciona tanto se você o chamar antes quanto depois 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);
});- Sem um handler, os erros são registrados no log do próprio OpenTelemetry (
OTEL_LOG_LEVELdefine o nível de detalhe). - Um handler seu é o único lugar em que um erro pode ser relançado, por exemplo para falhar rápido em um build de teste. Em produção, registre no log e retorne.
Ver os dados chegarem
Rode seu app e use-o por um minuto, depois abra “Traces” ou “Logs” no Observatory: seu serviceName está lá (Observatory).
| O que você vê | O que fazer |
|---|---|
| Nada chega | Confira o endpoint. Rode uma vez com --dart-define=OTEL_LOG_LEVEL=debug (ou OTEL_LOG_LEVEL=debug em um servidor): o log mostra OTelEnv: Parsed 1 header(s) quando seu token chegou ao app, com o valor oculto. |
| As exportações são recusadas com 401 | O token está errado, foi revogado ou é de outra organização ou deployment. Gere um novo token OTLP no Control Room desta organização. |
| O Flutter web não envia nada | A web precisa de um token Browser OTLP com a origem do seu site cadastrada nele (Browser OTLP). |
Quanto você envia
O que seu app envia conta para o tráfego de entrada do seu plano, tanto no Cloud quanto no Dedicated (Preços). Traces, métricas e logs vêm ativados por padrão e, sem nenhuma destas configurações, nada é descartado por amostragem. A captura de tela do RUM vem desativada por padrão. Cada uma pode ser definida por uma variável de ambiente e alterada enquanto seu app roda. Seu app decide quando alterar uma delas e chama o setter. Não há configuração remota.
| Sinal | Variável de ambiente | Com o app rodando |
|---|---|---|
| Traces, no Dart | OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | DOTel.tracesSampler |
| Traces, no 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 tela do RUM | DARTASTIC_RUM_SAMPLE_RATE | ReplayCaptureController.setRumSampleRate() |
Em celulares e na web, uma variável de ambiente é um --dart-define, definido no build. Um valor no código prevalece sobre a variável de ambiente, e uma alteração com o app rodando prevalece sobre ambos. Um valor inválido vai para o error handler do OpenTelemetry pelo nome, e o que estava em vigor continua valendo.
- Traces, no motor: uma alteração vale a partir do próximo lote. Os spans que um amostrador
tailainda retém passam pelo novo amostrador na hora, então uma alteração nunca os perde. - Logs: a taxa vai de 0.0 a 1.0 e é decidida por sessão, então uma sessão é mantida ou descartada por inteiro, e aumentar a taxa apenas acrescenta sessões. Um registro de
ERRORou acima sempre é enviado, então crashes e ANRs graves sempre chegam. Visualizações de tela e toques são registros de log, então uma sessão descartada aqui não tem nenhum deles na linha do tempo. - Métricas: a taxa vai de 0.0 a 1.0 e reduz os ciclos de exportação: com 0.25, um em cada quatro ciclos periódicos envia. Os totais cumulativos continuam corretos.
DOTel.flushMetricse o encerramento sempre enviam, exceto com 0, que não envia nada. - Captura de tela do RUM: a taxa vai de 0.0 a 1.0, é decidida por sessão, e uma alteração vale na hora. Aumentá-la apenas acrescenta sessões, e diminuí-la apenas remove sessões. Ela vale para o que a captura registra: sessões, telas e toques são telemetria, e ela não mexe neles. Uma gravação de suporte nunca é descartada por amostragem. Se o build e o seu código definirem a taxa, os dois precisam concordar, ou a captura começa em 0. Quanto cada sessão capturada carrega é a sua fidelidade.
Fidelidade do RUM
A fidelidade é quanto da tela um replay carrega. Um replay conta para o tráfego de entrada do seu plano pelos bytes que armazena, então um nível mais baixo consome menos dele.
| Fidelidade | O que um replay mostra | Um minuto acrescenta |
|---|---|---|
| Events | A linha do tempo de telas, toques, chamadas de rede, spans, erros e crashes. Nenhuma imagem da tela. | Nenhum byte de replay |
| Outline | Um retângulo para cada elemento principal. Sem texto e sem ícones. | 62 KB |
| Wireframe | Também texto, ícones e controles menores, cada um desenhado como um retângulo. O texto aparece como barras cinza, e nenhum caractere sai do dispositivo. | 81 KB |
| Shadow | Uma captura de tela real, desfocada em blocos para que o texto não possa ser lido. | 430 KB |
| Pixel | A captura de tela real, como o usuário a viu. | 597 KB |
| Pixel, texto digitado oculto | A captura de tela, com o que os usuários digitam coberto. | 516 KB |
| Pixel, todo o texto oculto | A captura de tela, com todo o texto coberto. | 438 KB |
Medido no app de demonstração Alpine Trails em novembro de 2026. Uma sessão Pixel de cinco minutos adiciona cerca de 3 MB. As telas do seu app vão variar.
| Configuração | Variável de ambiente | Com o app rodando |
|---|---|---|
| O nível do seu app | DARTASTIC_RUM_FIDELITY | ReplayCaptureController.setFidelity() |
| O nível de uma tela | Nenhum | setFidelity(level, route: '/checkout') |
| O nível mais alto que um build pode enviar | DARTASTIC_RUM_FIDELITY_MAX | Nenhum |
| Texto oculto no Pixel | Nenhum | ReplayCaptureController.setMasking() |
| Replay ligado ou desligado | Nenhum | ReplayCaptureController.setMode() |
Os níveis são events, outline, wireframe, shadow e pixel. Cada variável de ambiente aqui é um --dart-define, definido no build.
- O nível do seu app: se o build e o seu código o definirem, os dois precisam concordar. Se não concordarem, ou se um valor não for um nível, a captura informa o problema e fica em Events. Uma gravação de suporte pode elevar o nível, e uma configuração mais baixa em uma tela continua valendo nessa tela.
- O nível mais alto: o motor descarta qualquer registro de replay acima dele, não importa o que seu app ou uma gravação peça. Use-o para certificar um build, por exemplo um que não pode capturar pixels.
- Texto oculto no Pixel:
ReplayMasking.textFieldsoculta o que os usuários digitam, eReplayMasking.allTextoculta todo o texto. - Replay ligado ou desligado: o replay fica desligado até seu app definir um modo.
ReplayMode.bufferUntilTriggermantém os frames no dispositivo e só faz upload deles quando algo dá errado, então uma sessão em que nada quebra não envia nenhum replay.
Webviews
Uma página web dentro do seu app, como um checkout ou uma central de ajuda, pode enviar seus erros, requisições, web vitals e eventos para a sessão do app, marcados com dartastic.telemetry.source webview. A página nunca exporta, nunca guarda um token e nunca vê um endpoint. Ela envia os dados ao seu app, que verifica cada campo e os envia pelo pipeline do próprio app. A telemetria de webviews é um recurso Pro.
Indique os hosts em que você confia. Uma página corresponde quando tem exatamente o host de uma entrada ou é um subdomínio dela, e uma lista vazia mantém a ponte desligada.
final bridge = DartasticWebviewBridge(
allowedHosts: ['checkout.example.com', 'example.com'],
serviceName: 'web-checkout',
transport: DartasticWebviewTransport.javaScriptChannel,
);Tudo o que uma página permitida envia usa as credenciais de telemetria do seu app, e nada mascara esses dados no servidor. Sua lista allowedHosts e os limites de tamanho da ponte são a contenção.
Com webview_flutter (4.9.0 e 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();Com flutter_inappwebview (6.1.5 e posteriores)
Defina transport: DartasticWebviewTransport.inAppWebViewHandler na ponte e deixe o JavaScript ativado.
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);
}
},
)O que chega
- iOS e macOS:
shimForCommittedPage(1.32.0 e posteriores) é obrigatório nessas plataformas e não faz nada nas demais. Sem ele, uma página nessas plataformas envia apenas o span da página. - webview_flutter no iOS e no macOS: erros e requisições de antes de a página terminar de carregar não são capturados, e uma página que nunca termina de carregar envia apenas o seu span. As métricas vitais ainda chegam, porque o navegador as mantém em buffer. Quando elas importam, use flutter_inappwebview, que captura desde o início do documento.
- Web vitals: TTFB e FCP chegam em todas as plataformas. LCP, CLS, INP e tarefas longas chegam onde a plataforma os mede. O Android WebView mede os quatro. No iOS 27, o WKWebView não informa CLS nem tarefas longas, e LCP e INP não estão confirmados ali. A ponte nunca inventa um valor.
- Toques: um toque em uma platform view, como uma webview ou um mapa, é registrado, mas nunca é contado como toque inativo ou toque de raiva.