alibabacloud-aes-sysom-os-diagnosis

alibabacloud-aes-sysom-os-diagnosis

スキル名: alibabacloud-aes-sysom-os-diagnosis 目標: Alibaba Cloud ECS インスタンスで SysOM による OS レベルの詳細な診断を実行します。必要に応じて、インスタンスの登録と DingTalk アラートの設定も行います。

---

認証情報のセキュリティ

[CRITICAL] 認証情報のセキュリティルール：

• 絶対に AccessKey ID / AccessKey Secret の値を会話やコマンド出力に表示、エコー、出力しないでください（LTAI_ACCESS_KEY_ID を一部マスキングして表示することも禁止です）
• 絶対にユーザーに会話やコマンドラインで AK/SK を直接入力するよう求めないでください
• 絶対にリテラルの認証情報を指定して aliyun configure set を使用しないでください
• 認証情報の状態を確認するには、aliyun configure list のみを使用してください

aliyun configure list --user-agent AlibabaCloud-Agent-Skills

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確認してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. このセッション外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list --user-agent AlibabaCloud-Agent-Skills で有効なプロファイルが表示された後、戻って再実行します

---

RAM ポリシー

このスキルで必要な RAM 権限の一覧については、references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応： 実行中のいずれかの時点で、権限エラーが原因でコマンドまたは API 呼び出しが失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、このスキルで必要な権限の一覧を確認します
2. ram-permission-diagnose スキルを使用し、必要な権限の申請方法をユーザーに案内します
3. 必要な権限が付与されたことをユーザーが確認するまで待機します

---

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーが指定できるすべてのパラメーター（RegionId、インスタンス名、CIDR ブロック、 パスワード、ドメイン名、リソース仕様など）を、必ずユーザーに確認してください。 明示的な承認なしに、デフォルト値を想定または使用しないでください。

パラメーター	必須／任意	説明	デフォルト値
region	必須	ECS インスタンスのリージョン（例：cn-hangzhou）	なし。ユーザーが指定する必要があります
instance_id	必須	ECS インスタンス ID（例：i-bp1xxxxxxxx）	なし。ユーザーが指定する必要があります
ocd_description	任意	問題の説明（英語のみ。例：high_cpu）	""
start_time	任意	診断の開始タイムスタンプ（Unix 秒）	0（リアルタイム）
end_time	任意	診断の終了タイムスタンプ（Unix 秒）	0
enable_diagnosis	任意	リアルタイム診断を強制します（最優先）	false
uid	任意	インスタンスを所有するアカウント ID	None
skip_support_check	任意	インスタンスのサポート確認をスキップします（ワークフローを高速化）	false
cluster_id	任意	ACK クラスター ID（クラスター登録に必要）	None

---

コアワークフロー

このワークフローは、4 つのフェーズと 14 のステップで構成されています。すべての aliyun CLI コマンドには、必ず --user-agent AlibabaCloud-Agent-Skills を含めてください。

フェーズ 1：環境のセットアップ（ステップ 0～3）

ステップ 0 — AI モードの有効化とプラグインの更新

CLI コマンドを実行する前に、AI モードを有効にし、User-Agent を設定して、プラグインを更新します。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-aes-sysom-os-diagnosis"
aliyun plugin update

⚠️ 上記の 3 つのコマンドは、すべての CLI 操作に先立って実行する必要があります。実行するのは 1 回だけです。

ステップ 1 — CLI バージョンの確認

aliyun version --user-agent AlibabaCloud-Agent-Skills

バージョンが 3.3.1 以上であることを確認します。条件を満たさない場合は、インストール手順について references/cli-installation-guide.md を参照してください。

ステップ 2 — プラグインの自動インストールを有効化

aliyun configure set --auto-plugin-install true --user-agent AlibabaCloud-Agent-Skills

ステップ 3 — 認証情報の確認

aliyun configure list --user-agent AlibabaCloud-Agent-Skills

