Questo documento descrive i passaggi per la risoluzione dei problemi e i problemi comuni relativi all'utilizzo di un OpenTelemetry Collector, ad esempio Google-Built OpenTelemetry Collector, 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'esportatore
debug
è il modo migliore per visualizzare i dati a livello di OpenTelemetry Collector. L'esportatore
prende 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 in Google-Built OpenTelemetry Collector. 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 OpenTelemetry Transformation Language (OTTL) online con OTTL Playground
OTTL Playground è uno strumento sviluppato dalla community che ti consente di sviluppare in modo interattivo una pipeline del linguaggio di trasformazione OpenTelemetry. Inizia fornendo OTLP JSON come input, scrivi la pipeline utilizzando la stessa configurazione che useresti per OpenTelemetry Collector e ispeziona visivamente i risultati.
Il modo migliore per ottenere OTLP JSON da una pipeline è inserire un
esportatore file
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 scriverà ogni payload ricevuto 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 a OpenTelemetry Collector/Google-Built OpenTelemetry Collector e come risolverli, ove possibile.
Eccessivi errori connect: network is unreachable durante l'utilizzo dello strumento di esportazione otlp
NOTA: questo problema riguarda solo l'esportatore gRPC otlp, non l'esportatore HTTP
equivalente chiamato otlphttp.
NOTA: finora questo problema è stato osservato direttamente solo negli ambienti Compute Engine, ma a causa della sua natura non possiamo confermare che sia effettivamente limitato a Compute Engine.
A partire dalla versione 0.147.0 di Google-Built OpenTelemetry Collector e dalla versione 0.145.0 di OpenTelemetry Collector upstream, l'esportatore otlp inizierà 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, disponeva anche di un fallback IPv4
completamente 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 (consulta la nostra guida per l'utente delle metriche OTLP per un esempio) oppure puoi configurare manualmente il bilanciatore pick_first nell'esportatore otlp:
exporters:
otlp:
# ...
balancer_name: pick_first
# ...
Se l'errore persiste dopo una delle soluzioni alternative, è probabile che questo messaggio di errore sia un sintomo di problemi effettivi di connettività di rete, quindi dovrai assicurarti che il tuo agente di raccolta possa effettivamente raggiungere la rete.