Este documento descreve etapas de solução de problemas e problemas comuns ao usar um coletor do OpenTelemetry, como o coletor do OpenTelemetry criado pelo Google, para enviar dados à Observabilidade do Google Cloud.
Resolver problemas com a coleta de dados
Nesta seção, descrevemos estratégias que você pode usar para resolver problemas com a coleta de dados.
Usar o exportador debug
O
exportador debug
é a melhor maneira de ver os dados no nível do OpenTelemetry Collector. O exportador recebe os dados e os grava em stdout em um formato legível. Isso é mais útil quando você precisa verificar se as transformações no pipeline estão produzindo o resultado esperado.
O exportador debug está incluído no OpenTelemetry Collector criado pelo Google. Configure o exportador debug com verbosity: detailed para ver todo o payload de telemetria.
exporters:
debug:
verbosity: detailed
É possível incluir o exportador no pipeline:
service:
pipelines:
metrics:
receivers: [
# ...
]
processors: [
# ...
]
exporters: [
debug, # can be added alongside any other configured exporters
# ...
]
Testar a linguagem de transformação do OpenTelemetry (OTTL) on-line com o OTTL Playground
O OTTL Playground (em inglês) é uma ferramenta desenvolvida pela comunidade que permite desenvolver interativamente um pipeline da linguagem de transformação do OpenTelemetry. Comece fornecendo JSON OTLP como entrada, escreva seu pipeline usando a mesma configuração do coletor do OpenTelemetry e inspecione os resultados visualmente.
A melhor maneira de receber JSON OTLP de um pipeline é colocar um
exportador file
no local antes de onde o processador de transformação estaria. Comece configurando um exportador file:
exporters:
file:
path: example.json
Se você tiver um pipeline como este:
service:
pipelines:
metrics:
receivers: [hostmetrics]
processors: [
memorylimiter,
groupbyattrs,
transform, # where your OTTL pipeline will go
cumulativetodelta,
metricstarttime,
]
exporters: [
otlp,
]
Você pode modificar temporariamente o pipeline para exportar os dados como eles vão aparecer
no processador transform em que você está trabalhando.
service:
pipelines:
metrics:
receivers: [hostmetrics]
processors: [
memorylimiter,
groupbyattrs,
# transform,
# cumulativetodelta,
# metricstarttime,
]
exporters: [
# otlp,
file,
]
O exportador file grava cada payload recebido em uma linha do arquivo.
Você pode usar uma única linha de dados como entrada para o ambiente de simulação da OTTL.
Problemas conhecidos
Esta seção descreve problemas conhecidos com o OpenTelemetry Collector/OpenTelemetry Collector criado pelo Google e como contorná-los, quando possível.
Excesso de erros connect: network is unreachable ao usar o exportador otlp
OBSERVAÇÃO: esse problema se aplica apenas ao exportador gRPC otlp, e não ao exportador HTTP equivalente chamado otlphttp.
OBSERVAÇÃO: até o momento, esse problema foi observado diretamente apenas em ambientes do Compute Engine, mas, devido à natureza dele, não podemos confirmar que ele está limitado ao Compute Engine.
A partir da versão 0.147.0 do OpenTelemetry Collector criado pelo Google e da versão 0.145.0 do OpenTelemetry Collector upstream, o exportador otlp vai usar por padrão a estratégia de balanceamento de carga do lado do cliente round_robin, que antes era pick_first. Quando o exportador usava a estratégia pick_first, ele também tinha um fallback de IPV4 totalmente funcional em um cenário em que o IPV6 não funcionava. A estratégia round_robin não tem essa propriedade e tenta enviar repetidamente para todos os endereços que resolve no momento da inicialização do exportador, mesmo quando eles não funcionam.
Como resultado, se você estiver usando o exportador otlp para enviar dados à API Telemetry, poderá ver mensagens de erro como esta:
2026-02-13T20:50:00.665Z warn grpc@v1.78.0/clientconn.go:1526 [core] [Channel #1 SubChannel #18] grpc: addrConn.createTransport failed to connect to {Addr: "[2607:f8b0:4001:c62::5f]:443", ServerName: "telemetry.googleapis.com:443", }. Err: connection error: desc = "transport: Error while dialing: dial tcp [2607:f8b0:4001:c62::5f]:443: connect: network is unreachable" {"resource": {"service.instance.id": "feb467f0-ecc6-4a0c-b1e2-90c908131fdd", "service.name": "otelcol-google", "service.version": "v0.147.0"}, "grpc_log": true}
Isolando o erro real do registro:
transport: Error while dialing: dial tcp [2607:f8b0:4001:c62::5f]:443: connect: network is unreachable
Para contornar esse erro, mude para o exportador otlphttp (consulte o guia do usuário de métricas do OTLP para um exemplo) ou configure manualmente o balanceador pick_first no exportador otlp:
exporters:
otlp:
# ...
balancer_name: pick_first
# ...
Se o erro persistir após qualquer uma das soluções alternativas, é provável que essa mensagem seja um sintoma de problemas reais de conectividade de rede. Portanto, verifique se o coletor pode acessar a rede.