alibabacloud-alinux-sysom-inspection

SysOM Inspection（sysom-inspection）

検査は sysom-osops CLI コマンド（sysom-osops inspection ecs ...）で実行します。検査用 OpenAPI を直接呼び出さず、必ず CLI を使用してください。

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,... は、指定したすべてのインスタンスを検査し、異常度が最も高い上位 3 件を自動診断します。残りのインスタンスについては、レポートにコピーしてすぐ使える詳細調査コマンドを一覧表示します。
• リージョン全体： --scope-type all は、リージョン内のすべての ECS インスタンスを自動検出し（上限 5000 件）、同じ上位 3 件の自動診断と LLM による要約を 1 つのコマンドで実行します。
• レポートの再表示： --region <region> --scope-type <scope-type> --report-id <reportId>（または --region <region> --instance <instanceId> --report-id <reportId>）を実行すると、検査を再実行せず、既存のレポートをすぐに返します。検査結果では、元の --region と --scope-type／--instance を含むこの再表示コマンドが、next_steps に自動的に出力されます。

オブザーバビリティ

• UA テンプレート（すべての SDK リクエストで必須）：
  • AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}
  • このスキルで実行時に解決される形式：AlibabaCloud-Agent-Skills/alibabacloud-alinux-sysom-inspection/<SKILL_SESSION_ID>
• 統一された session-id のルール：
  • 1 つの session-id をセッションごと（CLI の実行 1 回につき）に 1 度だけ生成し、CLI と SDK の両方のリクエストを含むすべての API 呼び出しで一貫して再利用する必要があります。
  • 生成の優先順位：外部 env SKILL_SESSION_ID（優先）→ 自動生成のフォールバック sid-<32-char hex>（uuid4 hex）。注入された値が無効な場合は、生成された ID にフォールバックします。
  • 使用できる形式：[A-Za-z0-9][A-Za-z0-9._:-]{7,127}。
  • 解決された値はプロセス env 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 のキーワード／意図のマッピングから選択され、 クエリに一致する項目がない場合は全項目の調査に切り替わります。
• どのモードでも、調査（メトリクス＋ログ）-> 検出された異常の自動根本原因診断 -> LLM による中国語レポートの要約 という完全なクローズドループが実行されます。
• 自動根本原因診断は InvokeDiagnosis によってトリガーされます（params に __sysom_diagnosis_source=skill_hub を挿入）。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>（または --scope-type の代わりに --instance を指定）を使用すると、タスクの作成をスキップして既存のレポートを直接取得します。調査結果では、 元の --region と --scope-type／--instance を含むこの再実行コマンドが next_steps に自動的に出力されます。
• ローカルのしきい値／イベントルール設定は使用されません。異常の判定はサーバー側の調査レポートに基づきます。

エラー処理

CLI の呼び出しが失敗した場合は、エラーテキスト（Error: <Code>: ...）から失敗の種類を分類し、 無条件に再試行するのではなく、以下のように対処します。

• 権限（Forbidden.RAM）：sysom:InitialSysom／ sysom:InvokeAgentCli が不足していることを説明し、最小限のポリシーについて references/ram-policies.md を案内します。再試行しないでください。
• パラメーター（InvalidParameter、invalid argument）：問題のある引数を特定し、 インスタンス 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>（または --scope-type の代わりに --instance を指定）を使用すると、再実行せずに既存のレポートを再確認できます。元の --region と --scope-type／--instance を含む再実行コマンドは、調査結果の next_steps に自動的に出力されます。
• ローカルの Python CLI（./scripts/osops.sh inspection）は、sysom-osops を利用できない環境向けの フォールバックとしてのみ残されています。
• フォールバック経路のメモリ異常トリガーロジックは、scripts/sysom_cli/inspection/command.py に実装されています。
• 調査後の専門的な診断アクションを追加する場合は、InvokeDiagnosis の統合パターンを再利用してください。