调试与故障排除

收集集群信息和调试日志，以排查 Standard Edition 相关问题。

注：

自主托管的 Standard Edition1.10.3 and earlier versions：

对于在线（非物理隔离）安装，大多数 stanctl 生命周期命令（例如） stanctl up 将无法运行。
对于物理隔离的系统，这些 stanctl 命令仍然有效。

所需操作：在执行生命周期操作之前，请升级 stanctl 至 1.10.4 或更高版本。

示例：在运行 stanctl1.10.3 或更早版本的在线部署中，任何在备份前停止服务的流程（例如 `stop` stanctl down 命令）都无法完成，因为后续的 stanctl up `start` 命令会失败。在开始执行以下步骤之前，请将系统升级 stanctl 至 1.10.4 或更高版本。

收集信息

使用有关集群的信息创建归档文件。您可以使用该文件中的信息对问题进行故障诊断，或者与支持团队共享该文件。

归档文件收集以下信息:

容器日志
资源清单（ YAML 格式）
stanctl 日志
包含内存， CPU 和 CPU 使用情况的系统信息
磁盘安装及其使用情况
打开文件 (已分配，可用和最大)
后端日志

使用以下命令来创建归档文件:

stanctl debug

运行该命令后，您将看到以下消息。当您在消息中看到 Done! 时，这意味着归档文件已就绪。

./stanctl debug
⠼ Streaming container logs  [26s] ✓
⠸ Gathering resource manifests  [27s] ✓
⠋ Gathering stanctl config files  [0s] ✓
⠋ Gathering system information  [0s] ✓
⠹ Creating tar file  [0s] ✓

----------------------
Done!
Debug package -> debug_20231027111737
Compressed debug package -> debug_20231027111737.tar.gz
----------------------

调整 Instana 组件的日志级别

要调整 Instana 组件的音量，请按照以下步骤操作：

编辑核心配置文件，例如， $HOME/.stanctl/values/instana-core/custom-values.yaml.

在 Core 或 Unit CR 中配置组件的日志级别。在下面的示例中，将组件 butler 的日志级别 DEBUG 更改为：

componentConfigs:
  - name: butler
    env:
      - name: COMPONENT_LOGLEVEL
        # Possible values are DEBUG, INFO, WARN, ERROR (not case-sensitive)
        value: DEBUG

运行以下命令以应用自定义值：
```
stanctl backend apply
 
```
运行以下命令查看日志：
```
kubectl logs <component name> -n instana-core
 
```
<组件名称> 是您要进行故障排除的组件名称。

安全套接层（ SSL ）证书

了解与 SSL 证书相关的支持配置、限制及故障排除步骤。

通配符 SSL 证书

您可以将通配符 SSL 证书与 Instana Standard Edition 配合使用。某些通配符配置不受支持，而特定的部署模式则需要更多考量。

场景示例

假设存在以下 DNS 结构：

通配符证书： *.company.com
Instana 后端： instana.company.com
受体终点： agent-acceptor.instana.company.com
Instana 用户界面： unit-tenant.instana.company.com

单层通配符的局限性

在此场景下，您无法使用通配符证书，例如 *.company.com 。

原因： 根据设计，星号 (*) 在 DNS 名称中只能替换一个标签。它不能跨越多个子域名层级。

证书匹配规则

证书 *.company.com 匹配结果：

www.company.com
api.company.com
mail.company.com

证书 *.company.com 不匹配：

a.b.company.com
dev.api.company.com
company.com

注：每个圆点 (.) 表示分隔一个 DNS 标签。通配符仅替换一个标签。

要支持 Instana 的部署，请使用以下选项之一：

为完整的主域名 Instana 创建一个通配符证书：
```
*.instana.company.com 
```

请使用一份列出了所有所需主机名的SAN证书。

DNS: api.example.com
DNS: dev.api.example.com
DNS: prod.api.example.com

在 SAN 证书中合并多个通配符条目：
```
DNS: *.example.com
DNS: *.api.example.com
```

恢复自签名证书

您可以恢复之前已删除的 TLS 自签名证书。

删除现有的 TLS 密钥：

kubectl delete secret instana-tls -n instana-core

生成一个新的自签名证书：
```
stanctl be apply --core-tls-generate-cert
```
结果：
- 已生成并应用了一个新的自签名 SSL 证书。
- TLS 已为 Instana 端点启用加密功能。
- 现代浏览器（如Chrome或 Firefox ）会显示安全警告，因为该证书并非由受信任的证书颁发机构签发的。
重要提示：尽管浏览器会将该连接标记为不可信，但所有通信仍保持加密状态。

摘要

*.company.com单级通配符证书（例如）不支持多级子域名。
Instana 标准通常要求使用SAN证书或基础域通配符证书。
如有需要，您可以放心重新生成自签名证书，届时浏览器会显示预期的警告。

