Problemas comuns

Comece pela organização, pelo recurso e pelo período selecionados. Depois, verifique a origem do sinal. Um resultado vazio e uma consulta indisponível são situações diferentes.

O agente não aparece

Confira a instalação e os logs:

sudo systemctl status farol-agent --no-pager
sudo journalctl -u farol-agent -n 100 --no-pager
sudo -u farol-agent farol-agent check-config --config /etc/farol-agent/config.yaml

Confirme a saída HTTPS do servidor, a validade do token de instalação e se a organização escolhida é a mesma que emitiu o token. Não reutilize um token consumido e não copie a identidade de outra máquina.

O agente aparece, mas os logs não chegam

• Confira se a fonte está habilitada em config.yaml.
• Confira a permissão de envio de logs na credencial do agente.
• Para arquivos, confirme o caminho e o acesso pelo usuário farol-agent.
• Para Docker, confira o socket e as permissões necessárias.
• Confira o nome service e o campo environment usados no filtro.
• Gere uma linha nova após aplicar a configuração; não use só a existência de um arquivo antigo como prova de coleta.

O serviço está cadastrado, mas não tem traces

O cadastro não instrumenta o processo. Confira a inicialização do SDK, service.name, o endpoint /v1/ingest/traces e o escopo DATA_PLANE_TRACES.

Faça uma requisição instrumentada e confira o shutdown do exporter em processos curtos. Para a separação por ambiente, use deployment.environment.name com o slug do catálogo.

O erro não aparece

Confira o DSN completo, seu vínculo com o serviço e a permissão DATA_PLANE_ERRORS. Gere um erro controlado no servidor e espere o envio do SDK antes de encerrar o processo. Não use o teste Node.js deste guia como prova de captura no navegador.

O monitor recusa o alvo

Os checks HTTP, TCP e TLS acessam alvos públicos. Endereços privados, loopback, link-local, metadados e DNS que resolve para faixas bloqueadas são recusados. Confira também o formato: HTTP usa URL completa; TCP e TLS usam host:porta.

O uptime está desconhecido

Confira os horários das amostras e a cobertura das localizações. Ausência de dado ou amostra antiga não representa sucesso. Se uma localização não executa verificações, cadastrar seu nome não cria um prober nela.

Respostas na ingestão

Resposta	O que conferir
401	Credencial ausente, inválida, expirada ou revogada
403	Escopo necessário e acesso ao recurso
413	Tamanho do evento ou lote; reduza o payload
429	Limite de envio; respeite o backoff e Retry-After quando presente
503	Indisponibilidade temporária; preserve a fila e a retentativa

Informações para pedir ajuda

Informe o recurso, o horário com fuso, o sinal afetado, a versão do agente ou SDK e a mensagem de erro sem segredos. Se houver um identificador de requisição, inclua-o.

Não envie tokens, a URL secreta do heartbeat, o DSN completo ou identity.json. Remova dados sensíveis de logs e capturas de tela antes de compartilhar.