有効な認証情報がない場合は、停止し、セッション外で認証情報を設定するようユーザーに案内してください。

---

フェーズ 2：診断の実行（ステップ 4～9）

詳細なワークフローについては、references/diagnose-workflow.md を参照してください。

ステップ 4 — あいまいな問題の明確化（反転ゲート）

region と instance_id を必ず確認してください。ユーザーから提供されていない場合は、明示的に質問してください。また、任意の ocd_description（英語に翻訳する必要があります）、時間範囲なども抽出してください。

⚠️ 時刻推定ルール：ユーザーの説明に時間に関する言及（例：「今朝」「昨日の午後」「午後 3 時ごろ」「昨夜」）が少しでも含まれている場合、具体的な時間範囲を必ず事前に確認し、過去の診断モードを推奨してください。問題が明らかに過去に発生した場合に、リアルタイム診断を暗黙的にデフォルト設定しないでください。

ステップ 5 — Cloud Assistant のオンライン確認

aliyun ecs describe-cloud-assistant-status --biz-region-id <region> --instance-id <instance_id> --user-agent AlibabaCloud-Agent-Skills

応答の CloudAssistantStatus が true であることを確認してください。オフラインの場合は、パイプラインを終了してください。

ステップ 6 — SysOM のロール初期化

aliyun sysom initial-sysom --check-only false --source aes-skills --user-agent AlibabaCloud-Agent-Skills

ステップ 7 — インスタンスのサポート確認

aliyun sysom check-instance-support --instances <instance_id> --biz-region <region> --user-agent AlibabaCloud-Agent-Skills

ステップ 8 — 診断を呼び出して結果をポーリング

診断モードの決定ルール

if enable_diagnosis == true:
    mode = real-time diagnosis    # enable_diagnosis has highest priority
elif start_time != 0:
    mode = historical diagnosis   # time range specified, retrospective analysis
else:
    mode = real-time diagnosis    # default

• リアルタイム：start_time=0、end_time=0
• 過去：start_time=<unix_ts>、end_time=<unix_ts>
• リアルタイムを強制：enable_diagnosis=true の場合、指定されていても start_time を 0 に設定します

params JSON の構築

SDK と一貫性を保つため、snake_case のキーを使用してください。必須の基本フィールドはすべて含めてください。

{
  "instance": "<instance_id>",
  "region": "<region>",
  "start_time": 0,
  "end_time": 0,
  "type": "ocd",
  "ai_roadmap": true,
  "enable_sysom_link": false
}

⚠️ 混同防止の注意："type": "ocd" は params JSON 内の必須フィールドです。省略しないでください！

--service-name ocd（CLI 引数）と "type": "ocd"（params JSON フィールド）は異なる階層のパラメーターであり、両方とも必須です。

• --service-name ocd → 呼び出す診断サービスのエンドポイントを CLI に指定します
• "type": "ocd" → 内部で実行する診断タイプを診断エンジンに指定します

--service-name ですでに ocd を指定しているからといって、params から "type": "ocd" を省略しないでください！

条件付きフィールド（空でない場合のみ追加）：

• ocd_description：英語での問題の説明（例：high_cpu）
• uid：インスタンスを所有するアカウント ID（整数）

診断の呼び出し

aliyun sysom invoke-diagnosis \
  --service-name ocd \
  --channel ecs \
  --params '{"instance":"<instance_id>","region":"<region>","start_time":<start_time>,"end_time":<end_time>,"type":"ocd","ai_roadmap":true,"enable_sysom_link":false,"ocd_description":"<ocd_description>"}' \
  --user-agent AlibabaCloud-Agent-Skills

応答から task_id を抽出してください。Sysom.TaskInProgress エラーが返された場合は、エラーメッセージから既存の task_id を抽出し、ポーリングを続行してください。

結果のポーリング（間隔：10 秒、最大 60 回）

aliyun sysom get-diagnosis-result --task-id <task_id> --user-agent AlibabaCloud-Agent-Skills

