故障排查

Collector 故障排查建议

在本页中，你可以了解如何对 OpenTelemetry Collector 的健康状况和性能进行故障排查。

故障排查工具

Collector 在调试问题方面提供了多种指标、日志和扩展功能。

内部遥测数据

你可以配置并使用 Collector 的内部遥测数据，以监控其性能。

本地导出器

针对某些类型的问题，例如配置验证和网络调试，你可以将少量测试数据发送到配置为输出到本地日志的 Collector。通过使用一个本地导出器，你可以检查 Collector 正在处理的数据。

对于实时故障排查，可以考虑使用 debug 导出器，它可确认 Collector 是否正在接收、处理并导出数据。例如：

receivers:
  zipkin:
exporters:
  debug:
service:
  pipelines:
    traces:
      receivers: [zipkin]
      processors: []
      exporters: [debug]

开始测试时，生成一个 Zipkin 负载。例如，你可以创建一个名为 trace.json 的文件，内容如下：

[
  {
    "traceId": "5982fe77008310cc80f1da5e10147519",
    "parentId": "90394f6bcffb5d13",
    "id": "67fae42571535f60",
    "kind": "SERVER",
    "name": "/m/n/2.6.1",
    "timestamp": 1516781775726000,
    "duration": 26000,
    "localEndpoint": {
      "serviceName": "api"
    },
    "remoteEndpoint": {
      "serviceName": "apip"
    },
    "tags": {
      "data.http_response_code": "201"
    }
  }
]

Collector 运行后，向其发送该负载：

curl -X POST localhost:9411/api/v2/spans -H'Content-Type: application/json' -d @trace.json

你应当会看到类似如下的日志条目：

2023-09-07T09:57:43.468-0700    info    TracesExporter  {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}

你也可以配置 debug 导出器，使其打印完整负载内容：

exporters:
  debug:
    verbosity: detailed

如果使用修改后的配置重新运行上述测试，日志输出如下：

2023-09-07T09:57:12.820-0700    info    TracesExporter  {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
2023-09-07T09:57:12.821-0700    info    ResourceSpans #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.4.0
Resource attributes:
     -> service.name: Str(telemetrygen)
ScopeSpans #0
ScopeSpans SchemaURL:
InstrumentationScope telemetrygen
Span #0
    Trace ID       : 0c636f29e29816ea76e6a5b8cd6601cf
    Parent ID      : 1a08eba9395c5243
    ID             : 10cebe4b63d47cae
    Name           : okey-dokey
    Kind           : Internal
    Start time     : 2023-09-07 16:57:12.045933 +0000 UTC
    End time       : 2023-09-07 16:57:12.046058 +0000 UTC
    Status code    : Unset
    Status message :
Attributes:
     -> span.kind: Str(server)
     -> net.peer.ip: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen)

检查 Collector 组件

使用以下子命令列出 Collector 分发包中可用的组件及其稳定性等级。请注意，输出格式可能随版本变化：

otelcol components

示例输出：

buildinfo:
  command: otelcol
  description: OpenTelemetry Collector
  version: 0.96.0
receivers:
  - name: opencensus
    stability:
      logs: Undefined
      metrics: Beta
      traces: Beta
  - name: prometheus
    stability:
      logs: Undefined
      metrics: Beta
      traces: Undefined
  - name: zipkin
    stability:
      logs: Undefined
      metrics: Undefined
      traces: Beta
  - name: otlp
    stability:
      logs: Beta
      metrics: Stable
      traces: Stable
processors:
  - name: resource
    stability:
      logs: Beta
      metrics: Beta
      traces: Beta
  - name: span
    stability:
      logs: Undefined
      metrics: Undefined
      traces: Alpha
  - name: probabilistic_sampler
    stability:
      logs: Alpha
      metrics: Undefined
      traces: Beta
exporters:
  - name: otlp
    stability:
      logs: Beta
      metrics: Stable
      traces: Stable
  - name: otlphttp
    stability:
      logs: Beta
      metrics: Stable
      traces: Stable
  - name: debug
    stability:
      logs: Development
      metrics: Development
      traces: Development
  - name: prometheus
    stability:
      logs: Undefined
      metrics: Beta
      traces: Undefined
