本文档介绍了使用 OpenTelemetry 收集器（例如 Google 构建的 OpenTelemetry 收集器）将数据发送到 Google Cloud Observability 时的问题排查步骤和常见问题。
排查数据收集问题
本部分介绍了可用于排查数据收集问题的策略。
使用 debug 导出器
debug 导出器是在 OpenTelemetry 收集器级别查看数据的最佳方式。导出器会接收任何数据，并以直观易懂的格式将其写入标准输出。当您需要验证流水线中的任何转换是否产生了预期结果时，此功能最为有用。
debug 导出器包含在 Google 构建的 OpenTelemetry 收集器中。您可以使用 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 收集器相同的配置编写流水线，最后直观地检查结果。
从流水线获取 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 收集器/Google 构建的 OpenTelemetry 收集器的已知问题，以及在可能的情况下如何解决这些问题。
使用 otlp 导出器时出现过多的 connect: network is unreachable 错误
注意：此问题仅适用于 gRPC otlp 指标导出器，而不适用于名为 otlphttp 的 HTTP 等效指标导出器。
注意：到目前为止，我们仅在 Compute Engine 环境中直接观察到此问题，但由于此问题的性质，我们无法确认它是否确实仅限于 Compute Engine。
从 Google 构建的 OpenTelemetry 收集器版本 0.147.0 和上游 OpenTelemetry 收集器版本 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
# ...
如果采用任一解决方法后错误仍然存在，则此错误消息很可能是实际网络连接问题的症状，因此您需要确保收集器确实可以访问网络。