Este documento descreve etapas de solução de problemas e problemas comuns ao usar um OpenTelemetry Collector, como o OpenTelemetry Collector criado pelo Google, para enviar dados ao Google Cloud Observability.
Resolver problemas de coleta de dados
Esta seção descreve estratégias que podem ser usadas para resolver problemas de coleta de dados.
Usar o exportador debug
O
debug exportador
é a melhor maneira de visualizar 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. É possível configurar o exportador debug com verbosity: detailed para conferir todo o payload de telemetria.
exporters:
debug:
verbosity: detailed
Você pode 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 é uma ferramenta desenvolvida pela comunidade que permite desenvolver interativamente um pipeline de linguagem de transformação do OpenTelemetry. Comece fornecendo JSON OTLP como entrada, escreva o pipeline usando a mesma configuração do OpenTelemetry Collector e inspecione os resultados visualmente.
A melhor maneira de receber JSON OTLP de um pipeline é colocar um
file exportador
no local antes do processador de transformação. 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,
]
É possível modificar temporariamente o pipeline para exportar os dados como eles serão exibidos 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.
É possível usar uma única linha de dados como entrada para o OTTL Playground.
Problemas conhecidos
Esta seção descreve problemas conhecidos com o OpenTelemetry Collector/OpenTelemetry Collector criado pelo Google e como contorná-los, quando possível.
Erros connect: network is unreachable excessivos ao usar o exportador otlp
OBSERVAÇÃO: esse problema se aplica apenas ao exportador otlp do gRPC, 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 do problema, não podemos confirmar que ele está realmente 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 começará a usar por padrão a estratégia de balanceamento de carga do lado do cliente
round_robin, em que anteriormente era pick_first. Quando o exportador usava a estratégia pick_first, ele também tinha um fallback 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 tentará enviar repetidamente para todos os endereços que resolve no horário de início do exportador, mesmo quando eles não funcionam.
Como resultado, se você estiver usando o exportador otlp para enviar dados à API Telemetry, poderá receber 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, você pode mudar para o exportador otlphttp
(consulte nosso guia do usuário de métricas OTLP para conferir um
exemplo) ou configurar 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 de erro seja um sintoma de problemas reais de conectividade de rede. Portanto, é necessário garantir que o coletor possa acessar a rede.