ステップ 9 — 結果の解析と出力

返された JSON を解析し、summary.overall_status、summary.root_cause、summary.suggestions、issues[]、その他の主要な情報をユーザーに提示してください。

---

フェーズ 3：登録の推奨（ステップ 10～12）

詳細なワークフローについては、references/manage-and-alert-workflow.mdを参照してください。

ステップ 10 — 登録の推奨と意向の確認（逆転ダブルゲート）

このステップには、厳密に分離された 2 つのゲートがあり、必ず順番に実行してください。統合、省略、簡略化は禁止です。

10A — 登録を明確に推奨（第 1 ゲート）

⚠️ 必須ルール：診断結果を提示した後、以下の推奨内容をただちに逐語的に出力してください。省略したり、自分の言葉で短縮または言い換えたりしないでください。

<instance_id>を実際のインスタンス ID に置き換え、以下の内容を一字一句そのまま出力してください。

<verbatim_output>

🔔 推奨：インスタンスを登録して 24 時間 365 日の自動診断を実現

今回の診断は、手動で一度だけ実行したものです。SysOM でこのインスタンスを継続的に保護したい場合は、インスタンスの登録をおすすめします。

登録すると、以下の機能を利用できます：

• 🔍 自動診断：インスタンスで CPU の急上昇、メモリーリーク、IO レイテンシーなどのパフォーマンス問題が発生すると、手動操作なしで SysOM が自動的に詳細な診断を開始します
• 📲 DingTalk アラート：診断レポートがDingTalk グループボットに自動的に送信され、運用チームにただちに通知されます
• 🛡️ 継続的なモニタリング：24 時間 365 日、中断なく保護します。「問題発生後に調査する」運用から、「問題が発生したときに根本原因が自動で通知される」運用へ移行できます

インスタンス <instance_id> を登録しますか？

</verbatim_output>

上記を出力したら、停止してください。ユーザーの返答を待ってください。10A では登録方法について質問しないでください。

• ユーザーが辞退する → パイプラインを終了します
• ユーザーが同意する → ステップ 10B に進みます

10B — 登録方法を確認（第 2 ゲート）

ユーザーが 10A で明示的に同意した後に限り、以下を出力してください（<instance_id>と<region>は実際の値に置き換えてください）。

<verbatim_output>

登録方法を選択してください

A. 現在のインスタンスのみを登録 直前に診断したインスタンスのみを登録します：<instance_id>（<region>）

B. ACK クラスターを登録 このインスタンスが ACK クラスターに属している場合、ワンクリックですべてのノードを登録できます。 新たに追加されたノードも自動的に登録されるため、手動操作は不要です。 👉 ACK クラスター IDを入力してください（例：c9d7f3fc3d42********c1100ffb19d）

C. 指定した複数のインスタンスを登録 複数のインスタンスを一括登録します。 👉 インスタンス一覧をInstanceID:Region形式で、スペース区切りで入力してください 例：i-xxx:cn-beijing i-yyy:cn-hangzhou

A／B／C を選択するか、要件を直接お知らせください。

</verbatim_output>

上記を出力したら、停止してください。ユーザーの返答を待ってください。

ステップ 11 — 登録を実行

登録コマンドで使用する--agent-id、--agent-version、--config-idの固定パラメーター値は、references/related-commands.mdの「固定パラメーター」テーブルに記載されています。

# Instance mode
aliyun sysom install-agent \
  --instances instance=<instance_id> region=<region> \
  --install-type InstallAndUpgrade \
  --agent-id <agent-id> \
  --agent-version <agent-version> \
  --user-agent AlibabaCloud-Agent-Skills

# Cluster mode
aliyun sysom install-agent-for-cluster \
  --cluster-id <cluster_id> \
  --agent-id <agent-id> \
  --agent-version <agent-version> \
  --config-id <config-id> \
  --user-agent AlibabaCloud-Agent-Skills

