alibabacloud-rds-mysql-inspection

Alibaba Cloud RDS MySQL インスタンス検査スキル

このスキルは、Alibaba Cloud RDS MySQL インスタンスのヘルスチェックを一括で実行します。設定可能な期間（デフォルトは 7 日間、最大 30 日間）で、単一インスタンス、複数インスタンス、全体一括の 3 つのモードに対応し、標準化された HTML 検査レポートを生成します。

使用方法

手動でコマンドを実行する必要はありません。 自然言語でリクエストを説明するだけです。

プロンプトの例

例 1：単一インスタンス

• EN: Inspect RDS instance rm-bp1xxxxxx
• ZH: 帮我巡检下 RDS 实例 rm-bp1xxxxxx

例 2：期間を指定した複数インスタンス

• EN: Inspect rm-bp1xxx and rm-bp1yyy for the past 14 days
• ZH: 巡检 rm-bp1xxx 和 rm-bp1yyy 这两个实例，看最近 14 天的情况

例 3：全体検査

• EN: Run a health inspection on all RDS MySQL instances and produce a summary report
• ZH: 帮我对所有 RDS MySQL 实例做一次健康巡检，输出汇总报告

例 4：リージョンで絞り込み

• EN: Inspect all RDS MySQL instances in cn-hangzhou and cn-shanghai
• ZH: 巡检 cn-hangzhou 和 cn-shanghai 两个 region 的所有 RDS MySQL 实例

AI が自動的に行う処理

1. ユーザーの意図（単一／複数／全体）を認識し、期間のパラメーターを抽出します。
2. rds describe-regions を呼び出して、利用可能なリージョンの一覧を取得します（ClosedDown を除外）。
3. 各リージョンを並行してスキャンし、RDS MySQL インスタンスを検索します（リージョン ID は自動的に指定されるため、ユーザーが指定する必要はありません）。
4. 対象インスタンスごとに、属性、モニタリング、アラート、スローログ、ストレージデータを並行して取得します。
5. クラスターインスタンスを自動的に検出し、ノードごとのデータを収集します。
6. インスタンスごとの HTML レポートに加え、ヘルススコアのランキングと最適化の提案を含む概要 HTML レポートを生成します。

---

前提条件

実行環境

• Python：3.7 以降（標準ライブラリのみ）
• OS：Linux／macOS／Windows
• Aliyun CLI：3.3.3 以降、有効な認証情報で設定済みであること

インストールの確認

事前確認：Aliyun CLI 3.3.3 以降が必要です

aliyun version を実行して、バージョンが 3.3.3 以降であることを確認してください。CLI がインストールされていない場合、または古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたはアップグレードするか、 https://help.aliyun.com/zh/cli/ のインストール手順に従ってください。

事前確認：Aliyun CLI プラグインの更新が必要です

[MUST] aliyun configure set --auto-plugin-install true を実行して、自動プラグインインストールを有効にしてください。 [MUST] aliyun plugin update を実行して、ローカルにインストール済みのすべてのプラグインを最新の状態にしてください。

aliyun version
aliyun configure set --auto-plugin-install true
aliyun plugin update

Python の依存関係

Python 標準ライブラリのモジュール（subprocess、json、argparse、concurrent.futures、datetime）のみを使用するため、pip install は不要です。

---

[MUST] CLI User-Agent と AI モードの必須ルール

[MUST] CLI User-Agent — このスキルが実行するすべての aliyun CLI 呼び出しには、次の指定を含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-rds-mysql-inspection

scripts/inspect.py の call_cli() ラッパーがこの UA を自動的に設定するため、各コマンドで繰り返し指定する必要はありません。

[MUST] AI モードを有効にする — Agent Skill を実行する前に、AI モードを有効にする必要があります。 CLI コマンドを実行する前に、次のコマンドを実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-rds-mysql-inspection"

[MUST] すべての終了時に AI モードを無効にする — 最終応答を返す前に（成功、失敗、例外、ユーザーによるキャンセル、セッション終了のいずれの場合も）、AI モードを無効にする必要があります。AI モードは Agent Skill の実行中のみ使用するものであり、スキルの実行停止後に有効なままにしてはいけません。

aliyun configure ai-mode disable

---

必要な RAM 権限

このスキルは読み取り専用の RDS／CMS／DAS API を使用します。カスタムポリシーの完全な JSON、アクションごとの目的の表、およびシステムポリシーの代替案は、references/ram-policies.md に記載されています。スキルを実行する前に、そのポリシーを実行する RAM ID にアタッチしてください。