connectors:
  - name: forward
    stability:
      logs-to-logs: Beta
      logs-to-metrics: Undefined
      logs-to-traces: Undefined
      metrics-to-logs: Undefined
      metrics-to-metrics: Beta
      traces-to-traces: Beta
extensions:
  - name: zpages
    stability:
      extension: Beta
  - name: health_check
    stability:
      extension: Beta
  - name: pprof
    stability:
      extension: Beta

扩展

以下是可用于 Collector 调试的扩展列表。

性能分析器 (pprof)

pprof 扩展默认在本地端口 1777 提供服务，可在 Collector 运行时对其进行性能分析。这是一种高级使用场景，通常情况下无需使用。

zPages

zPages 扩展默认在本地端口 55679 提供服务，可用于查看 Collector 接收器和导出器的实时数据。

其中，/debug/tracez 上的 TraceZ 页面对调试链路操作很有帮助，例如：

延迟问题。找出应用中耗时的部分。
死锁与探针问题。识别未正常结束的正在运行的 Span。
错误。判断发生了哪些类型的错误以及错误发生的位置。

请注意，zpages 中可能包含 Collector 本身未输出的错误日志。

在容器化环境中，建议将此端口暴露至公有接口而非仅本地可用。可通过 extensions 配置段设置 endpoint：

extensions:
  zpages:
    endpoint: 0.0.0.0:55679

复杂管道的调试清单

当遥测数据通过多个 Collector 和网络流动时，定位问题可能会比较困难。每次数据在 Collector 或其他组件之间传递时，都应验证以下内容：

Collector 日志中是否有错误信息？
遥测数据是如何进入该组件的？
此组件是否修改了遥测数据（如采样、脱敏）？
此组件如何导出遥测数据？
遥测数据使用的是什么格式？
下游组件的配置如何？
是否存在网络策略阻止数据进出？

常见的 Collector 问题

本节介绍如何解决常见的 Collector 问题。

Collector 出现数据问题

Collector 及其组件可能会出现数据问题。

Collector 丢失数据

Collector 可能因以下常见原因丢失数据：

Collector 配置不当，处理和导出数据的速度低于接收速度。
导出目标不可用或接收速度太慢。

为缓解丢失情况，请配置 batch 处理器。另外，还可能需要在启用的导出器上配置排队重试选项。

Collector 收不到数据

Collector 收不到数据的原因可能包括：

网络配置问题。
接收器配置不正确。
客户端配置错误。
接收器在 receivers 段中定义但未在任何 pipelines 中启用。

检查 Collector 的日志以及 zPages 以排查问题。

Collector 未处理数据

大多数处理问题源于对处理器工作方式的误解或处理器配置错误。例如：

属性处理器仅作用于 Span 上的标签，Span 名称需由 Span 处理器处理。
除尾部采样外的链路数据处理器仅作用于单个 Span。

Collector 未导出数据

Collector 未导出数据的原因可能包括：

网络配置问题。
导出器配置错误。
目标端不可用。

检查 Collector 的日志以及 zPages 以排查问题。

导出数据失败通常是由于网络配置问题，例如防火墙、DNS 或代理问题。注意 Collector 支持代理。

Collector 出现控制问题

Collector 可能会遇到启动失败、异常退出或重启的问题。

Collector 退出或重启

Collector 可能因以下原因退出或重启：

缺少或错误配置的 memory_limiter 处理器导致内存压力。
负载下资源配置不当。
错误的配置，例如队列大小超过可用内存。
基础设施资源限制，如 Kubernetes。

Collector 在 Windows Docker 容器中启动失败

在 v0.90.1 及更早版本中，Collector 在 Windows Docker 容器中启动可能失败，并出现错误信息： The service process could not connect to the service controller。此时，需设置 NO_WINDOWS_SERVICE=1 环境变量，使 Collector 以交互式终端方式启动，而非尝试作为 Windows 服务运行。

Collector 出现配置问题

Collector 可能因配置问题导致异常。

空映射问题

在解析多个配置文件时，较早配置中的值会被较晚配置中的值覆盖，即便后者为 null。你可以通过以下方式修复：

使用 {} 表示空映射，例如使用 processors: {} 而非 processors:。
省略空配置段，例如不写 processors:。

更多信息请参见 confmap 故障排查。

Feedback

Was this page helpful?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

Last modified August 12, 2025: [zh] Add collector/troubleshooting.md (#7479) (ed30778f)