ステップ 12 — 登録ステータスの確認

# Instance mode — poll instance status (interval: 10s, max: 60 attempts)
aliyun sysom list-instance-status --instance <instance_id> --biz-region <region> --user-agent AlibabaCloud-Agent-Skills

# Cluster mode — get full cluster list, then match target cluster by cluster_id
aliyun sysom list-clusters --user-agent AlibabaCloud-Agent-Skills
# From the returned cluster list, match the target cluster by cluster_id field and check its cluster_status

⚠️ 登録成功の基準：ステータスがRunningの場合、登録は完了です。ポーリングをただちに停止し、次のステップに進んでください。

---

Phase 4：アラート設定（手順 13～15）

詳細なワークフローについては、references/manage-and-alert-workflow.md を参照してください。

手順 13 — DingTalk Webhook の収集とアラート送信先の作成（反転ゲート + SDK 呼び出し）

登録に成功したら、アラート送信先を作成するため、ユーザーから DingTalk ボットの Webhook URL を直ちに必ず取得してください。この機能は CLI ではサポートされていません。scripts/ 配下の SDK スクリプトを使用してください。

ユーザーに次のように尋ねます。

<verbatim_output>

📲 アラート通知の受信先となる DingTalk グループボットの Webhook URL を入力してください。 形式：https://oapi.dingtalk.com/robot/send?access_token=xxx

💡 取得方法：DingTalk グループ設定 → ボット管理 → ボットを追加 → カスタムボット → 任意のキーワード：alert → Webhook URL をコピー

</verbatim_output>

ユーザーから Webhook を受け取ったら、SDK 環境を初期化し、アラート送信先を作成します。

# Initialize SDK environment (first time only, can skip afterwards)
bash scripts/setup-sdk.sh

# Create alert destination (stdout outputs destination_id)
.sysom-sdk-venv/bin/python scripts/create-alert-destination.py '<user-provided-webhook-url>'

⚠️ スクリプトの実行には .sysom-sdk-venv/bin/python を必ず使用してください。システムの python3 を使用することは禁止されています（署名アルゴリズムは特定の SDK バージョンに依存します）。

成功すると、標準出力に destination_id（数字のみ）が出力されます。この値を記録し、手順 15 で使用してください。

手順 14 — アラート項目の選択（反転ゲート）

aliyun sysom list-alert-items --user-agent AlibabaCloud-Agent-Skills

アラート項目の一覧を表示します（NODE／POD 別）。クイック選択（all、node-all、pod-all）と番号による選択に対応しています。

手順 15 — アラート戦略の作成（SDK 呼び出し）

ユーザーがアラート項目を選択したら、destinations に手順 13 の送信先 ID を設定して、アラート戦略を直接作成してください。

⚠️ CLI は destinations パラメーターをサポートしていません。アラート戦略の作成には、必ず SDK スクリプトを使用してください。

.sysom-sdk-venv/bin/python scripts/create-alert-strategy.py \
  --name "aliyun-aes-skills-create-<YYYYMMDDHHmm>" \
  --items "<alert_item_1>,<alert_item_2>" \
  --clusters "<clusters_value>" \
  --destinations "<destination_id>"

• インスタンスモード → --clusters の値は default
• クラスターモード → --clusters の値は <cluster_name>（名前であり、ID ではありません）
• --destinations → 手順 13 の送信先 ID（複数の ID はカンマ区切りで指定します。例：1,2）
• --items → アラート項目名をカンマ区切りで指定します

⚠️ スクリプトの実行には .sysom-sdk-venv/bin/python を必ず使用してください。システムの python3 を使用することは禁止されています。

---

成功の確認

各フェーズの確認方法については、references/verification-method.md を参照してください。

---

クリーンアップ

このスキルの診断操作は読み取り専用で、インスタンスの状態を変更しないため、クリーンアップは不要です。

