本文說明使用 OpenTelemetry Collector (例如 Google 建構的 OpenTelemetry Collector) 將資料傳送至 Google Cloud Observability 時，常見的問題和疑難排解步驟。
排解資料收集問題
本節說明可用於排解資料收集問題的策略。
使用 debug 匯出工具
使用 debug 匯出工具，是在 OpenTelemetry Collector 層級查看資料的最佳方式。匯出工具會接收任何資料，並以人類可讀的格式將資料寫入標準輸出。如需驗證管道中的任何轉換作業是否產生預期結果，這項功能就非常實用。
debug 匯出工具已納入 Google 建構的 OpenTelemetry Collector。您可以透過 verbosity: detailed 設定 debug 匯出工具，查看完整的遙測酬載。
exporters:
debug:
verbosity: detailed
您可以在管道中加入匯出工具：
service:
pipelines:
metrics:
receivers: [
# ...
]
processors: [
# ...
]
exporters: [
debug, # can be added alongside any other configured exporters
# ...
]
使用 OTTL Playground 線上測試 OpenTelemetry 轉換語言 (OTTL)
OTTL Playground 是社群開發的工具，可讓您以互動方式開發 OpenTelemetry Transformation Language 管道。首先，請提供 OTLP JSON 做為輸入內容，然後使用與 OpenTelemetry Collector 相同的設定編寫管道，並以視覺化方式檢查結果。
如要從管道取得 OTLP JSON，最好的方法是在轉換處理器之前的位置放置 file 匯出工具。首先，請設定 file 匯出工具：
exporters:
file:
path: example.json
假設您有類似下方的管道：
service:
pipelines:
metrics:
receivers: [hostmetrics]
processors: [
memorylimiter,
groupbyattrs,
transform, # where your OTTL pipeline will go
cumulativetodelta,
metricstarttime,
]
exporters: [
otlp,
]
您可以暫時修改管道，匯出資料，瞭解資料進入您使用的 transform 處理器時的樣貌。
service:
pipelines:
metrics:
receivers: [hostmetrics]
processors: [
memorylimiter,
groupbyattrs,
# transform,
# cumulativetodelta,
# metricstarttime,
]
exporters: [
# otlp,
file,
]
file 匯出工具會將收到的每個酬載寫入檔案中的一行。您可以將單行資料做為 OTTL Playground 的輸入內容。
已知問題
本節說明 OpenTelemetry Collector/Google 建構的 OpenTelemetry Collector 的已知問題，以及盡可能解決問題的方法。
使用 otlp 匯出工具時發生過多 connect: network is unreachable 錯誤
注意：這個問題只會影響 gRPC otlp 匯出工具，不會影響名為 otlphttp 的 HTTP 對等匯出工具。
注意：目前我們只在 Compute Engine 環境中直接觀察到這個問題，但由於問題的性質，我們無法確認問題是否僅限於 Compute Engine。
從 Google 建構的 OpenTelemetry Collector 0.147.0 版和上游 OpenTelemetry Collector 0.145.0 版開始，otlp 匯出器預設會採用用戶端負載平衡策略 round_robin，先前則是 pick_first。如果出口商先前使用 pick_first 策略，在 IPv6 無法運作的情況下，出口商也能完全正常地使用 IPv4 備援。round_robin 策略沒有這項屬性，即使地址無法運作，也會在匯出工具啟動時解析所有地址，並重複嘗試傳送。
因此，如果您使用 otlp 匯出工具將資料傳送至 Telemetry API，可能會看到類似以下的錯誤訊息：
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}
找出記錄中的實際錯誤：
transport: Error while dialing: dial tcp [2607:f8b0:4001:c62::5f]:443: connect: network is unreachable
如要解決這項錯誤，您可以切換至 otlphttp 匯出工具 (請參閱 OTLP 指標使用者指南中的範例)，或在 otlp 匯出工具上，手動設定 pick_first 平衡器：
exporters:
otlp:
# ...
balancer_name: pick_first
# ...
如果採取任一解決方法後仍發生錯誤，則可能是網路連線問題導致錯誤訊息出現，因此請務必確認收集器確實可以連上網路。