OpenTelemetry Collector 故障排查-未完纪

故障排查

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 接收器和导出器的实时数据。

TraceZ 页面位于 /debug/tracez，有助于调试追踪操作，例如：

延迟问题：找出应用中较慢的部分。
死锁和插桩问题：识别正在运行却迟迟不结束的 span。
错误：确定发生了什么类型的错误，以及错误出现在哪里。

注意，zpages 可能包含 Collector 自身没有输出的错误日志。

在容器环境中，可能希望把端口暴露在公共接口，而不只是本地接口。endpoint 可以通过 extensions 配置节设置：

extensions:
  zpages:
    endpoint: 0.0.0.0:55679

复杂管线调试清单

遥测经过多个 Collector 和网络时，问题可能很难定位。对于管线中经过 Collector 或其他组件的每一“跳”，都应核实以下问题：

Collector 日志中是否有错误信息？
遥测是如何摄取到这个组件中的？
这个组件如何修改遥测，例如采样或脱敏？
遥测如何从这个组件导出？
遥测采用什么格式？
下一跳如何配置？
是否存在阻止数据流入或流出的网络策略？

Kubernetes 环境中的故障排查

在 Kubernetes 上运行 OpenTelemetry Collector 时，可使用临时调试容器排查 Collector 相关问题。

Collector 常见问题

本节介绍常见 Collector 问题的处理方法。

Collector 遇到数据问题

Collector 及其组件可能遇到数据问题。

Collector 丢弃数据

Collector 可能因多种原因丢弃数据，最常见的情况是：

Collector 的资源规模配置不当，处理和导出速度跟不上数据接收速度。
导出器目标不可用，或者接收数据过慢。

为减少丢弃，请在启用的导出器上配置队列重试选项，尤其是发送队列批处理设置。

Collector 未接收数据

Collector 可能因以下原因收不到数据：

网络配置问题。
接收器配置错误。
客户端配置错误。
接收器在 receivers 节中定义，却没有在任何 pipelines 中启用。

检查 Collector 的日志和 zPages，寻找可能的问题。

Collector 未处理数据

多数处理问题来自对处理器机制的误解或处理器配置错误。例如：

attributes 处理器只处理 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 服务运行。