对红帽构建的 OpenTelemetry 进行故障排除

Red Hat build of OpenTelemetry 3.8

诊断并解决 Collector 和检测问题

Red Hat OpenShift Documentation Team

摘要

本文档为 OpenTelemetry Collector 和工具提供了故障排除过程。了解如何使用 must-gather 来收集诊断数据、配置和检索 Collector 日志、公开和监控内部指标以进行数据处理、使用 debug 导出器并排除网络问题。包括诊断检测注入问题、验证 pod 注解、检查 init-containers、检查 Operator 日志以及解决遥测数据生成问题的流程。

第 1 章故障排除
复制链接

OpenTelemetry Collector 提供了多种方法来测量其健康状况，并调查数据监控问题。

在提交问题单时，向红帽提供包含有关集群的诊断信息会很有帮助。您可以使用 oc adm must-gather 工具来收集各种类型的资源的诊断数据，如 OpenTelemetryCollector、Instrumentation 以及创建的资源，如 Deployment、Pod 或 ConfigMap。oc adm must-gather 工具会创建一个收集此数据的新 pod。

流程

从您要保存收集的数据的目录中，运行 oc adm must-gather 命令来收集数据：

oc adm must-gather --image=ghcr.io/open-telemetry/opentelemetry-operator/must-gather -- \
/usr/bin/must-gather --operator-namespace <operator_namespace>

$ oc adm must-gather --image=ghcr.io/open-telemetry/opentelemetry-operator/must-gather -- \
/usr/bin/must-gather --operator-namespace <operator_namespace>

Copy to Clipboard

Toggle word wrap

1: 安装 Operator 的默认命名空间是 openshift-opentelemetry-operator。

验证

1.2. 获取 OpenTelemetry Collector 日志
复制链接

您可以按照如下所示，获取 OpenTelemetry Collector 的日志。

流程

在 OpenTelemetryCollector 自定义资源(CR) 中设置相关的日志级别：
```
  config:
    service:
      telemetry:
        logs:
          level: debug 
```
```
  config:
    service:
      telemetry:
        logs:
          level: debug 
```
1
Copy to Clipboard Toggle word wrap
1
收集器的日志级别。支持的值包括 info、warn、error 或 debug。默认为 info。
使用 oc logs 命令或 Web 控制台来检索日志。

1.3. 公开指标
复制链接

OpenTelemetry Collector 会公开有关它已处理的数据卷的指标。

otelcol_receiver_accepted_spans: 成功推送到管道中的 span 数量。
otelcol_receiver_refused_spans: 无法推送到管道中的 span 数量。
otelcol_exporter_sent_spans: 成功发送到目的地的 span 数量。
otelcol_exporter_enqueue_failed_spans: 无法添加到发送队列的 span 数量。
otelcol_receiver_accepted_logs: 成功推送到管道的日志数量。
otelcol_receiver_refused_logs: 无法推送到管道的日志数量。
otelcol_exporter_sent_logs: 成功发送到目的地的日志数量。
otelcol_exporter_enqueue_failed_logs: 无法添加到发送队列中的日志数量。
otelcol_receiver_accepted_metrics: 成功推送到管道的指标数量。
otelcol_receiver_refused_metrics: 无法推送到管道的指标数量。
otelcol_exporter_sent_metrics: 成功发送到目的地的指标数量。
otelcol_exporter_enqueue_failed_metrics: 无法添加到发送队列中的指标数量。

您可以使用这些指标来排除 Collector 的问题。例如，如果 otelcol_receiver_refused_spans 指标具有较高值，这表示 Collector 无法处理传入的 span。

Operator 会创建一个 <cr_name>-collector-monitoring 遥测服务，可用于提取指标端点。

流程

通过在 OpenTelemetryCollector 自定义资源（CR）中添加以下行来启用 telemetry 服务：

# ...
  config:
    service:
      telemetry:
        metrics:
          readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888 
