alibabacloud-alinux-sysom-inspection

SysOM 检查（sysom-inspection）

使用 sysom-osops CLI 命令启动检查 （sysom-osops inspection ecs ...）。请始终通过 CLI 操作，而不要直接调用检查 OpenAPI。

CLI 设置

检查 CLI 是否可用：

command -v sysom-osops

如果未安装，请安装：

curl -fsSL --connect-timeout 1000 https://sysom-prd-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/sysom_prd/skill_cli/install.sh | sudo bash

然后仅验证二进制文件：

command -v sysom-osops

如果已安装 CLI，但尚无 inspection 子命令，请先运行 sysom-osops update，然后重试。

如果命令因缺少 RAM 权限而失败，请按照 references/ram-policies.md 附加最低限度的权限策略。

快速入门

# Focused inspection by intent (--query)
# Run only CPU/load related items (keyword mapping)
sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "cpu related inspection"

# Combined intent: memory and disk
sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "memory and disk"

# Natural-language sentence: intent is extracted automatically, matching packet-loss items
sysom-osops inspection ecs --region cn-shenzhen --instance i-xxxxxxxx --query "check whether this machine has network packet loss"

# If the query matches no items, it falls back to a full inspection automatically

# Batch inspection (--scope-type batch, auto diagnosis supported)
# Inspect all specified instances -> auto root-cause diagnosis on the Top-3 most severe
# anomalous instances -> LLM summary (the rest get copy-ready deep-dive commands in the report)
sysom-osops inspection ecs --region cn-shenzhen --scope-type batch --instances i-aaa,i-bbb,i-ccc

# Region-wide inspection (--scope-type all, auto diagnosis supported)
# Auto-discover every ECS instance in the region (limit 5000) -> Top-3 anomalies auto-diagnosed
# -> LLM summary; one command for the full closed loop
sysom-osops inspection ecs --region cn-shenzhen --scope-type all

# Re-check an existing report (--report-id)
# Returns immediately without re-running (auto-generated in inspection next_steps).
# IMPORTANT: --region and --scope-type (or --instance) MUST match the original
# inspection command, otherwise the replay will fail with MissingParam errors.
sysom-osops inspection ecs --region cn-shenzhen --scope-type all --report-id inspection-82a64d9d-11c5-45b2-a81c-27fc754891e8

调用模式

• 定向检查： --query "<intent>" 会将关键词或提取出的意图映射到具体检查项（CPU/负载关键词映射、内存 + 磁盘等组合意图，以及网络丢包检查等自然语言句子）。如果查询未匹配任何检查项，则会自动回退到完整检查。
• 批量检查： --scope-type batch --instances i-aaa,i-bbb,... 会检查所有指定实例，自动诊断其中异常最严重的 Top-3 实例，并在报告中列出其余实例可直接复制使用的深入检查命令。
• 全地域检查： --scope-type all 会自动发现该地域中的所有 ECS 实例（上限为 5000 个），然后通过一条命令执行相同的 Top-3 自动诊断和 LLM 摘要。
• 报告重放： --region <region> --scope-type <scope-type> --report-id <reportId> （或 --region <region> --instance <instanceId> --report-id <reportId>）会立即返回现有报告，而不会重新运行检查；检查结果会自动在 next_steps 中提供此重放命令，并保留原始的 --region 和 --scope-type/--instance。

可观测性

• UA 模板（所有 SDK 请求均为必需）：
  • AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}
  • 本技能运行时解析后的形式：AlibabaCloud-Agent-Skills/alibabacloud-alinux-sysom-inspection/<SKILL_SESSION_ID>