故障诊断

解决这些问题。

Instana 代理未在用户界面中显示

删除用于远程监控的 Instana 代理并安装用于自我监控的 Instana 代理后，该代理可能不会显示在 Instana 用户界面中。

代理可能正在尝试连接到远程的 Instana 后端，而不是本地的 Instana 后端。

要解决此问题，请安装代理程序并指定后端端点主机和代理程序密钥:

stanctl agent apply --agent-cluster-name <cluster-name> --agent-endpoint-host acceptor.instana-core --agent-endpoint-port 8600 --agent-zone-name <zone-name> --agent-key <agent-key-of-local-backend>

Instana 当 Elasticsearch 数据磁盘的使用率超过85%时，后端将无法正常运行

Elasticsearch 当所用磁盘的使用率超过 85% 时，系统会自动将数据存储切换为只读模式。这会导致 Instana 后端停止运行。请为 Elasticsearch 数据磁盘释放空间或增加其容量，以恢复正常运行。注意：其他 Instana 磁盘在类似的使用率下（即使超过95%）也不会触发只读行为，这可能会让该问题显得难以理解。

要解决此问题，请采取以下任一措施：

释放 Elasticsearch 数据磁盘的空间
增加分配给 Elasticsearch 的磁盘空间

当可用空间充足时， Elasticsearch 将恢复正常的写入操作，后端也将恢复正常运行。

注意：其他 Instana 磁盘在类似的使用率下（即使超过95%）也不会进入只读模式，这可能会在故障排除过程中造成混淆。

Instana 后端升级失败，原因是 Helm 图表安装损坏

运行该 stanctl backend apply 命令后， Instana 后端升级失败。您可能会看到以下错误：

Error: another operation (install/upgrade/rollback) is in progress

在该 console.log 文件中，您可能会看到类似于以下条目的信息：

ts=2025-05-26T12:26:09Z level=INFO msg="upgrading Helm chart" name=instana-core release=instana-core version=1.8.1 namespace=instana-core
ts=2025-05-26T12:26:09Z level=DEBUG msg="preparing upgrade for instana-core"

此问题表明当前核心图表的 Helm 安装已损坏，您可以使用以下命令进行重置：

从命名 instana-core 空间中删除旧的 Helm 图表密钥。
```
kubectl delete secret -n instana-core -l owner=helm
 
```
升级后端。

stanctl up

主机代理无法连接到 SLES 主机上的 Instana 后端

在SUSE Linux Enterprise Server （SLES）15 SP5 主机上安装主机代理以进行自我监控后，该代理不会自动连接到 Instana 后端。

您必须使用代理外部地址 URL 作为远程主机连接到后端。

使用以下命令：

stanctl agent apply --agent-endpoint-host agent-acceptor.<base_domain> --agent-endpoint-port 8443

Kafka pods 显示 CrashLoopBackOff 的状态

Kafka 在 Instana 后端主机关机后，pods无法自动重启。您可能会看到 CrashLoopBackOffKafka Pods的状态。

要解决此问题，请重启 Instana 后端。

关闭后端。
```
stanctl down
 
```
启动后端。
```
stanctl up
 
```

重新启动后端后，请检查 Kafka pod 的状态。

kubectl get pods --all-namespaces | grep kafka

Kafka pod 状态应显示为 Running。

在执行 Instana 备份和还原后，计划的合成测试未运行

在恢复 Instana 的后端和代理数据后，计划的合成测试并未运行。

要解决此问题，请在安装 synthetic-pop-controller pod 的集群上重新启动该 pod。

Standard Edition 在 RHEL 上安装 9.3 失败

Red Hat® Enterprise Linux® 9.3 使用 iptables 1.8.8。

如果您正在 RHEL 9.3 上安装 Standard Edition ，安装可能会因 iptables 1.8.8 而失败。

要解决这个问题，请将主机升级到 RHEl 9.4，同时将 iptables 升级到 1.8.10 版本。

在 Standard Edition 上升级失败 1.9.x

当您将 Standard Edition 1.9.x 升级到更高版本时，可能会遇到以下错误：

Error: installation failed for prerequisite app coredns: Unable to continue with install: ConfigMap "coredns" in namespace "kube-system" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "coredns"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "kube-system"

要解决此问题，请再次运行该 stanctl up 命令。

升级失败，并显示“CPU 不足”或“内存不足”的错误

在资源有限的单节点 K3s 部署中，或在无法增加临时容量的环境中进行升级时，您可能会遇到以下任一问题：

诸如以下错误："Insufficient CPU"或"Insufficient memory"
留在Pending状态