# ...

# ...
  config:
    service:
      telemetry:
        metrics:
          readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888


# ...

Copy to Clipboard

Toggle word wrap

1: 公开内部收集器指标的端口。默认值为 :8888。

运行以下命令来检索指标，该命令使用端口转发 Collector pod：
```
oc port-forward <collector_pod>
```
```
$ oc port-forward <collector_pod>
```
Copy to Clipboard Toggle word wrap
在 OpenTelemetryCollector CR 中，将 enableMetrics 字段设置为 true 以提取内部指标：
```
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
spec:
# ...
  mode: deployment
  observability:
    metrics:
      enableMetrics: true
# ...
```
```
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
spec:
# ...
  mode: deployment
  observability:
    metrics:
      enableMetrics: true
# ...
```
Copy to Clipboard Toggle word wrap
根据 OpenTelemetry Collector 的部署模式，使用 PodMonitor 或 ServiceMonitor 提取内部指标。
注意
另外，如果您没有将 enableMetrics 字段设置为 true，您可以访问 http://localhost:8888/metrics 的指标端点。
可选：如果 web 控制台中启用了 User Workload Monitoring 功能，进入 web 控制台中的 Observe → Dashboards，然后从下拉列表中选择 OpenTelemetry Collector 仪表板。有关用户工作负载监控功能的更多信息，请参阅监控中的"为用户定义的项目启用监控"。
提示
您可以过滤由 Collector 实例、命名空间或 OpenTelemetry 组件（如处理器、接收器或导出器）的 span 或 metrics 等视觉化数据。

1.4. Debug Exporter
复制链接

您可以配置 Debug Exporter，将收集的数据导出到标准输出。

流程

配置 OpenTelemetryCollector 自定义资源，如下所示：

  config:
    exporters:
      debug:
        verbosity: detailed
    service:
      pipelines:
        traces:
          exporters: [debug]
        metrics:
          exporters: [debug]
        logs:
          exporters: [debug]

  config:
    exporters:
      debug:
        verbosity: detailed
    service:
      pipelines:
        traces:
          exporters: [debug]
        metrics:
          exporters: [debug]
        logs:
          exporters: [debug]

Copy to Clipboard

Toggle word wrap

使用 oc logs 命令或 Web 控制台将日志导出到标准输出。

1.5. 禁用网络策略
复制链接

红帽构建的 OpenTelemetry Operator 会创建网络策略来控制 Operator 和操作对象的流量以提高安全性。默认情况下，网络策略会被启用并配置为允许到所有所需组件的流量。不需要额外的配置。

如果您遇到 OpenTelemetry Collector 或其 Target Allocator 组件的流量问题，则问题可能是默认的网络策略配置。您可以为 OpenTelemetry Collector 禁用网络策略来排除这个问题。

先决条件

您可以使用具有 cluster-admin 角色的集群管理员访问集群。

流程

通过配置 OpenTelemetryCollector 自定义资源(CR)来禁用 OpenTelemetry Collector 的网络策略：

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel
  namespace: observability
spec:
  networkPolicy:
    enabled: false 
  # ...

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: otel
  namespace: observability
spec:
  networkPolicy:
    enabled: false


  # ...

Copy to Clipboard

Toggle word wrap

1: 通过将 networkPolicy.enabled 设置为 true （默认）或 false 来指定是否启用网络策略。将它设置为 false 可禁用网络策略的创建。

1.6. 使用 Network Observability Operator 进行故障排除
复制链接

您可以使用 Network Observability Operator 来调试可观察性组件之间的流量。

先决条件

您已安装了 Network Observability Operator，如"安装 Network Observability Operator"中所述。

流程

在 OpenShift Container Platform web 控制台中进入 Observe → Network Traffic → Topology。
选择 Namespace 根据部署 OpenTelemetry Collector 的命名空间过滤工作负载。
使用流量可视化来排查可能的问题。如需了解更多详细信息，请参阅"从 Topology 视图保留网络流量"。