登録済みの Agent をアンインストールするには、aliyun sysom uninstall-agent を使用してください（パラメーターについては references/related-commands.md を参照してください）。

すべての CLI 操作が完了したら、AI-Mode を必ず無効にしてください。

aliyun configure ai-mode disable

---

コマンド一覧

CLI コマンドの全一覧については、references/related-commands.md を参照してください。

---

ベストプラクティス

1. 診断前に Cloud Assistant のステータスを確認する：SysOM の診断には Cloud Assistant がオンラインである必要があります。必ずステップ 5 で確認してください
2. リアルタイム診断モードを使用する：ユーザーが時間範囲を明示的に指定しない限り、リアルタイム診断をデフォルトとして使用してください
3. ocd_description には英語のキーワードを使用する：API がサポートする文字は [a-zA-Z0-9_.~-] のみです
4. 登録の推奨には 2 段階の確認を使用する：まず推奨し、その後に方法を尋ねてください。情報を一度に与えすぎないようにします
5. クラスター登録の一括処理上限：インスタンスが 50 を超える場合、最初のバッチでは 50 インスタンスのみがインストールされ、残りは自動的にインストールされます
6. アラート戦略の clusters パラメーター：インスタンスモードでは default を使用し、クラスター�ードでは ID ではなくクラスターの名前を使用してください
7. SDK によるアラート送信先の設定：アラート送信先の API は CLI ではサポートされていません。Python SDK (alibabacloud_sysom20231230) を使用する必要があります
8. アラート戦略の destinations パラメーター：アラート送信先を作成した後、create-alert-strategy に destinations（送信先 ID のリスト）を含めてください。SysOM 経由で DingTalk にアラートが送信されます
9. 認証情報のセキュリティ：会話内で AK/SK の値を表示またはエコーしないでください
10. すべての CLI コマンドに --user-agent AlibabaCloud-Agent-Skills を含めてください
11. 修復の提案には高リスクの操作が含まれる場合があります：Human-in-the-loop プロトコルに従い、ユーザーの確認を待ってください

---

サポート対象外のシナリオ

• Linux 以外のインスタンス（Windows インスタンスはサポートされていません）
• 互換性のないカーネルバージョンのインスタンス（check-instance-support で確認します）
• 純粋な構成の問題（セキュリティグループのルールや VPC ルーティングなど、OS レベルの診断が不要なもの）

---

エラー処理

エラーのシナリオ	CLI の応答	エージェントの対応
SysOM がインスタンスをサポートしていない	check-instance-support が unsupported を返す	カーネルレベルの診断がサポートされていないことをユーザーに伝え、標準的な診断に切り替える
ロールの認可に失敗	initial-sysom がエラーを返す	SysOM サービスの有効化状況を確認するようユーザーに促す
診断の呼び出しに失敗	invoke-diagnosis がエラーを返す	認証情報と権限の構成を確認する
診断がタイムアウト	get-diagnosis-result のポーリングがタイムアウトする	後でもう一度試すようユーザーに提案する
権限不足	API が Forbidden を返す	references/ram-policies.md を読み、権限を申請するようユーザーを案内する
SDK がインストールされていない	ModuleNotFoundError: No module named 'alibabacloud_sysom20231230'	pip install alibabacloud_sysom20231230 を実行するようユーザーに促す
アラート送信先の作成に失敗	SDK がエラーを返す	Webhook URL の形式と認証情報の権限を確認する

---

参考リンク

参考資料	説明
references/cli-installation-guide.md	Aliyun CLI のインストールおよび構成ガイド
references/ram-policies.md	RAM 権限ポリシーの一覧
references/related-commands.md	CLI コマンドの全一覧
references/verification-method.md	各フェーズの成功確認方法
references/diagnose-workflow.md	詳細な診断ワークフロー（ステップ 4～9）
references/manage-and-alert-workflow.md	詳細な登録およびアラートのワークフロー（ステップ 10～15）
references/acceptance-criteria.md	テストの受け入れ基準