Pular para o conteúdo
FG Tracker
DocsComeçar
Documentação · Sem dados?

Documentação

Sem dados no painel?

Diagnóstico passo a passo quando o trace não aparece: endpoint, chave, filtros, relógio, encerramento e CORS.

Conferido com o código e os pacotes publicados em 2026-10-16

O SDK envia a cada 2 segundos e o painel atualiza a cada 15. Se depois de meio minuto nada aparecer, siga a ordem abaixo. Ligue debug: true no createTracker enquanto investiga: cada envio bem-sucedido aparece como [fg-tracker] enviados N spans.

1. Leia o console da aplicação

O SDK mostra cada tipo de falha uma vez, até um envio dar certo:

Mensagens do SDK Node e o que fazer
MensagemCausa e correção
[fg-tracker] apiKey ausente: tracker desabilitado.A variável da chave está vazia no processo. Confira o .env e como ele é carregado (por exemplo, node --env-file=.env).
[fg-tracker] falha ao enviar para http://localhost:4050/v1/ingest: … (nova tentativa em N s)Falta endpoint no createTracker. O SDK não lê FG_TRACKER_URL sozinho: passe endpoint: process.env.FG_TRACKER_URL.
[fg-tracker] falha ao enviar para https://…/v1/ingest: … (nova tentativa em N s)Rede, DNS, proxy ou firewall bloqueando a saída HTTPS. O SDK continua tentando com backoff.
[fg-tracker] ingest respondeu 401 (lote descartado)Chave errada, de outro ambiente ou rotacionada. Copie de novo em Configurações → Geral → Chaves de ingestão.
[fg-tracker] logs respondeu 403 (lote descartado)Logs enviados com a chave pública stk_ num projeto restrito. Use a fgsk_ no transporte de logs.
[fg-tracker] falha ao enviar logs para http://localhost:4050/v1/logs: …Falta endpoint no transporte de logs (pino, winston, Nest ou createLogShipper).
[fg-tracker] a API recusou N span(s) (ex.: public_key_not_allowed)stk_ restrita enviando spans de servidor. Troque para a fgsk_.
[fg-tracker] a API recusou N span(s) (ex.: started_at_too_old | started_at_in_future)Relógio da máquina errado (mais de 5 minutos adiantado) ou spans com mais de 14 dias.
Nenhuma linha [fg-tracker], mesmo com debug: trueNenhum span terminou: o middleware está depois das rotas, a requisição não passou por este processo ou o tracker foi criado com enabled: false.

2. Confira os filtros do painel

  • Projeto: o seletor no topo do menu lateral precisa estar no projeto dono da chave.
  • Janela: o padrão é Últimas 24 horas e conta pelo início do span raiz.
  • Raiz: em Traces, o padrão HTTP mostra só traces que começam numa requisição recebida pelo servidor. Jobs, tracker.span('custom', …) e Lambda com wrapLambda aparecem com Jobs ou Todas; erros e fetches do navegador, só com Todas (o seletor não tem opção de navegador). O aviso Aguardando o primeiro sinal do início também só conta requisições HTTP.
  • Ambiente e serviço: as telas de visão geral, endpoints e traces somam todos os ambientes; um ambiente errado não esconde o trace ali, mas some dos filtros por ambiente (banco de dados, releases, SLOs).
  • Papel: viewers veem os dados, mas não as chaves.

3. Pergunte à API

Com um token pessoal com telemetry:read, a saúde da ingestão diz se algo chegou e por que algo foi recusado:

terminal
curl -sS "$FG_TRACKER_URL/v1/projects/$FG_TRACKER_PROJECT_ID/ingest-health?range=1h" \
  -H "authorization: Bearer $FG_TRACKER_TOKEN"
  • lastReceivedAt nulo e ingest.accepted zero: nada chegou ao projeto. Volte ao passo 1 (endpoint, chave, rede).
  • ingest.rejected maior que zero: veja reasons e lastRejection.
  • clockAheadSpans maior que zero: relógio da máquina adiantado.

Pelo MCP, tracker_verify_ingest mostra o último trace (de qualquer tipo de raiz) e o último log dos 15 minutos anteriores.

4. O processo terminou antes?

  • Script que termina sozinho: o SDK envia no beforeExit. Se você chama process.exit(), chame await tracker.shutdown() antes.
  • Handler próprio de SIGTERM/SIGINT: chame await tracker.shutdown() nele.
  • AWS Lambda: use tracker.wrapLambda. Serverless de Next.js: veja a limitação.
  • Erro de CORS em /v1/ingest no console do navegador: a origem do site não está em Domínios permitidos (com protocolo e porta).
  • init lança TypeError: falta endpoint.
  • Aviso de apiKey ausente: a variável pública não foi embutida no build (confira o prefixo VITE_ ou NEXT_PUBLIC_).
  • 401 SERVER_KEY_IN_URL na aba de rede: há uma fgsk_ no front. Troque pela stk_ e rotacione a fgsk_.
  • Requisições feitas com axios ou XMLHttpRequest não aparecem: o pacote só instrumenta fetch.

Conta e acesso

  • 403 EMAIL_VERIFICATION_REQUIRED em qualquer tela: confirme o e-mail (o link é enviado quando você clica em Enviar link de confirmação e vale 30 minutos).
  • O e-mail não chega: confira o spam, espere 1 minuto e reenvie, ou entre com Google ou Meta, que já confirmam o e-mail.
  • Não vê um projeto: peça a um owner ou admin do projeto para convidar o seu e-mail em Configurações → Membros e aceite o convite no painel.