OpenTelemetry 映射故障排除

概述

SUSE Observability CLI 可用于排查 OpenTelemetry 拓扑同步问题，并修复可能阻止拓扑数据被正确摄取和显示在 SUSE® Observability 中的问题。本页面描述了在调试此类问题时应采取的一般故障排除步骤。

一般故障排除步骤

  1. 验证 OpenTelemetry 映射是否存在。

    • 如果没有映射，请验证 OpenTelemetry StackPack 的安装。

  2. 当缺少某种类型的组件或关系时，获取映射的状态。

    • 检查延迟指标以确定数据是否在流动，或者 OpenTelemetry 收集器与平台之间是否存在误通信。

    • 修复报告的映射错误，因为这些错误阻止某些拓扑元素同步。

    • 映射"静默"未按预期处理的潜在来源可能是输入字段中应用的条件/过滤。例如，如果条件为假，则没有错误 - 但映射被"跳过"。

有用的 CLI 命令

列出 OpenTelemetry 组件映射

返回所有当前 OpenTelemetry 映射的列表。

$ sts otel-component-mapping list
NAME                   | IDENTIFIER
Database               | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:database
Function Component     | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:function
Host Component         | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:host
Kubernetes Namespace   | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:namespace
Kubernetes Pod         | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:pod
OTel Service Component | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service-instance
OTel Service Instance  | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service
Task Component         | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:task

列出 OpenTelemetry 关系映射

返回所有当前 OpenTelemetry 映射的列表。

$ sts otel-relation-mapping list
NAME                                               | IDENTIFIER
Database Relation                                  | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database
Executes Relation (Function)                       | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:executes-function
Executes Relation (Host)                           | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:executes-host
Executes Relation (Task)                           | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:executes-task
Kubernetes to OTEL Relation                        | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:kubernetes-to-otel
OTel Async Relation (Consumer -> Peer)             | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:asynchronous-consumer-peer
OTel Async Relation (Producer -> Consumer)         | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:asynchronous-producer-consumer
OTel Async Relation (Producer -> Peer)             | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:asynchronous-producer-peer
OTel Synchronous Relation                          | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:synchronous
OTel service instance provided-by service relation | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:provided-by

显示 OpenTelemetry 组件或关系映射状态

OpenTelemetry 组件映射状态命令返回聚合的延迟、吞吐量指标和创建的拓扑元素数量。这在调试为什么拓扑的特定部分需要很长时间才能同步时非常有用。输出包括一个部分 Mapping errors，该部分将指示在将映射规则应用于 OpenTelemetry 数据时发生的任何问题。

$ sts otel-component-mapping status --identifier urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service


Otel Component Mapping:
NAME                  | IDENTIFIER                                                           | COMPONENTS | RELATIONS
OTel Service Instance | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service | 9          | 0


Otel Component Mapping Metrics:
METRIC          | 500S AGO | 500-1000S AGO | 1000-1500S AGO
latency seconds | 44.45    | 44.45         | 41.19

类似地，有一个 OpenTelemetry 关系映射状态

$ sts otel-relation-mapping status --identifier urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database


Otel Relation Mapping:
NAME              | IDENTIFIER                                                           | COMPONENTS | RELATIONS
Database Relation | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database | 0          | 2


Otel Relation Mapping Metrics:
METRIC          | 500S AGO | 500-1000S AGO | 1000-1500S AGO
latency seconds | 43.404   | 43.404        | 39.978


Otel Relation Mapping Errors:
No otel relation mapping errors found.

获取完整的 OpenTelemetry 组件或映射

要快速查看组件或关系映射的完整映射定义，请使用`get`命令：

$ sts otel-component-mapping get --identifier urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service
# Output omitted for brevity

或者对于关系映射：

$ sts otel-relation-mapping get --identifier urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database
# Output omitted for brevity

编辑 OpenTelemetry 组件或关系映射

如果您在映射定义中发现问题，请直接使用`edit`命令进行编辑。这将打开您默认的文本编辑器中的映射。

$ sts otel-component-mapping edit --identifier urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service
# Opens the mapping in your default text editor

或者对于关系映射：

$ sts otel-relation-mapping edit --identifier urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database
# Opens the mapping in your default text editor

如果映射被修改，保存并退出编辑器时将应用更改。

请记得在您的 StackPack 源文件中更新映射定义，以保持与通过 CLI 所做的任何更改同步。