---

認証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• AK／SK の値を絶対に読み取ったり、エコーしたり、表示したりしないでください
• 会話やコマンドラインで、ユーザーに AK／SK を直接入力するよう絶対に求めないでください
• 認証情報の状態の確認には aliyun configure list のみを使用してください

aliyun configure list

出力を確認し、有効なプロファイルが存在することを確かめてください。認証情報が設定されていない場合は、会話の外で設定するようユーザーに案内してください。

aliyun configure

---

CLI 引数リファレンス

python3 scripts/inspect.py [options]

引数	短縮形	型	説明	デフォルト
--instance-ids	-i	string	インスタンス ID（複数回指定可能、または単一の値にカンマ区切りで指定）	なし
--all	—	flag	すべての RDS MySQL インスタンスをグローバルに検査します	オフ
--days	-d	int	期間の日数（1～30）	7
--start-time	—	YYYY-MM-DD	開始日（--days と同時には指定できません）	なし
--end-time	—	YYYY-MM-DD	終了日（--start-time と同時に指定する必要があります）	なし
--output	-o	path	出力ディレクトリ	./rds-inspection-reports/<ts>/
--profile	-p	string	Aliyun CLI のプロファイル名	デフォルトプロファイル
--regions	—	string	スキャン対象のリージョンを限定します（カンマ区切り）	すべて
--concurrency	-c	int	インスタンスごとの検査並列数	3
--region-concurrency	—	int	リージョンスキャンの並列数	3
--skip-space	—	flag	DAS のスペース分析をスキップします（インスタンスあたり 30～150 秒を節約）	オフ

検証ルール（スクリプトによって自動的に適用されます）：

• -i または --all のいずれか一方を必ず指定してください。
• --days は 1～30 の範囲で指定してください。この範囲外の値を指定するとエラーになります。
• --start-time と --end-time は必ず同時に指定し、期間は 30 日以内にしてください。

---

コアワークフロー

フェーズ 1：利用可能なリージョン一覧を取得

aliyun rds describe-regions --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-rds-mysql-inspection

返された Regions.RDSRegion[] から RegionId を抽出し、Status に closed が含まれるリージョンを除外します。

フェーズ 2：リージョンをまたいで RDS MySQL インスタンスを並行スキャン

リージョンごとに、次を呼び出します。

aliyun rds describe-db-instances --region <RegionId> \
  --engine MySQL --page-size 100 --page-number <N> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-rds-mysql-inspection

TotalRecordCount に基づいてページネーションを行い、すべてのレコードを取得するまで繰り返します。結果を統合して、完全な [{instanceId, regionId, ...}] リストを作成します。

フェーズ 3：対象インスタンスを絞り込み

• --all：すべてのインスタンス。
• -i id1,id2：完全なリストから絞り込みます（各インスタンスのリージョン ID は自動的に引き継がれるため、ユーザーが指定する必要はありません）。

一致しないインスタンス ID がある場合は警告を出しますが、ワークフロー全体は中止しません。

フェーズ 4：インスタンス属性のクエリ（デフォルトの並列数 3）

aliyun rds describe-db-instance-attribute --region <RegionId> \
  --db-instance-id <InstanceId> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-rds-mysql-inspection

主要なフィールドを抽出します：Category（インスタンスがクラスターかどうかを判定）、DBClusterNodes（クラスターのノード一覧）、MaxConnections、MaxIOPS、MaxIOMBPS、CurrentKernelVersion、LatestKernelVersion、ExpireTime など。

フェーズ 5：インスタンスごとの検査（デフォルトの並列数 3）

各インスタンス内では、次の収集手順を順番に実行します。

5.1 CMS メトリック収集（cms describe-metric-list）

主要なメトリックは5つです。MetricName と Dimensions は、インスタンスがクラスターかどうかによって異なります。

クラスターインスタンス（Category=cluster、ノードごとにクエリ）：

MetricName	意味
Cluster_CpuUsage	CPU 使用率
Cluster_MemoryUsage	メモリ使用率
Cluster_DiskUsage	ディスク使用率
Cluster_IOPSUsage	IOPS 使用率
Cluster_ConnectionUsage	接続使用率

Dimensions：[{"instanceId":"<DBInstanceId>","nodeId":"<NodeId>"}]

非クラスターインスタンス：

MetricName	意味
CpuUsage / MemoryUsage / DiskUsage / IOPSUsage / ConnectionUsage	上記と同じ

Dimensions：[{"instanceId":"<DBInstanceId>"}]

呼び出しテンプレート：