1.7. 对工具进行故障排除
复制链接

要对工具进行故障排除，请查找以下问题：

在工作负载中检测注入的问题
检测库生成数据的问题

1.7.1. 对工作负载注入的故障排除
复制链接

要排除检测注入的问题，您可以执行以下操作：

检查是否创建了 Instrumentation 对象
检查 init-container 是否已启动
检查资源是否以正确顺序部署
搜索 Operator 日志中的错误
仔细检查 pod 注解

流程

运行以下命令验证 Instrumentation 对象是否已成功创建：
```
oc get instrumentation -n <workload_project>
```
```
$ oc get instrumentation -n <workload_project> 
```
1
Copy to Clipboard Toggle word wrap
1
创建检测的命名空间。
运行以下命令，以验证 opentelemetry-auto-instrumentation init-container 是否已成功启动，这是检测注入工作负载的先决条件：
```
oc get events -n <workload_project>
```
```
$ oc get events -n <workload_project> 
```
1
Copy to Clipboard Toggle word wrap
1
为工作负载注入检测的命名空间。
输出示例
```
... Created container opentelemetry-auto-instrumentation
... Started container opentelemetry-auto-instrumentation
```
```
... Created container opentelemetry-auto-instrumentation
... Started container opentelemetry-auto-instrumentation
```
Copy to Clipboard Toggle word wrap
验证资源是否已正确部署，以便自动检测正常工作。正确的顺序是在部署应用程序前部署 Instrumentation 自定义资源(CR)。有关 Instrumentation CR 的详情，请参考"配置工具"部分。
注意
当 pod 启动时，Red Hat build of OpenTelemetry Operator 会检查 Instrumentation CR 中的注解，其中包含注入自动检测的说明。通常，Operator 会将 init-container 添加到应用程序的 pod 中，该 pod 会将自动检测和环境变量注入应用程序的容器中。如果在部署应用程序时 Operator 无法使用 Instrumentation CR，Operator 无法注入自动检测。
修复部署顺序需要以下步骤：
1. 更新检测设置。
2. 删除检测对象。
3. 重新部署应用。

运行以下命令检查 Operator 日志中的检测错误：

oc logs -l app.kubernetes.io/name=opentelemetry-operator --container manager -n openshift-opentelemetry-operator --follow

$ oc logs -l app.kubernetes.io/name=opentelemetry-operator --container manager -n openshift-opentelemetry-operator --follow

Copy to Clipboard

Toggle word wrap

对特定编程语言的检测的 pod 注解进行故障排除。请参阅"配置检测"中的所需的注解字段和值。
1. 验证您要检测的应用程序 pod 是否使用正确的注解标记，并且应用了适当的自动检测设置。
  Example
  instrumentation.opentelemetry.io/inject-python="true"
  
  Copy to Clipboard Toggle word wrap
  获取检测 Python 应用程序的 pod 注解的命令示例
  $ oc get pods -n <workload_project> -o jsonpath='{range .items[?(@.metadata.annotations["instrumentation.opentelemetry.io/inject-python"]=="true")]}{.metadata.name}{"\n"}{end}'
  
  Copy to Clipboard Toggle word wrap
2. 验证应用于检测对象的注解是否正确，适用于您检测的编程语言。
3. 如果同一命名空间中有多个检测，请在注解中指定 Instrumentation 对象的名称。
  Example
  instrumentation.opentelemetry.io/inject-nodejs: "<instrumentation_object>"
  
  Copy to Clipboard Toggle word wrap
4. 如果 Instrumentation 对象位于不同的命名空间中，请在注解中指定命名空间。
  Example
  instrumentation.opentelemetry.io/inject-nodejs: "<other_namespace>/<instrumentation_object>"
  
  Copy to Clipboard Toggle word wrap
