View a markdown version of this page

使用 pcluster-diag 进行故障排除 - Amazon ParallelCluster
显示可用支票执行检查解释报告从中获取最新的 pcluster-diag GitHub
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 pcluster-diag 进行故障排除

pcluster-diag是一种诊断工具，用于验证健康 Amazon ParallelCluster 节点应满足的一组条件。

当集群在运行时出现异常行为时，用pcluster-diag作第一步。该工具会发出 JSON 诊断报告，以帮助您了解影响集群的问题。如果您无法解决问题，请将报告附加到 Amazon 支持案例中。

从 3.16.0 版开始的每个 Amazon ParallelCluster AMI 中都包含该工具，包括官方 AMI 和您构建时使用的自定义 AMI。pcluster build-image如果您使用的是旧 Amazon ParallelCluster 版本，则仍然可以按照中的步骤安装该工具低于 3.16.0 的版本。

你可以在任何群集节点pcluster-diag上运行。如果你不知道问题出在哪里，请在头节点上运行它。

主要特性

  • 上下文感知 ——在启动时，它会读取节点类型和已部署的集群配置，然后仅运行适用的检查。检查您的集群未使用的功能将被报告为已跳过。

  • Read-only 默认情况下，它永远不会更改集群的配置。非只读支票需要您的明确批准才能运行，如果您拒绝，则将其记录为跳过。

  • 一次运行即可完成 ——失败的检查永远不会停止其他检查。每一次适用的检查都会在每次调用时运行，因此，根据可用的检查，一次运行即可获得节点的完整情况。

显示可用支票

要查看该工具将执行哪些检查，请使用子命令，该describe-checks子命令返回每个注册支票的 JSON 数组，每个检查都有其 ID 和描述。

$ pcluster-diag describe-checks
[
  {
    "check_id": "...",
    "check_description": "..."
  },
  ...
]

执行检查

连接到要诊断的节点，然后以 root 身份执行run子命令。

$ sudo pcluster-diag run

pcluster-diag写入两个单独的流：

  • 标准错误的进度日志。

  • 将JSON报告转换为标准输出。同一报告还保存到当前目录下的带有时间戳的文件./pcluster-diag-output/中。

可用选项如下：

--output-file path

写入 JSON 报告的文件。例如，默认为下方的./pcluster-diag-output/带有时间戳的文件。./pcluster-diag-output/pcluster-diag-report-2026-08-04T10-12-00.json

-y, --yes

批准每张需要确认的支票，无需提示。当你pcluster-diag从脚本运行时使用它。

--version

打印pcluster-diag版本。

--help

打印使用信息。pcluster-diag run --help打印run子命令的选项。

解释报告

pcluster-diag发出一个 JSON 报告，说明它运行的每一次检查，无论检查是通过、警告、失败还是被跳过。context描述了被诊断的节点。该报告的总体结构如下：

{
  "context": { ... },
  "results": [
    {
      "check_id": "...",
      "check_description": "...",
      "status": "...",
      "errors": [ { "code": "...", "message": "..." } ],
      "warnings": [ { "code": "...", "message": "..." } ],
      "infos": [ { "code": "...", "message": "..." } ]
    }
  ]
}

检查状态

每张status支票都会告诉你该怎么做。

Status 含义 操作

PASSED

此检查没有发现任何问题。

-

WARNING

此检查发现了一些可能导致节点出现问题的东西。

查看清warnings单并解决任何可能重要的问题。

FAILURE

此检查在节点上发现了问题。

查看清errors单并解决所有问题。

CHECK_ERROR

检查无法完成，因此无法确认状态。

将其视为没有定论，而不是问题。将错误报告给 Amazon 支持部门，因为这可能是未处理错误的信号。

SKIPPED_NOT_APPLICABLE

该检查不适用于此节点类型或您的集群配置。

没什么。这是您的集群未使用的功能的预期状态。

SKIPPED_BY_USER

这张支票需要你确认，但你拒绝了。

重新运行pcluster-diag，出现提示时批准支票。

如果每张支票都有报告PASSED，没有pcluster-diag发现任何问题。但是，的覆盖范围pcluster-diag并不全面，并且会随着每个版本的发布而增加。健康的诊断并不能保证集群运行正常。

查看调查结果

检查结果可以包含三种结果，每种结果都有 a code 和 a message。

  • errors，已编码En，是检查失败的原因。保留代码E0仅用于导致无法正确执行检查的内部错误。

  • warnings，经过编码Wn，是非致命观察结果。

  • infos，已编码In，是上下文注释。

从中获取最新的 pcluster-diag GitHub

pcluster-diag适用于所有 Amazon ParallelCluster 版本 3.16.0 及更高版本，也可以通过一些额外步骤安装在旧版本上。

新的检查和改进的诊断消息已放入网站的 aws-parallelcluster-cookbook 存储库中。GitHub要在不等待下一个 Amazon ParallelCluster 版本的情况下使用最新的支票，请按照相应 Amazon ParallelCluster 版本的步骤进行操作。

版本 3.16.0 及更高版本

在 3.16.0 及更高 Amazon ParallelCluster 版本中，该pcluster-diag命令已安装并在上可用。PATH

要从develop分支更新工具，请在要执行该工具的节点上运行以下命令。

$ curl -fL https://github.com/aws/aws-parallelcluster-cookbook/archive/refs/heads/develop.tar.gz \
  | sudo tar -xz --strip-components=5 -C /opt/parallelcluster/sources/pcluster-diag \
    --wildcards '*/cookbooks/aws-parallelcluster-platform/files/pcluster-diag/*'

验证该工具是否正常运行：

$ sudo pcluster-diag describe-checks

要使用提示以外的版本develop，请develop在 URL 中替换为所需的分支或标签，例如分release-*支。

记住以下内容：

  • 刷新仅适用于您运行它的节点。在要使用新检查诊断的每个节点上重复此操作。

  • 工具源代码已内置到 AMI 中，因此被替换的节点会返回来自 AMI 的版本。

低于 3.16.0 的版本

在 3.16.0 之前的 Amazon ParallelCluster 版本中，该pcluster-diag命令未安装在节点上。

要从develop分支安装该工具，请在要执行该工具的节点上运行以下命令。

$ sudo mkdir -p /opt/parallelcluster/sources/pcluster-diag
curl -fL https://github.com/aws/aws-parallelcluster-cookbook/archive/refs/heads/develop.tar.gz \
  | sudo tar -xz --strip-components=5 -C /opt/parallelcluster/sources/pcluster-diag \
    --wildcards '*/cookbooks/aws-parallelcluster-platform/files/pcluster-diag/*'

验证该工具是否正常运行：

$ PYTHONPATH=/opt/parallelcluster/sources/pcluster-diag /opt/parallelcluster/pyenv/versions/3.12.8/envs/cookbook_virtualenv/bin/python3 -m pcluster_diag.cli describe-checks