Questo documento descrive i passaggi per la risoluzione dei problemi e i problemi comuni relativi all'utilizzo di un agente di raccolta OpenTelemetry, come l'agente di raccolta OpenTelemetry integrato di Google, per inviare dati a Google Cloud Observability.
Risolvere i problemi relativi alla raccolta dei dati
Questa sezione descrive le strategie che puoi utilizzare per risolvere i problemi relativi alla raccolta dei dati.
Utilizzare l'esportatore debug
L'
debugesportatore
è il modo migliore per visualizzare i dati a livello di collettore OpenTelemetry. L'esportatore prende tutti i dati che riceve e li scrive in stdout in un formato leggibile. Questa opzione è più utile quando devi verificare che le trasformazioni nella pipeline producano il risultato previsto.
L'esportatore debug è incluso nel collettore OpenTelemetry integrato di Google. Puoi configurare l'esportatore debug con verbosity: detailed per visualizzare l'intero payload di telemetria.
exporters:
debug:
verbosity: detailed
Puoi includere l'esportatore nella pipeline:
service:
pipelines:
metrics:
receivers: [
# ...
]
processors: [
# ...
]
exporters: [
debug, # can be added alongside any other configured exporters
# ...
]
Testare online OpenTelemetry Transformation Language (OTTL) con OTTL Playground
Il OTTL Playground è uno strumento sviluppato dalla community che ti consente di sviluppare in modo interattivo una pipeline OpenTelemetry Transformation Language. Inizia fornendo OTLP JSON come input, scrivi la pipeline utilizzando la stessa configurazione che useresti per il collettore OpenTelemetry e ispeziona visivamente i risultati.
Il modo migliore per ottenere OTLP JSON da una pipeline è inserire un
file esportatore
nel punto precedente a quello in cui si troverebbe il processore di trasformazione. Inizia configurando un esportatore file:
exporters:
file:
path: example.json
Se avevi una pipeline come questa:
service:
pipelines:
metrics:
receivers: [hostmetrics]
processors: [
memorylimiter,
groupbyattrs,
transform, # where your OTTL pipeline will go
cumulativetodelta,
metricstarttime,
]
exporters: [
otlp,
]
Potresti modificare temporaneamente la pipeline per esportare i dati così come appariranno nel processore transform su cui stai lavorando.
service:
pipelines:
metrics:
receivers: [hostmetrics]
processors: [
memorylimiter,
groupbyattrs,
# transform,
# cumulativetodelta,
# metricstarttime,
]
exporters: [
# otlp,
file,
]
L'esportatore file scrive ogni payload che riceve in una riga del file.
Puoi utilizzare una singola riga di dati come input per OTTL Playground.
Problemi noti
Questa sezione descrive i problemi noti relativi all'agente di raccolta OpenTelemetry/agente di raccolta OpenTelemetry integrato di Google e come risolverli, se possibile.
Errori connect: network is unreachable eccessivi quando si utilizza l'esportatore otlp
NOTA: questo problema si applica solo all'esportatore otlp gRPC, non all'esportatore HTTP
equivalente denominato otlphttp.
NOTA: finora questo problema è stato osservato direttamente solo negli ambienti Compute Engine, ma a causa della natura del problema non possiamo confermare che sia effettivamente limitato a Compute Engine.
A partire dalla versione 0.147.0 dell'agente di raccolta OpenTelemetry integrato di Google e dalla versione 0.145.0 dell'agente di raccolta OpenTelemetry upstream, l'esportatore otlpinizierà a utilizzare per impostazione predefinita la strategia di bilanciamento del carico lato client round_robin, mentre in precedenza era pick_first. Quando l'esportatore utilizzava in precedenza la strategia pick_first, aveva anche un fallback IPV4 perfettamente funzionante in uno scenario in cui IPV6 non funzionava. La strategia round_robin non ha questa proprietà e tenterà ripetutamente di inviare a tutti gli indirizzi che risolve all'avvio dell'esportatore, anche quando non funzionano.
Di conseguenza, se utilizzi l'esportatore otlp per inviare dati all'API Telemetry, potresti visualizzare messaggi di errore come questo:
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}
Isolamento dell'errore effettivo del log:
transport: Error while dialing: dial tcp [2607:f8b0:4001:c62::5f]:443: connect: network is unreachable
Per risolvere questo errore, puoi passare all'esportatore otlphttp
(per un esempio, consulta la nostra guida per l'utente delle metriche OTLP) oppure puoi configurare manualmente il bilanciatore pick_first sull'esportatore otlp:
exporters:
otlp:
# ...
balancer_name: pick_first
# ...
Se l'errore persiste dopo una delle due soluzioni alternative, è probabile che questo messaggio di errore sia un sintomo di problemi di connettività di rete effettivi, quindi dovrai assicurarti che l'agente di raccolta possa effettivamente raggiungere la rete.