• 统一的 session-id 规则：
  • 每个会话（一次 CLI 执行）只生成一个 session-id，并且必须在所有 API 调用（CLI 和 SDK 请求）中保持一致。
  • 生成优先级：外部环境变量 SKILL_SESSION_ID（优先使用）-> 自动生成的后备值 sid-<32-char hex>（uuid4 hex）；注入的值无效时，将回退到自动生成的 ID。
  • 接受的格式：[A-Za-z0-9][A-Za-z0-9._:-]{7,127}。
  • 解析后的值会导出到进程环境变量 SKILL_SESSION_ID，以确保下游调用保持一致。
• sysom-osops CLI 会自动注入 UA 标头，并遵循相同的统一 session-id 规则。

执行流程

• 每次检查前，CLI 都会验证 SysOM 是否已激活以及权限是否齐备（InitialSysom、 source=skill_hub）；激活和安装提示由 CLI 自行处理。
• 每次新检查都会调用 ROA API POST /api/v1/inspection/createInstanceInspection，并设置 source=skill_hub；所选项目由 --query 的关键词／意图映射确定；如果查询未匹配到任何项目，则回退到完整检查。
• 每种模式都会运行完整闭环：检查（指标 + 日志）-> 对检测到的异常自动进行根因诊断 -> 由大模型生成中文摘要报告。
• 通过 InvokeDiagnosis 触发自动根因诊断（将 __sysom_diagnosis_source=skill_hub 注入 params），并通过 GetDiagnosisResult 轮询，直到状态变为 success / fail 或超时。
• 批量模式（--scope-type batch --instances ...）会检查指定的每个实例；全区域模式（--scope-type all）会自动发现区域内所有 ECS 实例（上限 5000 个）。两种模式都会自动诊断异常最严重的 Top-3 实例，并在报告中为其余实例提供可直接复制的深入检查命令。
• 报告查询使用 ROA API GET /api/v1/inspection/getInspectionReport；CLI 会持续轮询，直到报告生成成功或超时。
• --region <region> --scope-type <scope-type> --report-id <reportId>（或用 --instance 替代 --scope-type）会跳过任务创建，直接获取已有报告；检查结果会自动在 next_steps 中输出此重放命令，其中包括原始的 --region 和 --scope-type／--instance。
• 不使用本地阈值／事件规则配置；异常判定由服务端检查报告提供。

错误处理

CLI 调用失败时，请根据错误文本（Error: <Code>: ...）对失败进行分类，并按以下方式处理，而不是盲目重试：

• 权限（Forbidden.RAM）：说明缺少 sysom:InitialSysom / sysom:InvokeAgentCli 权限，并指引用户查看 references/ram-policies.md，了解最低权限策略；不要重试。
• 参数（InvalidParameter、无效参数）：指出有问题的参数，并指导用户核实实例 ID 和区域；不要将其归咎于服务。
• 限流（Throttling）：告知用户请求受到速率限制，并建议稍后重试；不要自动循环重试。
• 内部错误（InternalError）：如实报告临时服务故障，并建议稍后重试；不要将其归咎于用户输入。
• 区域为空（no ECS instances found）：这不是错误。报告该区域没有 ECS 实例，并跳过检查；切勿伪造报告。

扩展说明

• 检查重点由 --query 控制（将关键词／意图映射到具体项目）；未匹配的查询会回退到完整检查。
• 批量检查使用 --scope-type batch --instances ...，整个区域使用 --scope-type all（最多 5000 个实例）；两种模式都会自动诊断异常最严重的 Top-3 实例。
• 使用 --region <region> --scope-type <scope-type> --report-id <reportId>（或用 --instance 替代 --scope-type）可在不重新执行的情况下重新查看已有报告；检查的 next_steps 中会自动输出重放命令，并包含原始的 --region 和 --scope-type／--instance。
• 仅在 sysom-osops 不可用的环境中，将本地 Python CLI（./scripts/osops.sh inspection）作为备用方案。
• 备用路径的内存异常触发逻辑仍在 scripts/sysom_cli/inspection/command.py 中实现。
• 如需添加更多检查后的专用诊断操作，请复用 InvokeDiagnosis 集成模式。