Enviar traces com OpenTelemetry
As traces são enviadas pelo SDK ou agente OpenTelemetry da aplicação ao gateway de ingestão do Farol. Elas não dependem do agente de métricas do servidor.
Prepare a credencial e a identidade
- Cadastre o serviço e o ambiente no Farol.
- Emita uma credencial de aplicação com o escopo
DATA_PLANE_TRACES. - Guarde a credencial
app_no gerenciador de segredos do deploy. - Confirme o endpoint de ingestão do seu ambiente.
Configure OTLP/HTTP
Para uma distribuição OpenTelemetry que aceite as variáveis padrão, como o Java agent oficial:
OTEL_SERVICE_NAME=checkout-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=2026.10.01
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://farol-ingest.paxsoft.com.br/v1/ingest/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20app_SUBSTITUA_PELO_SEGREDO
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
O endpoint acima corresponde ao ambiente Farol da Paxsoft. Se recebeu outro endpoint, use-o com o caminho /v1/ingest/traces. A credencial do exemplo é um placeholder e precisa ser substituída pelo segredo emitido.
O espaço de Bearer <credencial> está codificado como %20 no formato de headers das variáveis OpenTelemetry. Quando configurar um exporter por código, siga o formato de headers exigido por esse SDK.
Não acrescente um header de organização ao cliente. Não use os caminhos internos do Tempo ou um endereço de consulta no lugar do endpoint público de ingestão.
Ative a instrumentação
As variáveis não instalam o SDK nem instrumentam o código automaticamente. Escolha a integração adequada:
| Stack | Integração |
|---|---|
| Java / Spring Boot | Anexe o Java agent OpenTelemetry e configure as variáveis antes de iniciar a JVM |
| Node.js / Next.js no servidor | Inicialize um SDK OpenTelemetry antes da aplicação; respeite o runtime Node.js e confira o build de produção |
| Go | Inicialize provider, exporter OTLP/HTTP e propagação; use middleware HTTP instrumentado |
Os exportadores de métricas e logs estão desligados no exemplo porque esses sinais podem ser coletados pelo agente Farol. Se adotar outra estratégia, evite duplicar o envio do mesmo sinal.
Combine com erros
Ao combinar Sentry e OpenTelemetry, mantenha um único dono do provider OpenTelemetry. O SDK de erros deve ler o contexto ativo, enquanto o exporter OTLP envia a trace.
Desligue a performance do Sentry nessa montagem. Dois providers independentes podem produzir IDs diferentes para a mesma requisição.
Confirme que funcionou
Faça uma requisição HTTP instrumentada e consulte Traces no Farol, pelo serviço e período recente. Abra a trace e confira os spans, a duração e o ambiente. Para erros, confira o status do span de servidor.
Se o logger inclui o ID do span ativo, busque o mesmo trace_id nos logs. No encerramento gracioso, faça flush ou shutdown do SDK: filas em memória podem perder dados quando o processo é encerrado à força.
Falhas 401 indicam problema de credencial; 403 pode indicar falta de escopo. Para 413, reduza o lote; para 429 e falhas transitórias, configure backoff no SDK. Veja problemas comuns.