默认的 RollingUpdate 策略需要在升级期间同时运行新旧Pod，因此需要额外的临时容量。在资源有限的系统上，即使整体利用率看似较低，这一需求也可能超过可用的 CPU 或内存。

要解决此问题，请使用“重新创建”更新策略，该策略在升级过程中无需额外容量：

stanctl up --core-update-strategy=Recreate

有关更新策略的更多信息，请参阅《配置升级的更新策略》

注：

“Recreate”策略会在升级过程中导致短暂的停机（几分钟）。对于非生产环境或无法扩充硬件容量的系统而言，这种权衡通常是可以接受的。

Systemd 不会设置默认工作目录

当由 stanctl systemd 服务启动时，systemd 不会自行设置工作目录。如果您未指定工作目录，systemd 将从 /. 目录运行该服务。此操作可能会导致文件（例如集群数据、 .stanctl或 Kubernetesstanctl 配置文件）被创建在错误的位置（通常是 / 或 /root/），即使该服务使用的是非 root 用户。

为了解决这个问题，您必须在 systemd 服务中添加一行 WorkingDirectory= 代码，以便将文件创建在用户的正确主目录中。例如， WorkingDirectory=/home/instana。

无法更新许可证

当您运行该 stanctl license update 命令时，可能会因以下错误信息导致命令执行失败：

...
no dependency found: 'instana-core'
...

运行以下命令以更新许可证：

stanctl license download --sales-key=<your-key>
stanctl backend apply

Instana 后端升级因节点磁盘空间不足而失败

当节点面临磁盘压力时， Instana 后端的安装或升级可能会失败。

故障现象

您可能会出现以下一种或多种症状：

后端安装或升级失败。
Pods 仍处于待处理状态。
某些工作负载显示 ContainerStatusUnknown.

原因

在安装、升级或导入离线软件包期间，随着容器镜像和构建产物的处理，磁盘使用量会暂时增加。如果节点磁盘空间不足， Kubernetes 会触发 DiskPressure 状态，并阻止新的 Pod 启动。

验证

运行以下命令以检查节点状态：
```
kubectl describe node <node-name>
```
在“条件”部分，勾选“ DiskPressure ”。
运行以下命令以检查磁盘使用情况：
```
df -h
```
请确认磁盘使用量是否已接近或达到容量上限。

解决方案

请执行以下任一操作以解决问题：

删除未使用的容器镜像或不必要的文件，以释放磁盘空间。
增加节点的存储容量。

恢复

如果恢复磁盘空间后工作负载仍处于该 ContainerStatusUnknown 状态，请重启该节点。重启完成后，请重新尝试安装或升级。

许可证无效或缺失

如果许可证无效或缺失，后端将阻止代理连接。

当这种情况发生时

导入的许可证无效。
Instana 操作员无法将许可证应用于 Groundskeeper 后端。

如何排除故障

请确认核心密钥中的销售密钥与单元密钥中的许可证字符串是否一致。如果两者不一致，请使用正确的销售密钥重新下载许可证。
请检查 Instana 服务器日志，查看是否存在许可证导入错误：
```
kubectl logs -n instana-operator deployment/instana-operator --tail=100
```
检查 Groundskeeper 后端组件、Pod 状态和日志：
```
kubectl get pods -n instana-core | grep groundskeeper 
```
如果许可证状态仍显示为无效，请联系 IBM 技术支持。

安装失败，提示“致命 glibc 错误：CPU 不支持 x86‑64‑v2”

症状

运行时 stanctl install，安装会在早期阶段失败，并出现类似以下的错误：

Fatal glibc error: CPU does not support x86-64-v2

此故障通常发生在所有组件安装完成之前，可能会导致诸如 Cassandra 和 Kafka 等服务无法启动。

原因

此错误表明操作系统无法检测到 x86‑64‑v2 指令集。最常见的原因是虚拟机的 CPU 配置未启用所需的 CPU 标志，这通常是由于兼容旧版系统的设置所致。

解决方案

在 VMware 和 vSphere 环境中，此问题通常是由选择了过时的虚拟 CPU 架构，或启用了会限制指令集的 CPU 兼容模式所导致的。要解决此问题，请执行以下操作：

配置虚拟机时，请避免使用旧版 CPU 兼容性配置文件。
请确保未启用 CPU 屏蔽功能。
如果启用了增强型 vMotion 兼容性（EVC），请确认其设置级别支持 x86‑64‑v2 指令集。
关闭虚拟机，并更新 CPU 配置。
如有必要，请使用更新的 CPU 设置重新创建虚拟机。

应用更改后，请在重新运行安装程序之前，确认所需 CPU 标志已在客户机操作系统中显示。

联系支持人员

如果您无法解决此问题，请联系 IBM 客服。向支持团队提供您创建的归档文件。