本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 对 Amazon SageMaker HyperPod 可观测性附加组件进行故障排除
使用以下指南来解决 Amazon SageMaker HyperPod (SageMaker HyperPod) 可观察性附加组件的常见问题。
## 解决 Amazon Managed Grafana 中的指标缺失问题
如果 Amazon Managed Grafana 控制面板中未显示指标，请执行以下步骤来识别和解决问题。
### 验证 Amazon Managed Service for Prometheus 与 Amazon Managed Grafana 的连接
1. 登录 Amazon Managed Grafana 控制台。
1. 在左侧窗格中，选择**所有工作区**。
1. 在**工作区**表中，选择您的工作区。
1. 在工作区的详细信息页面中，选择**数据来源**选项卡。
1. 确认 Amazon Managed Service for Prometheus 数据来源存在。
1. 检查连接设置：
+ 确认端点 URL 正确。
+ 确认已正确配置 IAM 身份验证。
+ 选择 **Test connection (测试连接)**。确认状态为**数据来源正在运行**。
### 确认 Amazon EKS 加载项状态
1. 在 [https://console.aws.amazon.com/eks/home\$1/](https://console.amazonaws.cn/eks/home#/clusters) clusters 中打开 Amazon EKS 控制台。
1. 选择您的集群。
1. 选择**附加组件**选项卡。
1. 确认已列出 SageMaker HyperPod 可观测性插件且其状态是否为 **AC** TIVE。
1. 如果状态不是 **ACTIVE**，请参阅[附加组件安装失败故障排除](#troubleshooting-addon-installation-failures)。
### 确认容器组身份关联
1. 在 [https://console.aws.amazon.com/eks/home\$1/](https://console.amazonaws.cn/eks/home#/clusters) clusters 中打开 Amazon EKS 控制台。
1. 选择您的集群。
1. 在集群详细信息页面上，选择**访问**选项卡。
1. 在**容器组身份关联**表中，选择具有以下属性值的关联：
+ **命名空间**：`hyperpod-observability`
+ **服务账户**：`hyperpod-observability-operator-otel-collector`
+ **附加组件**：`amazon-sagemaker-hyperpod-observability`
1. 确保附加到此关联的 IAM 角色具有以下权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "PrometheusAccess",
"Effect": "Allow",
"Action": "aps:RemoteWrite",
"Resource": "arn:aws:aps:us-east-1:111122223333:workspace/workspace-ID"
},
{
"Sid": "CloudwatchLogsAccess",
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:PutLogEvents",
"logs:GetLogEvents",
"logs:FilterLogEvents",
"logs:GetLogRecord",
"logs:StartQuery",
"logs:StopQuery",
"logs:GetQueryResults"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:/aws/sagemaker/Clusters/*",
"arn:aws:logs:us-east-1:111122223333:log-group:/aws/sagemaker/Clusters/*:log-stream:*"
]
}
]
}
```
------
1. 确保附加到此关联的 IAM 角色具有以下信任策略。确认源 ARN 和源账户正确。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
"Effect": "Allow",
"Principal": {
"Service": "pods.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
],
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:eks:us-east-1:111122223333:cluster/cluster-name",
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
### 查看 Amazon Managed Service for Prometheus 限制
1. 登录 Amazon Web Services 管理控制台 并打开 Service Quotas 控制台，网址为[https://console.aws.amazon.com/servicequotas/](https://console.amazonaws.cn/servicequotas/)。
1. 在**托管配额**框中，搜索并选择 Amazon Managed Service for Prometheus。
1. 选择**每个工作区的活动序列**配额。
1. 在**资源级限额**选项卡中，选择 Amazon Managed Service for Prometheus 工作区。
1. 确保利用率低于您的当前配额。
1. 如果您已达到配额限制，请通过选择工作区左侧的单选按钮来选择该工作区，然后选择**请求在资源级别增加**。
### 验证是否已启用 KV 缓存和智能路由
如果`KVCache Metrics`仪表板缺失，则该功能未启用或未在中提及端口`modelMetrics`。有关如何启用此功能的更多信息，请参阅中的步骤 1 和步骤 3 [配置 KV 缓存和智能路由以提高性能](sagemaker-hyperpod-model-deployment-deploy-ftm.md#sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route)。
如果`Intelligent Router Metrics`仪表板缺失，请启用该功能以显示它们。有关如何启用此功能的更多信息，请参阅[配置 KV 缓存和智能路由以提高性能](sagemaker-hyperpod-model-deployment-deploy-ftm.md#sagemaker-hyperpod-model-deployment-deploy-ftm-cache-route)。
## 附加组件安装失败故障排除
如果无法安装可观测性附加组件，请执行以下步骤来诊断并解决问题。
### 查看运行状况探针状态
1. 在 [https://console.aws.amazon.com/eks/home\$1/](https://console.amazonaws.cn/eks/home#/clusters) clusters 中打开 Amazon EKS 控制台。
1. 选择您的集群。
1. 选择**附加组件**选项卡。
1. 选择出现故障的附加组件。
1. 查看**运行状况问题**部分。
1. 如果运行状况问题与凭证或容器组身份有关，请参阅[确认容器组身份关联](#verify-pod-identity-association)。此外，还需确保容器组身份代理附加组件正在集群中运行。
1. 查看管理器日志中的错误。有关说明，请参阅[查看管理器日志](#review-manager-logs)。
1. 请联系 S Amazon upport 并提供问题详情。
### 查看管理器日志
1. 获取附加组件管理器容器组（pod）：
```
kubectl logs -n hyperpod-observability -l control-plane=hyperpod-observability-controller-manager
```
1. 对于紧急问题，请联系 Amazon Web Services 支持。
## 查看所有可观测性容器组（pod）
SageMaker HyperPod 可观测性插件创建的所有 pod 都在`hyperpod-observability`命名空间中。要获取这些容器组（pod）的状态，请运行以下命令。
```
kubectl get pods -n hyperpod-observability
```
查找状态为 `pending` 或 `crashloopbackoff` 的容器组（pod）。运行以下命令可获取这些待处理或出现故障的容器组（pod）的日志。
```
kubectl logs -n hyperpod-observability pod-name
```
如果您在日志中未找到错误，请运行以下命令来描述容器组（pod）并查找错误。
```
kubectl describe -n hyperpod-observability pod pod-name
```
要获取更多上下文，请运行以下两条命令来描述这些容器组（pod）的部署和 DaemonSet。
```
kubectl describe -n hyperpod-observability deployment deployment-name
```
```
kubectl describe -n hyperpod-observability daemonset daemonset-name
```
## 对处于 pending 状态的容器组（pod）进行故障排除
如果您看到有处于 `pending` 状态的 pod，请确保该节点足够大，可以容纳所有 Pod。要确认这一点，请执行以下步骤。
1. 在 [https://console.aws.amazon.com/eks/home\$1/](https://console.amazonaws.cn/eks/home#/clusters) clusters 中打开 Amazon EKS 控制台。
1. 选择您的集群。
1. 选择集群的**计算**选项卡。
1. 选择具有最小实例类型的节点。
1. 在容量分配部分，查找可用的容器组（pod）。
1. 如果没有可用的容器组（pod），则需要更大的实例类型。
对于紧急问题，请联系 Amazon Web Services 支持。
## 对受限实例组的可观察性进行故障排除
使用以下指南来解决具有受限实例组的集群所特有的问题。
### 可观察性 pod 无法在受限节点上启动
如果可观察性 Pod 未在受限节点上启动，请检查 pod 状态和事件：
```
kubectl get pods -n hyperpod-observability -o wide
kubectl describe pod pod-name -n hyperpod-observability
```
常见原因包括：
+ **图像拉取失败：**如果可观察性容器镜像尚未列入受限节点的许可名单，Pod 事件可能会显示图像拉取错误。确保您运行的是最新版本的可观测性插件。如果升级后问题仍然存在，请与联系 Amazon Web Services 支持。
+ **污点容忍度：验证** Pod 规格是否包含受限节点所需的容忍度。启用 RIG 支持后，从版本开始的插件`v1.0.5-eksbuild.1`会自动添加此容忍度。如果您使用的是旧版本，请升级到最新版本。
### 查看受限节点上的 Pod 的日志
该`kubectl logs`命令不适用于在受限节点上运行的 Pod。这是预期的限制，因为日志流所需的通信路径在受限节点上不可用。
要查看来自受限节点的日志，请使用 Amazon Managed Grafana 中的**集群日志**控制面板，它可以 CloudWatch 直接查询日志。您可以按实例 ID、日志流、日志级别和自由文本搜索进行筛选，以查找相关的日志条目。
### 同时包含标准节点和受限节点的集群中的 DNS 解析失败
在混合集群（同时包含标准实例组和受限实例组的集群）中，标准节点上的 Pod 在尝试访问 Amazon 服务终端节点（例如适用于 Prometheus 的 Amazon 托管服务或）时可能会遇到 DNS 解析超时。 CloudWatch
**原因：**该`kube-dns`服务有来自标准 CoreDNS 容器和 RIG CoreDNS 容器的端点。由于网络隔离，标准节点 pod 无法到达 RIG CoreDNS 端点。当从标准节点 pod 向 R `kube-proxy` IG CoreDNS 终端节点对 DNS 请求进行负载平衡时，请求会超时。
**解决方案：**在`kube-dns`服务`internalTrafficPolicy: Local`上进行设置，以便 pod 只能到达其本地节点上的 CoreDNS：
```
kubectl patch svc kube-dns -n kube-system -p '{"spec":{"internalTrafficPolicy":"Local"}}'
```
应用此补丁后，重启受影响的可观察性 pod：
```
kubectl delete pods -n hyperpod-observability -l app.kubernetes.io/name=hyperpod-node-collector
```
### 来自受限节点的指标未到达亚马逊 Prometheus 托管服务
如果受限节点的指标未出现在您的 Amazon Prometheus 托管服务工作区中：
1. **验证执行角色权限。**确保受限实例组的执行角色拥有`aps:RemoteWrite`访问您的 Prometheus 工作空间的权限。有关更多信息，请参阅 [受限实例组的其他先决条件](hyperpod-observability-addon-setup.md#hyperpod-observability-addon-rig-prerequisites)。
1. **检查节点收集器 Pod 的状态。**运行以下命令并验证节点收集器 Pod 是否在受限节点上运行：
```
kubectl get pods -n hyperpod-observability | grep node-collector
```
1. **检查中央收集器部署。**在节点受限的集群中，该插件在每个网络边界部署一个中央收集器。确认每个边界都有中央收集器：
```
kubectl get deployments -n hyperpod-observability | grep central-collector
```
1. **检查 pod 事件是否有错误。**在收集器窗格`kubectl describe`上使用以查找错误事件：
```
kubectl describe pod collector-pod-name -n hyperpod-observability
```
如果在验证上述内容后问题仍然存在，请与联系 Amazon Web Services 支持。
### Pod 身份验证不适用于受限实例组节点
[确认容器组身份关联](#verify-pod-identity-association)故障排除步骤仅适用于标准节点。在受限节点上，插件使用集群实例组执行角色代替 Amazon EKS Pod 身份进行身份 Amazon 验证。如果受限节点中缺少指标，请验证执行角色权限而不是 Pod 身份关联。
### Fluent Bit 无法在受限节点上运行
这是预料之中的行为。故意不将 Fluent Bit 部署在受限节点上。来自受限节点的日志 CloudWatch通过 SageMaker HyperPod 平台发布到，与可观察性插件无关。使用 Amazon Managed Grafana 中的**集群日志控制面板查看**这些日志。