5. 验证 OpenTelemetryCollector 自定义资源是否在 spec.template.metadata.annotations 下指定 auto-instrumentation 注解。如果 auto-instrumentation 注解位于 spec.metadata.annotations 中，请将其移到 spec.template.metadata.annotations 中。

1.7.2. 通过检测库生成遥测数据故障排除
复制链接

您可以通过检查端点、在应用程序日志中查找错误，并验证 Collector 收到遥测数据，从而通过检测库对遥测数据进行故障排除。

流程

验证检测是否将数据传送到正确的端点：
```
oc get instrumentation <instrumentation_name> -n <workload_project> -o jsonpath='{.spec.endpoint}'
```
```
$ oc get instrumentation <instrumentation_name> -n <workload_project> -o jsonpath='{.spec.endpoint}'
```
Copy to Clipboard Toggle word wrap
Instrumentation 对象的默认端点 http://localhost:4317 仅适用于部署为应用程序 pod 中的 sidecar 的 Collector 实例。如果您使用不正确的端点，请通过编辑 Instrumentation 对象并重新部署应用程序来纠正该端点。
检查应用程序日志中可能表明检测已出现故障的错误消息：
```
oc logs <application_pod> -n <workload_project>
```
```
$ oc logs <application_pod> -n <workload_project>
```
Copy to Clipboard Toggle word wrap
如果应用程序日志包含表明检测可能会出现故障的错误消息，请在本地安装 OpenTelemetry SDK 和库。然后，在本地运行应用程序并进行故障排除，以便在没有 OpenShift Container Platform 的情况下检测库和应用程序间的问题。
使用 Debug Exporter 验证遥测数据是否到达目的地 OpenTelemetry Collector 实例。如需更多信息，请参阅"Debug Exporter"。

法律通告
复制链接

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

对红帽构建的 OpenTelemetry 进行故障排除

诊断并解决 Collector 和检测问题

第 1 章故障排除
复制链接

1.1. 从命令行收集诊断数据
复制链接

1.2. 获取 OpenTelemetry Collector 日志
复制链接

1.3. 公开指标
复制链接

1.4. Debug Exporter
复制链接

1.5. 禁用网络策略
复制链接

1.6. 使用 Network Observability Operator 进行故障排除
复制链接

1.7. 对工具进行故障排除
复制链接

1.7.1. 对工作负载注入的故障排除
复制链接

1.7.2. 通过检测库生成遥测数据故障排除
复制链接

法律通告
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

对红帽构建的 OpenTelemetry 进行故障排除

诊断并解决 Collector 和检测问题

第 1 章 故障排除复制链接链接已复制到粘贴板!

1.1. 从命令行收集诊断数据复制链接链接已复制到粘贴板!

1.2. 获取 OpenTelemetry Collector 日志复制链接链接已复制到粘贴板!

1.3. 公开指标复制链接链接已复制到粘贴板!

1.4. Debug Exporter复制链接链接已复制到粘贴板!

1.5. 禁用网络策略复制链接链接已复制到粘贴板!

1.6. 使用 Network Observability Operator 进行故障排除复制链接链接已复制到粘贴板!

1.7. 对工具进行故障排除复制链接链接已复制到粘贴板!

1.7.1. 对工作负载注入的故障排除复制链接链接已复制到粘贴板!

1.7.2. 通过检测库生成遥测数据故障排除复制链接链接已复制到粘贴板!

法律通告复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 1 章故障排除
复制链接

1.1. 从命令行收集诊断数据
复制链接

1.2. 获取 OpenTelemetry Collector 日志
复制链接

1.3. 公开指标
复制链接

1.4. Debug Exporter
复制链接

1.5. 禁用网络策略
复制链接

1.6. 使用 Network Observability Operator 进行故障排除
复制链接

1.7. 对工具进行故障排除
复制链接

1.7.1. 对工作负载注入的故障排除
复制链接

1.7.2. 通过检测库生成遥测数据故障排除
复制链接

法律通告
复制链接