aliyun cms describe-metric-list \
  --namespace acs_rds_dashboard \
  --metric-name <MetricName> \
  --period 60 \
  --start-time <StartMillis> --end-time <EndMillis> \
  --dimensions '<JSON>' \
  --length 2000 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-rds-mysql-inspection

すべてのデータポイントを取得するまで、NextToken を使ってページネーションします。

5.2 CMS アラート履歴（cms describe-alert-log-list）

aliyun cms describe-alert-log-list \
  --namespace acs_rds_dashboard --product rds \
  --search-key <DBInstanceId> \
  --start-time <ms> --end-time <ms> \
  --page-size 100 --page-number <N>

すべての結果をページネーションで取得します。アラートの重要度の降順で並べ替えます：CRITICAL / P0 / P1 > WARN / P2 > INFO / P3 / P4。

5.3 DAS スローログ統計（das describe-slow-log-statistic）

aliyun das describe-slow-log-statistic \
  --instance-id <DBInstanceId> \
  --start <ms> --end <ms> \
  --order-by <Count|QueryTime> \
  [--node-id <NodeId>] \
  --endpoint das.cn-shanghai.aliyuncs.com

注意：

• DAS エンドポイントは das.cn-shanghai.aliyuncs.com に固定されています（DAS は一元的にデプロイされています）。
• クラスターインスタンスでは --node-id を渡す必要があります（Master ノードを使用してください）。
• クエリは Count 順と QueryTime 順で、それぞれ1回ずつ実行します。

5.4 DAS 容量分析 — 上位20件

# Trigger the task
aliyun das create-storage-analysis-task \
  --instance-id <DBInstanceId> \
  --endpoint das.cn-shanghai.aliyuncs.com

# Poll for results
aliyun das get-storage-analysis-result \
  --instance-id <DBInstanceId> --task-id <TaskId> \
  --endpoint das.cn-shanghai.aliyuncs.com

5秒ごとにポーリングし、上限を180秒とします。StorageAnalysisResult.TableStats から上位20件のテーブルを取得します。

フェーズ 6：ヘルススコアの計算

各インスタンスを0～100点で評価します。減点項目：

• CPU／メモリ／IOPS／接続のピーク値が80%超：-10点、60%超：-5点
• ディスクが85%超：-15点、70%超：-5点
• スローログの合計件数が1000件超：-8点、100件超：-3点
• 重大／深刻なアラート：-10点
• カーネルバージョンが最新リリースではない：-3点
• 30日以内に有効期限が切れる：-5点
• インスタンスが Lock 状態：-8点

フェーズ 7：単一インスタンスの HTML レンダリング（5セクション）

各インスタンスについて、次のセクションを含む instances/<DBInstanceId>.html を生成します。

1. インスタンスの基本情報 — DBInstanceId / Engine + Version / Category（(cluster) タグ付き）/ Class / Storage / MaxConnections / MaxIOPS / MaxIOMBPS / プライマリおよびセカンダリのゾーン / VPC + VSwitch / ステータス / 支払いタイプ / Lock / メンテナンスウィンドウ / 作成日時 + 有効期限 / 現在および最新のカーネル / クラスターのノード一覧（クラスターの場合）。
2. リソース使用率（過去N日間） — 各メトリックの平均／ピーク／ステータス色を含むテーブルと、5つの ECharts 折れ線グラフ（dataZoom で連動）。クラスターの場合、ノードごとに1本の線を表示します。
3. 容量使用量上位20テーブル — DAS の TableStats に基づいて並べ替えます。列：データベース／テーブル／合計容量／データ／インデックス／断片化／行数。
4. スローログ統計（過去N日間） — Count 順と QueryTime 順の上位を示す2つのテーブル。
5. アラート履歴（過去N日間） — 重要度順に並べ替えたテーブル。最大200行。

フェーズ 8：サマリー HTML のレンダリング（8 セクション）

summary.html を出力します。アンカーナビゲーションに加え、次の 8 つのセクションを含みます。

