OpenTelemetry Collector故障排除指南

1. 可观测性

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

1.1 日志

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

在配置中设置日志级别:

1service:
2  telemetry:
3    logs:
4      level: "debug"

1.2 Metrics

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

1service:
2  telemetry:
3    metrics:
4      address: ":8888"

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

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

 1receivers:
 2  prometheus:
 3    config:
 4      scrape_configs:
 5      - job_name: 'otelcol'
 6        scrape_interval: 10s
 7        static_configs:
 8        - targets: ['0.0.0.0:8888']
 9        metric_relabel_configs:
10          - source_labels: [ __name__ ]
11            regex: '.*grpc_io.*'
12            action: drop
13exporters:
14  logging:
15service:
16  pipelines:
17    metrics:
18      receivers: [prometheus]
19      processors: []
20      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可能包含收集器未生成的错误日志。

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

1extensions:
2  zpages:
3    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接收、处理和导出。

 1receivers:
 2  zipkin:
 3exporters:
 4  logging:
 5service:
 6  pipelines:
 7    traces:
 8      receivers: [zipkin]
 9      processors: []
10      exporters: [logging]

获取一个用于测试的Zipkin负载。例如，创建一个名为trace.json的文件，其中包含以下内容：

 1[
 2  {
 3    "traceId": "5982fe77008310cc80f1da5e10147519",
 4    "parentId": "90394f6bcffb5d13",
 5    "id": "67fae42571535f60",
 6    "kind": "SERVER",
 7    "name": "/m/n/2.6.1",
 8    "timestamp": 1516781775726000,
 9    "duration": 26000,
10    "localEndpoint": {
11      "serviceName": "api"
12    },
13    "remoteEndpoint": {
14      "serviceName": "apip"
15    },
16    "tags": {
17      "data.http_response_code": "201"
18    }
19  }
20]

在Collector运行的情况下，将此负载发送给Collector。例如：

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

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

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

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

1exporters:
2  logging:
3    verbosity: detailed

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

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

1.5 健康检查

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

1extensions:
2  health_check:
3service:
4  extensions: [health_check]

它返回类似以下的响应：

1{
2  "status": "Server available",
3  "upSince": "2020-11-11T04:12:31.6847174Z",
4  "uptime": "49.0132518s"
5}

1.6 pprof

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

2.常见问题

2.1 查看Collector的日志

要查看Collector的日志：

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

1journalctl | grep otelcol

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

1journalctl | 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支持代理。

参考

https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/troubleshooting.md

文章目录