Estas páginas mostram as URLs do Cloud. Faça login no Dedicated e elas passam a mostrar as do seu servidor.

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.

BUILDARQUITETURA DARTASTICUSUÁRIOStokensissuestoken do Pubpushtroca na CIos apps chegam aos usuários: lojas de apps, a web, servidoressímboloscrashesstack tracescódigo-fontetelemetriaComputador do desenvolvedorflutter run · dart pub getCIGitHub Actions, GitLab, …Control Roomcriação de tokens · controle de acesso por papéisPlano de controleorganizações · papéis · tokensDartastic Pubpackages · código-fonteObservatorysessões · traces · logsSymbolizercrashes → linhas do código-fonteDartastic AIrespostas a partir dos doisIssue trackerGitHub · Jira · LinearApps mobile e desktopcelulares · tablets · desktopsenvia com um token OTLPApps webem navegadoresenvia com um token Browser OTLPServidores Dartbackends · serviçosenvia com um token OTLP

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.io com um token do Pub.
[TODO: captura de tela de Control Room, “Tokens”: “Generate”, depois “OTLP”, e o novo token mostrado uma única vez]

Um app Flutter

Adicione os dois packages ao pubspec.yaml. Eles são lançados juntos e ficam sempre na mesma versão:

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

Inicialize uma 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 dá 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.
  • DartasticViewObserver registra 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.

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"

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 appAndroidiOS
version: 1.4.0+27 em pubspec.yaml1.4.0+271.4.0+27
version: 1.4.0 em pubspec.yaml1.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.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:

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

Em um servidor, as mesmas duas variáveis vêm do 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

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

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);
});
  • Sem um handler, os erros são registrados no log do próprio OpenTelemetry (OTEL_LOG_LEVEL define 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).

[TODO: captura de tela de a tela “Traces” do Observatory mostrando o primeiro trace do app]
O que você vêO que fazer
Nada chegaConfira 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 401O 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 nadaA 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.

SinalVariável de ambienteCom o app rodando
Traces, no DartOTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
Traces, no 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 tela do RUMDARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.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 tail ainda 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 ERROR ou 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.flushMetrics e 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.

FidelidadeO que um replay mostraUm minuto acrescenta
EventsA linha do tempo de telas, toques, chamadas de rede, spans, erros e crashes. Nenhuma imagem da tela.Nenhum byte de replay
OutlineUm retângulo para cada elemento principal. Sem texto e sem ícones.62 KB
WireframeTambé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
ShadowUma captura de tela real, desfocada em blocos para que o texto não possa ser lido.430 KB
PixelA captura de tela real, como o usuário a viu.597 KB
Pixel, texto digitado ocultoA captura de tela, com o que os usuários digitam coberto.516 KB
Pixel, todo o texto ocultoA 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çãoVariável de ambienteCom o app rodando
O nível do seu appDARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
O nível de uma telaNenhumsetFidelity(level, route: '/checkout')
O nível mais alto que um build pode enviarDARTASTIC_RUM_FIDELITY_MAXNenhum
Texto oculto no PixelNenhumReplayCaptureController.setMasking()
Replay ligado ou desligadoNenhumReplayCaptureController.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.textFields oculta o que os usuários digitam, e ReplayMasking.allText oculta todo o texto.
  • Replay ligado ou desligado: o replay fica desligado até seu app definir um modo. ReplayMode.bufferUntilTrigger manté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.

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

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

Com flutter_inappwebview (6.1.5 e posteriores)

Defina transport: DartasticWebviewTransport.inAppWebViewHandler na ponte e deixe o JavaScript ativado.

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

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.