1. インスペクションの概要 — KPI カード（総数／リージョン数／クラスター数／全体の健全性スコア／健全性の分布／アラート発生インスタンス数）と、4 つの円グラフ／棒グラフ（カテゴリ／ステータス／健全性／リージョン別）。
2. 健全性スコアのランキング — 健全性が低いインスタンスの上位 20 件を表示します。各行から、対応する単一インスタンスレポートに移動できます。
3. アラート発生インスタンスの統計 — KPI カード、重大度分布の棒グラフ、アラート数が多いインスタンスの上位 20 件を表示します。
4. リソース使用率の上位リスト — ピーク値順の上位 20 件の表を 5 つ表示します（CPU／メモリ／ディスク／IOPS／接続数）。
5. スローログの上位リスト — スローログ数、合計実行時間、単一ステートメントの最大実行時間別に、インスタンスの上位を表示します（インスタンス間で集計）。
6. 容量分析 — 使用容量の多いインスタンス、単一テーブルの上位 20 件（インスタンス間で集計）、断片化率の高いテーブルを表示します。
7. バージョンと有効期限 — カーネルのアップグレードが可能なインスタンス、有効期限まで 30 日以内のインスタンス、有効期限まで 90 日以内のインスタンスを表示します。
8. インスペクションの結論 — KPI カード（全体の健全性スコア、および健全／要注意／重大の各カテゴリのインスタンス数）と、集約された問題リスト（問題の種類別に分類：CPU 高負荷／メモリ高負荷／容量不足／スローログ過多／アラート過多／古いカーネル／有効期限接近。各行に影響を受けるインスタンス ID を列挙します）を表示します。

---

レポートの出力構成

./rds-inspection-reports/<timestamp>/
├── summary.html                  # Aggregated inspection report (8 sections)
└── instances/
    ├── rm-bp1xxx.html            # Per-instance report (5 sections)
    ├── rm-bp1yyy.html
    └── ...

サマリーレポートでは、すべてのインスタンス ID がハイパーリンクになっており、対応するインスタンス別レポートを新しいタブで開きます。

---

ステータスのしきい値

指標	正常	警告	重大
CPU 使用率	< 60%	60-80%	> 80%
メモリ使用率	< 60%	60-80%	> 80%
ディスク使用率	< 70%	70-85%	> 85%
IOPS 使用率	< 60%	60-80%	> 80%
接続使用率	< 60%	60-80%	> 80%
全体の健全性スコア	>= 80	60-79	< 60

---

クラスターと非クラスターの処理

項目	非クラスターインスタンス	クラスターインスタンス（Category=cluster）
CMS MetricName	プレフィックスなし（CpuUsage など）	Cluster_ をプレフィックスに付加
CMS Dimensions	{"instanceId":"<id>"}	{"instanceId":"<id>","nodeId":"<nid>"}。ノードごとにクエリします
DAS スローログ	--instance-id のみ	--node-id も渡す必要があります（Master ノードを使用）
HTML メトリクスチャート	単一の線	ノードごとに 1 本の線
クラスター単位の集計	該当なし	CPU／メモリのピーク値 = 全ノードのピーク値の最大値

クラスターのノードリストは、rds describe-db-instance-attribute が返す DBClusterNodes フィールドから取得します。

---

パフォーマンスの目安

シナリオ	推定所要時間
単一インスタンス（容量分析あり）	60-200 秒
単一インスタンス（--skip-space）	10-30 秒
同時実行数 3 で 10 インスタンス	5-15 分
--all で 50 インスタンス	30-90 分

実行を高速化するためのヒント：

• 大規模なバッチでは --skip-space を使用してください。DAS の容量分析にはインスタンスごとに 30-150 秒かかります。
• 対象インスタンスのリージョンが分かっている場合は、--regions cn-hangzhou,... を使用して他のリージョンをスキップしてください。
• -c を大きくすると同時実行数が増えます（CMS API にはデフォルトで 20 QPS の上限があるため、<= 5 を推奨します）。

---

安全ルール

これは読み取り専用のインスペクションスキルです。

• 変更操作（DDL／DML、インスタンス設定の変更）は固く禁じられています。
• インスペクション結果と最適化の提案のみを生成します。
• このスキルで使用する読み取り専用でない CLI 呼び出しは das create-storage-analysis-task のみです。これは副次的な分析タスクをスケジュールするもので、インスタンスのデータは変更しません。それ以外の呼び出しはすべて純粋な読み取り操作です。
• 変更操作はすべて、会話の外でユーザーが確認し、手動で実行する必要があります。

---

参考資料

• scripts/inspect.py — メインの検査スクリプト（CLI + 収集 + レンダリング）。
• references/ram-policies.md — RAM 権限の完全なリファレンス（カスタムポリシー JSON + アクションの目的）。
• Alibaba Cloud RDS API：https://help.aliyun.com/zh/rds/developer-reference/
• Alibaba Cloud CMS API：https://help.aliyun.com/zh/cms/cloudmonitor-1-0/developer-reference/
• Alibaba Cloud DAS API：https://help.aliyun.com/zh/das/developer-reference/