青蛙小白
博客 / 2023/06

OpenTelemetry Collector故障排除指南

2023/06/14 · — 字 · 阅读约 — 分钟 ·
#opentelemetry
目录

1. 可观测性

OpenTelemetry Collector提供了多种方法来评估其自身的健康状况以及如何排除故障。

1.1 日志

日志对于识别问题非常有帮助。始终从检查日志输出并查找潜在问题开始。日志的级别默认为INFO。

在配置中设置日志级别:

service:
  telemetry:
    logs:
      level: "debug"

1.2 Metrics

OTEL Collector的Prometheus指标在本地通过端口8888和路径/metrics公开。并可以通过配置文件中的service.telemetry.metrics.address进行配置。

service:
  telemetry:
    metrics:
      address: ":8888"

这里提供了一个适用于这些指标的Grafana Dashboard。

还要注意的是，可以配置Collector来获取自己的指标，并将其通过配置的管道发送出去。下面是一段配置示例:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'otelcol'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']
        metric_relabel_configs:
          - source_labels: [ __name__ ]
            regex: '.*grpc_io.*'
            action: drop
exporters:
  logging:
service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: []
      exporters: [logging]

1.3 zPages

zPages是OpenTelemetry Collector的一种扩展机制，用于提供实时的诊断和调试功能。它提供了一组基于Web的页面，可以通过HTTP端点进行访问，并显示有关Collector的运行时信息、配置、处理的数据和其他诊断信息。

所有核心的导出器（exporters）和接收器（receivers）都提供一些zPage服务支持。

zPages对于在进程中进行诊断非常有用，无需依赖任何后端来检查跟踪（traces）或指标（metrics）。

以下设置是必需的：

endpoint（默认值 localhost:55679）：指定提供zPages服务的HTTP端点。使用localhost:可以使其仅在本地可用，或使用":“使其在所有网络接口上可用。

可以启用zPages扩展，会在本地的端口55679上暴露zPages服务，并可通过/debug/tracez路径检查receivers和exporters的跟踪操作。zPages可能包含收集器未生成的错误日志。

在容器化环境中，可能希望将该端口暴露在公共接口上，而不仅仅是本地。可以通过扩展的配置部分进行配置。例如：

extensions:
  zpages:
    endpoint: 0.0.0.0:55679

暴露的zPages路由

OTEL Collector暴露了以下zPage路由：

  • ServiceZ: ServiceZ提供了Collector服务的概览，并可快速访问pipelinez、extensionz和featurez zPages。该页面还提供了构建和运行时信息。
    • 示例URL：http://localhost:55679/debug/servicez
  • PipelineZ: PipelineZ提供了有Collector中正在运行的管道的洞察信息。您可以找到有关每个管道的类型、数据是否被修改以及使用的Receivers、Processors和Exporters的信息。
    • 示例URL：http://localhost:55679/debug/pipelinez
  • ExtensionZ: ExtensionZ显示了在Collector中处于活动状态的扩展。
    • 示例URL：http://localhost:55679/debug/extensionz
  • FeatureZ：FeatureZ列出了可用的功能开关，以及它们的当前状态和描述。
    • 示例URL：http://localhost:55679/debug/featurez
  • TraceZ: TraceZ路由可用于按延迟桶对跨度进行检查和分类，例如(0us、10us、100us、1ms、10ms、100ms、1s、10s、1m]，它们还允许您快速检查错误样本。
    • 示例URL：http://localhost:55679/debug/tracez
  • RpcZ：RpcZ路由可用于帮助检查适当工具化的远程过程调用（RPC）的统计信息。例如，在使用gRPC时。
    • 示例URL：http://localhost:55679/debug/rpcz

1.4 Local exporters

可以配置本地Exporter来检查Collector处理的数据。

为了进行实时故障排除，请考虑使用日志导出器（logging exporter），它可以用于确认数据是否被Collector接收、处理和导出。

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

获取一个用于测试的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运行的情况下，将此负载发送给Collector。例如：

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

您应该从Collector看到类似以下的日志信息：

2020-11-11T04:12:33.089Z	INFO	loggingexporter/logging_exporter.go:296	TraceExporter	{"#spans": 1}

您还可以配置日志导出器的日志级别，以便打印整个负载：

exporters:
  logging:
    verbosity: detailed

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

2020-11-11T04:08:17.344Z	DEBUG	loggingexporter/logging_exporter.go:353	ResourceSpans #0
Resource labels:
     -> service.name: Str(api)
ScopeSpans #0
Span #0
    Trace ID       : 5982fe77008310cc80f1da5e10147519
    Parent ID      : 90394f6bcffb5d13
    ID             : 67fae42571535f60
    Name           : /m/n/2.6.1
    Kind           : SPAN_KIND_SERVER
    Start time     : 2018-01-24 08:16:15.726 +0000 UTC
    End time       : 2018-01-24 08:16:15.752 +0000 UTC
Attributes:
     -> data.http_response_code: Str(201)

1.5 健康检查

健康检查扩展（health_check extension）默认情况下在端口13133上对所有网络接口可用，可用于确保Collector正常运行。

extensions:
  health_check:
service:
  extensions: [health_check]

它返回类似以下的响应：

{
  "status": "Server available",
  "upSince": "2020-11-11T04:12:31.6847174Z",
  "uptime": "49.0132518s"
}

1.6 pprof

pprof扩展默认情况下在本地的端口1777上可用，允许您在Collector运行时对其进行性能分析。这是一个高级用例，在大多数情况下不需要使用。

2.常见问题

2.1 查看Collector的日志

要查看Collector的日志：

在Linux systemd系统上，可以使用journalctl命令找到日志：

journalctl | grep otelcol

要查找仅包含错误的日志：

journalctl | grep otelcol | grep Error

2.2 Collector退出/重启

Collector可能会退出/重启的原因包括：

  • 由于缺失或配置错误的memory_limiter处理器导致的内存压力。
  • 负载大小不正确。
  • 配置错误（例如，队列大小配置高于可用内存）。
  • 基础设施资源限制（例如Kubernetes）。

2.3 数据丢失

数据可能会因各种原因而丢失，但最常见的原因是：

  • Collector的大小设置不正确，导致无法处理和导出数据的速度跟不上接收数据的速度。
  • Exporter目标不可用或接受数据的速度过慢。
  • 为了减少数据丢失，强烈建议配置批处理处理器（batch processor）。此外，可能还需要在启用的exporter上配置排队重试选项。

2.4 接收数据无效

如果无法接收数据，则可能是因为以下原因之一：

  • 存在网络配置问题。
  • 接收器Reciever配置不正确。
  • 接收器在receivers部分中定义，但未在任何管道中启用。
  • 客户端配置不正确。
  • 请检查Collector的日志以及zpages，查找潜在问题。

2.5 处理数据无效

大多数处理问题是由于对处理器processor工作原理的误解或处理器的配置错误导致的。

误解的示例包括：

  • 属性处理器（attributes processors）仅适用于spans的“标签”（tags）。span名称由span处理器（span processor）处理。
  • 用于跟踪数据的处理器（除尾部采样外）逐个跨度（span）处理。

2.6 导出数据无效

如果无法导出到目标，则可能是因为以下原因之一：

  • 存在网络配置问题。
  • 导出器exporter配置不正确。
  • 目标不可用。
  • 请检查Collector的日志以及zpages，查找潜在问题。

一般情况下，导出数据无效是由于网络配置问题导致的。这可能是由于防火墙、DNS或代理问题引起的。请注意，Collector支持代理。

参考

TAGS # opentelemetry
评论