alibabacloud-elasticsearch-instance-diagnose

Alibaba Cloud Elasticsearch インスタンス診断

**Alibaba Cloud OpenAPI（コントロールプレーン）とElasticsearch REST API（データプレーン）**からシグナルを収集し、references/ 配下の SOP ナレッジベースと組み合わせて、根本原因分析、エビデンスチェーン、優先順位付けされた是正ガイダンスを生成します。また、複数の観点で問題が検出された場合は、発生順に並べたインシデントタイムライン（時間枠内の重大度と時刻。§5 Step 4 の **タイムラインと新しさ（必須）**を参照）も生成します。

アーキテクチャ：Alibaba Cloud Elasticsearch OpenAPI + Alibaba CloudMonitor（CMS）+ Elasticsearch REST API + 診断 SOP

完了条件：必須条件が適用され、ES_* が設定されている場合は、最終レポートを作成する前に、認証済みの ES API エビデンスを取得してください（§5 の実行可能性の順序を参照）。

---

1. 前提条件

1.1 Aliyun CLI

事前確認：RAM 権限の確認と OpenAPI CLI のフォールバックには、Aliyun CLI >= 3.3.1 が必要です aliyun version を実行し、バージョンが 3.3.1 以上であることを確認してください。CLI がインストールされていないか、バージョンが古い場合は、references/cli-installation-guide.md を参照してください。 インストール後、aliyun configure set --auto-plugin-install true を実行してプラグインの自動インストールを有効にしてください（このコマンドラインに平文の AccessKey ペアを渡さないでください。§1.2 を参照）。

1.2 Alibaba Cloud アカウントの認証とセキュリティ（必須）

セキュリティルール（必須）：

• AccessKey ID または AccessKey Secret の値を読み取ったり、表示したり、出力したりしてはいけません。
• 会話中に平文の AccessKey を貼り付けるようユーザーに促したり、要求したりしてはいけません。
• スクリプト、CLI 引数、curl URL に AccessKey を埋め込んではいけません。
• コマンドラインで文字列としての AccessKey ID/Secret を渡すために、aliyun configure set などを使用してはいけません。
• ユーザーが自発的にチャットに貼り付けた場合でも、AccessKey を受け取ってはいけません。
• 設定済みの CLI プロファイル（aliyun configure）か、ユーザーがローカルシェルで設定した ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET などの環境変数のみを使用してください（エージェントはセッション中にそれらの値を表示してはいけません）。

⚠️ ユーザーがチャットで AccessKey を提供した場合（例：「my AK is xxx」）

1. 直ちに停止します：認証情報が必要な Alibaba Cloud コマンドは実行しないでください。
2. 丁寧に断り、承認済みの設定方法の名前だけを案内してください（漏えいした可能性のあるシークレットを繰り返してはいけません）。
   • 推奨：ローカルターミナルで aliyun configure を実行し、プロンプトに従って認証情報を入力します。認証情報はローカルのプロファイルファイルに保存されます。
   • または、ローカルシェルで ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET を設定します（値を入力するのはターミナル内だけとし、チャットには入力しないでください）。
3. 認証情報が正しく設定された後にのみ、診断の依頼を再開してください。

シークレットを公開せずに認証情報を確認する：

aliyun configure list
aliyun --profile <profile_name> sts get-caller-identity

認証情報のポリシー：

1. aliyun configure プロファイル（デフォルトまたは --profile）を優先してください。
2. 有効なアイデンティティがない場合（configure list / get-caller-identity が失敗する場合）は、停止して、ユーザーにローカルで設定するよう案内してください。認証情報を推測したり、捏造したりしてはいけません。
3. 平文の AccessKey を会話で渡してはいけません。

1.3 Elasticsearch 直接接続の認証情報に関する境界

• ユーザーに ES_PASSWORD をチャットに貼り付けるよう求めてはいけません。パスワードを表示、出力、記録してはいけません。チャットからコマンド、フック、リポジトリ内のファイルにパスワードをコピーしてはいけません。
• curl -u "$ES_USERNAME:$ES_PASSWORD"（または同等のもの）でのシェル展開は、変数がユーザーのローカルシェルで事前にエクスポートされている場合に限り許可されます。シークレットをチャット、リポジトリにチェックインされるスクリプト、コマンド出力に文字列として記載してはいけません。
• ユーザーがチャットでパスワードを送ろうとした場合も、停止し、ES_PASSWORD は export を使ってローカルでのみ設定するよう依頼してください（§2.2 を参照）。

---

2. 環境のセットアップ

2.1 コントロールプレーン OpenAPI（Aliyun CLI 経由）

このスキルでのコントロールプレーンと CMS のデータ収集には、すべて Aliyun CLI を使用します。

[MUST] elasticsearch / cms — プラグインモードのシェルのみを使用（レガシー CLI は避ける）
エージェントが実行可能な aliyun コマンドを出力する場合（チャット、再現用エクスポート、コピー＆ペースト手順など）、プラグインのサブコマンド（小文字とハイフンを使用）と ケバブケースのフラグを使用してください。references/verification-method.md および scripts/openapi_cli_collect.py と同じ形式です。

• 使用しないでください：レガシーな POP 形式の呼び出し。同じ aliyun コマンド行で elasticsearch または cms の直後に パスカルケースの動詞が来る形式（従来の「アクション名＝サブコマンド」形式）、または新しいコマンドで --InstanceId、--Namespace、--StartTime のようなキャメルケースのフラグを使用する形式です。プラグインの動詞のみを使用してください（describe-instance、describe-metric-list など）。
• 命名の使い分け：DescribeInstance、ListSearchLog、DescribeMetricList などは OpenAPI アクション名（ドキュメント、RAM、コンソールで使用）です。シェル内で aliyun elasticsearch または aliyun cms の 直後に置くトークンは、CLI プラグイン名（describe-instance、list-search-log、describe-metric-list など）である必要があります。
• 標準のコントロールプレーン＋CMS の一括処理には、python3 scripts/check_es_instance_health.py を優先して使用してください。サブプロセスの呼び出しをこのリポジトリと整合させられます。
• CLI のリファレンス：Elasticsearch CLI 中心、云监控 CLI 中心。

AI モードとプラグインの基本設定（必須） — aliyun の OpenAPI／CMS コマンドを実行するすべての診断セッションを、次の方法でラップしてください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-diagnose"
aliyun plugin update
# … diagnosis: aliyun / python3 scripts/check_es_instance_health.py …
aliyun configure ai-mode disable

configure ai-mode がない、または失敗する場合：上記のラッパーをスキップし、次のブロックにある ALIBABA_CLOUD_USER_AGENT を使用してください。CLI の失敗（サブコマンドが利用できない場合など）を記録してください。プロファイルが有効かどうかは、aliyun configure list と sts get-caller-identity のみで判定します。「有効」または「有効性」と記述し、vaild とは書かないでください。

**User-Agent（必須）：**Alibaba Cloud API 呼び出し用の User-Agent を設定してください。

export ALIBABA_CLOUD_USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-diagnose"

CLI の堅牢化（推奨）：生の aliyun コマンドを作成する際は、まず §2.1 の MUST プラグイン形式を使用し、その後に --connect-timeout 3 --read-timeout 10 を追加してください（大きなレスポンスや CMS では read-timeout の値を増やします）。ネットワーク障害時に処理が無期限に停止するのを避けるため、インスタンス管理スキルの例に合わせてください。グローバルの User-Agent が設定されていない場合は、呼び出しごとに --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-diagnose を追加してください。check_es_instance_health.py 内の オプションの Elasticsearch プローブ（ES_* が設定されている場合）でも、同じ設定をスクリプトの --connect-timeout／--read-timeout として指定できます。これらはエンジン呼び出しの curl にのみ適用され、Aliyun OpenAPI クライアントには適用されません。

診断の前に実行してください。

aliyun version
aliyun configure list
aliyun --profile <profile_name> sts get-caller-identity

2.2 Elasticsearch API への直接アクセス（curl）

Elasticsearch エンドポイント（VPC またはパブリック）と管理者の認証情報を確認した後、ユーザーにローカル端末で接続用の環境変数を設定してもらってください。ユーザーごとの値をチャットにハードコードしないでください。

export ES_ENDPOINT="http://<elasticsearch-endpoint-ip>:9200"
export ES_USERNAME="elastic"
export ES_PASSWORD="<elasticsearch-admin-password>"

パブリックアクセスと http 対 https： DescribeInstance から publicDomain ／ domain と、報告された protocol を使用します。protocol が HTTP（一般的なパブリックリスナー）の場合、ES_ENDPOINT を http://<publicDomain>:9200 に設定します。HTTP のみのエンドポイントに https:// を使用すると、TLS エラー（例：WRONG_VERSION_NUMBER）が発生します。protocol が HTTPS の場合（または使用するポートで TLS が実際に有効になっている場合）のみ https:// を使用し、以下の HTTPS オプションに従って CA ／フィンガープリントのオプションを指定します。

http:// で「動作しない」場合 — https:// を試すタイミング： REST リスナーの信頼できる情報源として、DescribeInstance の protocol を扱います。http:// での 000、タイムアウト、または接続拒否は、通常、ネットワーク経路／許可リスト／セキュリティグループ／ホストまたはポートの誤りを意味します。protocol が引き続き HTTP の場合、「次は HTTPS を試す」という意味ではありません。protocol が HTTPS の場合（またはコンソール／製品ドキュメントにそのエンドポイントで TLS を使用すると記載されている場合）に、http:// での失敗がTLS またはスキームの不一致を示す症状（例：WRONG_VERSION_NUMBER、error:0A00010B、誤ったスキームでのプローブ中に即時に発生する SSL アラート）であれば、https:// に切り替えてください。protocol が HTTP で、プレーンな TCP のみが通知されている場合、到達性を確保するための代替手段として HTTPS は使えません。

認証情報の安全性

• 絶対に ES_PASSWORD を表示、出力、またはログに記録しないでください。チャットから認証情報をコピーして、シェル履歴や保存ファイルに残すことも絶対にしないでください。
• チャットでパスワードを平文で貼り付けるようユーザーに求めることは絶対にしないでください。
• 変数が設定されていることを確認するには、次のチェックのみを使用してください。

[[ -n "$ES_ENDPOINT" ]] && echo "ES_ENDPOINT: $ES_ENDPOINT" || echo "ES_ENDPOINT: NOT SET"
[[ -n "$ES_PASSWORD" ]] && echo "ES_PASSWORD: SET" || echo "ES_PASSWORD: NOT SET"

ネットワーク接続とアクセス制御

問題	確認方法	対処方法
パブリックネットワークアクセスが無効	Elasticsearch コンソール → ネットワーク	パブリックアクセスを有効にするか、VPC エンドポイントを使用する
パブリックアクセスの許可リスト	コンソール → セキュリティ → パブリックアクセス許可リスト	エージェントホストのパブリック IP を追加する
VPC の分離	例：telnet <ES_IP> 9200	VPC ピアリング、Express Connect、または同等の接続を使用する
セキュリティグループ	Elasticsearch をホストする ECS／セキュリティグループのインバウンドルール	TCP 9200（または設定済みのポート）を許可する

接続プローブ：curl -sS -o /dev/null -w "%{http_code}" --connect-timeout 5 "${ES_ENDPOINT}" — HTTP コード 000 は通常、経路に到達できないことを意味します。-u を指定しない場合の 401 は正常です（認証が必要です）。ES_PASSWORD が SET の場合は、認証付きの GET /_cluster/health（§7）に進みます。-u を指定した場合の 401 → 認証情報が誤っています。000 ／接続拒否／タイムアウト → ネットワーク、許可リスト、または TLS／スキームの不一致です。 HTTPS — 前提条件（満たす必要がある条件）

1. リスナー： 呼び出す Elasticsearch の HTTP ポート（変更していない場合は 9200）が、実際に TLS を使用している必要があります。DescribeInstance の protocol（HTTPS）またはコンソール／ネットワークのドキュメントと一致させてください。
2. URL： HTTP で使用するものと同じ ホスト（例：publicDomain）を使った https://<host>:<port> です。
3. クライアントによるサーバー証明書の信頼： クライアントがクラスターの証明書チェーン（クラスター／クラウドの CA PEM、または TLS が傍受される場合は社内プロキシの CA）を信頼する必要があります。curl では、curl --cacert /path/to/ca.crt ... を推奨します。-k / --insecure は、本番環境以外での短時間の診断に限って使用してください。
4. 認証： HTTP と同じ ES_USERNAME / ES_PASSWORD を使用します（TLS 経由の Basic 認証）。

HTTPS — このスキルでの記載方法

• 手動の curl（§7 および es-api-call-failures.md）： https:// の使用時にデフォルトのトラストストアにクラスター CA が含まれていない場合は、すべての curl に --cacert（またはテスト用の -k）を追加してください。
• check_es_instance_health.py のオプションの ES プローブ： -u のみを指定して curl を実行します。ES_CA_CERTS / ES_SSL_FINGERPRINT / ES_VERIFY_CERTS（これらは Python Elasticsearch クライアントで一般的な名前）は読み取りません。HTTPS インスタンスの詳細なチェックには、--cacert を指定した §7 の curl を使用するか、後で環境変数から --cacert を渡すようスクリプトを拡張してください。
• Python 形式の環境変数（他のツール向けの参考情報）： ES_CA_CERTS、ES_SSL_FINGERPRINT、ES_VERIFY_CERTS=false（テスト時のみ） — 現在、このリポジトリのオプションの curl 経由の処理には組み込まれていません。

---

3. RAM 権限の確認

[MUST] RAM 権限の事前確認

このスキルを実行する前に、プリンシパルに必要な RAM 権限があることを確認してください。 権限の一覧については、references/ram-policies.md を参照してください。 ユーザーから権限が不足していると報告された場合は、RAM コンソールで該当するポリシーをアタッチするよう案内してください。

---

4. パラメーターの確認

重要：パラメーターの確認 コマンドまたは API 呼び出しを行う前に、以下の項目をユーザーに確認してください。 宣言されていないデフォルト値を推測したり、ユーザー固有のパラメーターをハードコードしたりしないでください。

境界制御（必須）

• リージョンと instance-id を推測したり、未検証のデフォルト値から取得したりしてはいけません。 DescribeInstance の内容またはユーザーの明示的な説明と一致しない場合は、再確認してください。
• インスタンス A のメトリクス、ログ、または DescribeInstance の結論をインスタンス B に適用しないでください。ES_ENDPOINT は診断対象のインスタンスと一致している必要があります（以下の Elasticsearch API の事前検証を参照）。
• このスキルは読み取り専用の診断です。変更を伴うコントロールプレーン API（インスタンスの作成、サイズ変更、再起動、削除など）は呼び出さないでください。ユーザーが変更を依頼した場合は、推奨事項のみを提示してください。実行はコンソールまたは承認済みの変更ワークフローで行います。

パラメーター	必須	説明	デフォルト
instance-id	はい	Elasticsearch インスタンス ID（例：es-cn-xxxxx）。aliyun のフラグは --instance-id です（--InstanceId ではありません）。	-
region	はい	リージョン ID（例：cn-hangzhou）。aliyun のフラグは --region です（--region-id ではありません）。	-
profile	いいえ	Aliyun CLI プロファイル（明示的な --profile の指定を推奨）	default
ES_ENDPOINT	いいえ	Elasticsearch エンドポイント（API に直接アクセスする場合のみ）	-
ES_PASSWORD	いいえ	Elasticsearch 管理者パスワード（API に直接アクセスする場合のみ）	-
--window	いいえ	check_es_instance_health.py：分析対象の時間（分、デフォルトは 60）	60
--connect-timeout, --read-timeout	いいえ	check_es_instance_health.py：ES_* が設定されている場合に、オプションの ES エンジンプローブで使用する curl のタイムアウト（--connect-timeout → curl --connect-timeout、--read-timeout は curl -m に接続タイムアウトとともに適用されます）。デフォルトは 5 / 10 秒です。	5 / 10

---

5. エンドツーエンドの診断ワークフロー

エージェントの厳守ルール（必須）

Aliyun CLI の形式： aliyun elasticsearch と aliyun cms では、新しい実行可能コマンドのすべてで §2.1 の MUST（プラグインモードのみ） に従ってください。レガシーの DescribeInstance／ListSearchLog をサブコマンドとする行や、--InstanceId 形式のフラグをセッションのエクスポートやユーザー向けの手順リストに復活させないでください。これらは openapi_cli_collect.py と食い違い、静的チェックに失敗します。

OpenAPI／CMS は MUST のエンジン API の代わりにはなりません。 §5 の MUST 表の行、または check_es_instance_health.py のルールエンジンにおける MUST について、Alibaba Cloud OpenAPI と CloudMonitor は、エンジンレベルの根本原因を特定するために記載されている Elasticsearch REST 呼び出しの代わりにはなりません。実行可能な場合は、これらの curl エンドポイントを呼び出してください（§7 を参照）。これらは補完的なレイヤーであり、相互に置き換えられるものではありません。

実行可能かどうかは、推測ではなくチェックによってのみ判断します。 エージェントが Elasticsearch を呼び出せるかどうかは、実行可能性の確認順序（§5）を実際に実行して判断する必要があります。最低限、§2.2 に従って ES_ENDPOINT／ES_PASSWORD を確認し、ES_ENDPOINT を DescribeInstance と照合してから、認証済みの GET /_cluster/health を実行してください。セッション内でこれらの手順を実行せずに、ES_* が未設定である、またはパスに到達できないと想定しないでください。

Elasticsearch のインシデントでは、以下の4 つの手順に従ってください。それぞれ役割が異なります。

実行戦略（根本原因に基づく）

ポリシーの全文：es-api-diagnosis-strategy.md

データプレーンの curl による収集には、次の両方が必要です。

1. 実行可能性：ES_ENDPOINT と ES_PASSWORD が設定されており、ネットワーク経路が機能していること。
2. 必要性：根本原因の分析に、コントロールプレーンまたは CMS だけでは確認できないデータプレーンの証拠が必要であること。

発火した MUST テーブル行、または ルールエンジンの MUST の下に記載されたエンドポイントについては、その呼び出しの必要性はトリガーによってすでに満たされています。ただし、実行可能性は引き続き必要です（実行可能性の確認順序を参照）。それらのリストに含まれない、エンジンへの任意の curl については、es-api-diagnosis-strategy.md に従って、実行可能性と必要性を確認してください。

MUST のトリガー（以下の CMS 条件のいずれかに該当する場合、記載された Elasticsearch の証拠を収集します）：

トリガー	シナリオ	必要な Elasticsearch の証拠
ClusterStatus の最大値 ≥ Yellow / Red	クラスターの健全性	allocation/explain、_cat/shards
NodeCPUUtilization の最大値 > 80%	CPU の過負荷	_nodes/hot_threads、_tasks
NodeHeapMemoryUtilization の最大値 > 85%	メモリ負荷	_nodes/stats/breaker、GET /_cluster/settings?include_defaults=true（transient / persistent 内の indices.breaker.*）
スレッドプールの rejected > 0	パフォーマンス	_nodes/hot_threads、_nodes/stats/thread_pool
ノード間のリソース CV > 0.3	負荷の不均衡	_cat/shards、_cat/allocation
書き込み失敗またはインデックスが読み取り専用	ディスク／ウォーターマーク／ブロック	_cluster/settings、_all/_settings?filter_path=*.settings.index.blocks、_cat/allocation
Elasticsearch API のタイムアウトが断続的に発生し、CMS CPU > 80%	カスケード障害の可能性	_nodes/hot_threads、_nodes/stats/thread_pool、_tasks

スレッドプールの行： sop-query-thread-pool.md と sop-write-performance.md を参照して、search と write／bulk を判別してください（以下の書き込みパス／バルクの飽和も参照）。

ルールエンジンの MUST： check_es_instance_health.py が今回の実行について §5 MUST / §5–§7 の呼び出しを出力した場合は、上記の行と同様に扱い、実行可能性がある場合は記載された ES の証拠を収集してください。

拘束力のあるルール（MUST のトリガー）： 上記の MUST トリガー行のいずれか、または上記のルールエンジンの MUST が該当する場合、その証拠セットの必要性は満たされています。エンジンレベルの根本原因を特定するために必要な呼び出しは、OpenAPI／CMS では代替できません（クラスターの健全性については、Yellow / Red の場合に allocation/explain と _cat/shards）。以下の実行可能性の確認順序に従って、実行可能性を確認してください。認証情報が有効で到達可能な場合は、コントロールプレーンの収集と並行して、Step 2 の MUST 対象エンドポイントを実行してください。認証済みの GET /_cluster/health 後もブロックされる場合は、ブロック理由を冒頭に示してください。理由は、ES_* が未設定、トランスポート障害（000、接続拒否、タイムアウト）、-u を指定した状態での 401、スキーム／TLS の不一致です。ES_PASSWORD が設定済みの場合、未認証のプローブでの 401 は該当しません。

書き込みパス／バルクの飽和

ThreadPool.WriteRejected または write プールのストレスが、高 QPS のバルクインデックス作成と一致する場合は、証拠の連鎖、rejected の意味（ノード起動後の累積値）、Old GC／ヒープとレポート順序（因果関係、または二重の P0 — JVM のみの見出しより先に書き込みパスを扱う）、ノードごとの rejected／completed の数値（拒否の割合）、ノード間の非対称性、書き込みのみの場合と検索の場合について、references/sop-write-performance.md — §2 の「Evidence interpretation: bulk QPS → write pool」サブセクションを読んで、その指示に従ってください。このサブセクションが該当する場合、JVM だけを軸にした説明を冒頭に置かないでください。write-queue 型の受け入れプロンプトでは、冒頭の結論は GC／ヒープだけを見出しにするのではなく、書き込みキャパシティ（データプレーンのカウンターと、必要に応じた CMS のルール名）に基づく内容にしてください。

検索優先と書き込み（どちらのプールも累積 rejected を表示）

同じノードで _nodes/stats/thread_pool に search.rejected ≫ write.rejected と表示され、ThreadPool.SearchRejected／クエリ起因の過負荷が該当する場合は、search（高い同時クエリ数／terms／遅いクエリ。確認できている場合はホットインデックス）を、エグゼクティブサマリーとP0 の優先順位の先頭に置いてください。write を先頭にしてはいけません。write.rejected は、並行要因または二次要因（バルク、キャッチアップ）として P0/P1 に残る場合があります。Old GC／CPU／ノード切断は、同時ストレス要因または連鎖的な問題として扱ってください。チェッカーの表示順は、説明の順序を裏付けるものではありません。acceptance-criteria.md §6.5 と sop-query-thread-pool.md の Report narrative を参照してください。

時系列で特定できる証拠がある場合、直近性はこの規模による既定の優先順位より優先されます。累積カウンターにはタイムスタンプがないため、search.rejected と write.rejected の比較だけで冒頭の説明の優先順位を決めてはいけません。評価基準の全文は、acceptance-criteria.md §6.5（P0 / executive order vs search ≫ write：書き込みが時間的に優勢な場合を除く）および §6.6（Executive order、No false recency from counters）を参照してください。必須：以下のタイムラインと直近性（必須）（同じスキル）に従ってください。

activating／変更ワークフローの停滞（レイヤー横断の根本原因）

インスタンスが activating のままで、変更が未完了であり、Red または未割り当てのシャードが併存する場合は、references/sop-activating-change-stuck.md に最初から最後まで従ってください（必須：ListActionRecords、修復前後の DescribeInstance、収集順序のセクション 3.1、報告のセクション 4を含みます）。

Elasticsearch API の事前検証

[IMPORTANT] ES_ENDPOINT は診断対象のインスタンスと一致している必要があります

DescribeInstance の publicDomain／domain と protocol を ES_ENDPOINT と比較してください。 一致しない場合は、次のように警告してください：⚠️ ES_ENDPOINT does not match the current instance; run export ES_ENDPOINT="http://{publicDomain}:9200"（protocol が HTTP の場合）。https://… を使えるのは protocol が HTTPS の場合のみです（デプロイに合わせてホスト／ポートを調整してください）。

Elasticsearch の認証情報がない、または接続に失敗する場合

[CRITICAL] 接続性の修正方法を明示的にユーザーに案内し、失敗モードを分類してください（タイムアウトが継続する場合に、既定で「許可リストのみ」の問題と判断してはいけません）。エージェントが「Elasticsearch を忘れた」と示唆してはいけません。最初の回答が CMS／OpenAPI 中心の場合は、以下の実行可能性の優先順位に従って、処理を妨げている理由を示してください：未設定の ES_*、転送エラー、有効な -u を指定した 401、TLS／スキームの問題。ES_PASSWORD が設定されているとき、-u を指定せずに実行したプローブでの 401 は該当しません（先に認証済みの curl を使用してください）。

段階的なプレイブック（順番に読む）： references/es-api-call-failures.md（セクション 1 → 4）。
必須／戦略の背景情報： references/es-api-diagnosis-strategy.md（セクション 1～3 および 3.5 のサマリーテーブル）。

必須条件に該当するが Elasticsearch が設定されていない場合の必須警告

[CRITICAL] 必須条件が発生したにもかかわらず、データプレーンの証拠が不足している場合は、レポートの先頭に警告を記載してください： references/es-api-call-failures.md のセクション 4に従ってください（最初に処理を妨げている理由を示し、次に必須項目と不足している証拠を記載します。ES_* が未設定の場合は、この SKILL のセクション 2.2を案内します。変数が設定済みの場合は、認証と転送の問題を判別するため、es-api-call-failures のセクション 1～2を使用してください）。

ステップ 1：簡易ヘルススキャン（初期シグナル）

軽量ルールエンジン（17 のメトリクスルール）を実行して、P0／P1／P2 の所見を一覧表示し、詳細な収集の方針を定めます：

python3 scripts/check_es_instance_health.py -i <InstanceId> -r <RegionId> [--window <minutes, default 60>] [--profile <profile_name>]

実行可能性の判定順序（エージェント）

1. §2.2 の ES_* チェックを実行します（パスワードは SET のみ）。省略しないでください。このステップなしに実行可能性を推測しないでください。
2. ES_ENDPOINT が DescribeInstance の domain／publicDomain（スキーム／ポート）と一致していることを確認します。
3. 認証済みの GET /_cluster/health を実行します。ES_PASSWORD が SET の場合、未認証のプローブで 401 が返ってもそこで終了しないでください。
4. 必ず範囲を絞ります。§5 のテーブル行および／またはルールエンジンの MUST 行を確認します。

ステップ 2：エビデンスを並行して収集する

ステップ 1 に基づき、シグナルのある項目を優先して並行収集します。
MUST を発動する行またはルールエンジンの MUST が該当する場合は、実行可能性の判定順序を実行してから、同じラウンドで curl により必要な Elasticsearch のエビデンスを収集します（§7 を参照）。該当する MUST がない場合は、戦略ドキュメントに従い、実行可能性と必要性の両方を満たす場合に限り、オプションのデータプレーン curl を追加します。

ステップ 1 と同じ実行パターンで check_es_instance_health.py を再実行します。この並行ラウンドでは、--window 120 と明示的な --profile <profile_name> が共通です。

コントロールプレーンのエビデンス（DescribeInstance、ListSearchLog、CMS 形式の呼び出し）を補完するには、references/verification-method.md の aliyun パターン（エポック時刻、プロファイル、名前空間）を使用します。

注：データプレーンへのアクセスには引き続き ES_ENDPOINT／ES_PASSWORD が必要です。Aliyun CLI でクラスターへの curl を置き換えることはできません。

MUST を発動する行では、記載されたエンドポイントの必要性はすでに確認されています。到達可能性を含む実行可能性が確保されている場合は、省略しないでください。該当する行以外では、ES_* が設定されているという理由だけで、無関係な一括 curl を実行しないでください。代わりに、戦略ドキュメントの実行可能性＋必要性の判定を使用してください。

ステップ 3：シグナルに応じて SOP を読む

シグナルを SOP に対応付け、詳細な判断のために読みます。複数のシグナルがある場合は、重大度に応じて P0 → P1 → P2 の順に処理し、その後ステップ 4 でタイムラインと新しさ（MUST）を適用します。これにより、説明の順序は静的なルールエンジンの出力順だけでなく、対象期間内でシグナルが重要だった時点と一致します。

観測されたシグナル	読む資料
クラスターが Red／Yellow、ノードの消失、保留中のタスク	references/sop-cluster-health.md
activating が長時間続く、変更レコードが未完了、Red／未割り当てシャード	references/sop-cluster-health.md + references/sop-activating-change-stuck.md
CPU 高負荷、ロード、不均衡	references/sop-cpu-load.md
ノードごとの負荷不均衡（CPU／メモリ／ディスク／シャード数）	references/sop-node-load-imbalance.md
JVM の圧迫、GC、サーキットブレーカー、OOM	references/sop-memory-gc.md
ディスクのウォーターマーク、IO、書き込み失敗（読み取り専用）	references/sop-disk-storage.md
ウォーターマークの誤設定、インデックスブロック、「正常」なディスク使用率にもかかわらず書き込みが失敗する	references/sop-disk-storage.md（セクション 3 — ウォーターマークの誤設定）
書き込みタイムアウト／拒否／レイテンシ／QPS の低下	references/sop-write-performance.md
クエリーのタイムアウト／拒否／低速クエリー	references/sop-query-thread-pool.md
ノードがダウンしているように見えるのに CPU は報告される、all shards failed	references/sop-service-avalanche.md
Elasticsearch のタイムアウトが断続的に発生し、CMS の CPU 使用率が 80% 超	references/sop-service-avalanche.md
リスクのある設定、Ngram の問題、API の異常	references/sop-configuration.md
イベントコードの定義	references/health-events-catalog.md

Step 4: 統合して構造化レポートを作成する

任意の受け入れ基準チェックリスト： references/acceptance-criteria.md §6.1–§6.6 — Red/Yellow、読み取り負荷の高い CPU ＋ search プール（＋ CMS との整合性）、JVM／ブレーカー／fielddata、書き込みキューと GC の比較＋rejected/completed、読み取り負荷の高い場合のsearch プールと GC のみの比較を見出しに記載（sop-query-thread-pool.md の レポートの説明：search プールと GC／CPU の見出し で詳述）、タイムライン／直近性。バルク／書き込み： references/sop-write-performance.md §2。シャードの reroute： references/sop-node-load-imbalance.md §1.3（アロケーター／変更管理のみ）。

[CRITICAL] 是正措置は診断した根本原因に合わせる必要があります — 汎用テンプレートは避けてください。誤ったブレーカーまたは同時実行数の修正（例：in_flight_requests と request の取り違え、原因が同時実行数の問題なのに「クエリを分割する」）については、sop-memory-gc.md と、シグナルに対応する SOP を参照してください。

activating ＋データプレーンの異常：レイヤー横断の根本原因を1行で記載してください。references/sop-activating-change-stuck.md のセクション4を参照してください。

レポートのひな形（コピーして記入）： references/report-template.md。

タイムラインと新しさ（統合レポートで必須）

問題： check_es_instance_health.py と P0/P1/P2 の区分が示すのは重大度であり、分析ウィンドウ内でシグナルがいつ最も重要だったかではありません。エンジンの累積カウンター（search.rejected、write.rejected）には、新しさを示す情報が含まれていません。書き込みと検索の問題がどちらも「実際に発生している」場合でも、最近の期間に優勢だったのは片方だけかもしれません（例：書き込みの負荷よりも、ウィンドウ終了時に近い時点で検索の負荷が高かった）。

エージェントの拘束力のあるルール：

1. 2 つの軸 — 重大度（P0/P1/P2）と時間的関連性（ウィンドウ終了時／「現在」への近さ）を、互いに独立したものとして扱ってください。優先度だけから新しさを推測しないでください（例：時間分解された証拠が異なることを示しているのに、「書き込みは P0 だから、現在の主な問題に違いない」と判断する）。
2. ユーザー向けセクションを必須とする — 複数の主要な検出事項が発生した場合（例：書き込みプール＋検索プール＋GC/CPU）、ユーザーが明示的に簡潔なレポートを求めていない限り、統合レポートにはエグゼクティブサマリーの前または直後に、### Incident timeline (recency-ordered)（または同等の）ブロックを必ず含めてください。そのブロックでは、次のようにします。
   • 箇条書きまたは行を時系列順（早い → 遅い）に並べるか、{begin} ~ {end} の後半にどのシグナル群がピークに達したか、または持続したかを記載します。
   • 乖離を明記します。例：CMS またはログが裏付けている場合、「ウィンドウの前半は書き込みパスに負荷が集中し、検索パス／CPU の負荷がより最近に高まった」。
3. 新しさの証拠（利用可能なものを使い、タイムスタンプを捏造しないでください）：
   • CloudMonitor：メトリクスごとの時系列を確認し、収集済み JSON で NodeCPUUtilization、NodeHeapMemoryUtilization、GC 関連メトリクス、ThreadPool.* がレートまたは非累積系列として公開されている場合、ピーク時刻または高い値が持続した時間帯を記載します。
   • スローログ／ListSearchLog：クエリとインデックスのスローエントリーを分単位で関連付けます。
   • エンジン（任意）： 既知の時刻に _nodes/stats/thread_pool を 2 回サンプリングして、rejected／completed の差分を示します。または、_tasks／hot_threads を使って、過去の累積カウンターではなく現在の偏りを示します。
4. エグゼクティブサマリーの順序 — 冒頭の 2～4 文では、新しさを重視したユーザー影響を反映します。書き込みよりも検索の負荷が現在に近い場合は、検索／クエリの同時実行数と、それに伴う負荷（GC/CPU）を適宜先に述べ、過去の書き込み飽和は背景情報または第 2 波として記載します。ただし、修復バックログに残すべき P0 の書き込み検出事項は削除しないでください。
5. 不確実性を明示する — 累積カウンターしかなく、パスごとの違いを示す時系列データがない場合は、新しさを区別できないと 1 行で述べてください。次回の実行では、より短いウィンドウ、スローログ、または差分サンプリングを推奨します。

---

6. データ収集の詳細（CLI OpenAPI＋注入入力）

ワンショット実行

§5 のステップ 1 と同じ check_es_instance_health.py コマンドを使用します（--window／--profile は任意です。省略した場合、デフォルトのウィンドウは 60 分です）。

注入入力モード（CLI と併用）

check_es_instance_health.py は、重複した呼び出しを避けるため、外部 JSON を受け付けます。

python3 scripts/check_es_instance_health.py \
  -i <InstanceId> -r <RegionId> \
  --data-source input \
  --input-json-file /path/to/diag-input.json

入力 JSON の形式：

{
  "status_info": {},
  "metrics": {},
  "events": [],
  "logs": []
}

--data-source のモード：

• auto：注入されたフィールドを優先し、不足分を Aliyun CLI で補完します。
• cli：注入データを無視し、すべて CLI で取得します。
• input：注入データのみを使用し、OpenAPI は呼び出しません。

コントロールプレーンの手動 CLI 補完

OpenAPI の追加例については、references/verification-method.md を参照してください。

7. Elasticsearch の直接 API アクセス（データプレーンの詳細）

実行可能性（到達可能性を含む）が満たされる場合は、いずれかの MUST トリガー行で必要とされる REST 呼び出しを実行します（§5）。発火した MUST 行に記載されていないエンドポイントは、戦略ドキュメントに従い、実行可能性と必要性の両方が満たされる場合にのみ呼び出します。

ES_ENDPOINT は host:port または完全な URL を指定できます。以下のサンプルでは、http://${ES_ENDPOINT#http://} に正規化してください（クラスターが TLS を使用する場合は、一貫して https:// を使用してください）。

タイムアウト：すべての curl で --connect-timeout 10 --max-time 30 を使用してください。

Red / Yellow（MUST）— 推奨セット

対象範囲： クラスターのヘルス状態に関する MUST 行では、ClusterStatus の最大値が Yellow 以上（Red を含む）を使用します。このセットを使って、エンジン上の未割り当て／誤割り当てシャードの根本原因を調べます。

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cluster/health?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  -H "Content-Type: application/json" \
  -X POST "http://${ES_ENDPOINT#http://}/_cluster/allocation/explain?pretty" \
  -d '{}'

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cluster/pending_tasks?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/stats/thread_pool?pretty"

クエリ／書き込みパフォーマンス（MUST）— 推奨セット

Step 1 で ヒープ／GC／ブレーカーのルールが発火した場合、または _nodes/stats/breaker で懸念が示された場合は、_cluster/settings を含めてください。indices.breaker.*／network.breaker.* の transient と persistent を読み取ります。

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/hot_threads?threads=3"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/stats/breaker?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cluster/settings?include_defaults=true&pretty"

/_cluster/pending_tasks と GET /_nodes/stats/thread_pool も上記の Red / Yellow（MUST） に記載されています。両方のセクションが該当する場合は、セッションごとに各 1 回呼び出してください。このパフォーマンスブロックのみを実行する場合は、そのブロックにある 2 行の curl を追加してください。

クローズドループを伴わないリソース異常（SHOULD）— 推奨セット

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cat/nodes?v&s=cpu:desc&h=name,ip,cpu,heap.percent,ram.percent,load_1m"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_nodes/stats/jvm?pretty"

curl -sS --connect-timeout 10 --max-time 30 -u "${ES_USERNAME:-elastic}:${ES_PASSWORD}" \
  "http://${ES_ENDPOINT#http://}/_cat/allocation?v&bytes=gb"

GET /_cluster/settings?include_defaults=true も上記の クエリ／書き込みパフォーマンス（MUST） に記載されています。両方のブロックが該当する場合は、1 つのレスポンスを再利用してください。この SHOULD ブロックのみを実行する場合は、そのブロックと同じ curl 行を追加してください。

プロトコルの確認（WRONG_VERSION_NUMBER を回避）：通常、ES_ENDPOINT の http/https スキームの不一致が原因です。スキーム／ポートを修正して再試行してください。

シナリオ → エンドポイントの索引：references/es-api-catalog.md。

---

8. 診断範囲

ナレッジベースは、ヘルスイベント形式のルールと連鎖シナリオ（例：ディスク圧迫 → 割り当て → Red）を 48 件以上網羅しています。カテゴリ別の件数、P0/P1/P2 の内訳、イベントコード：references/health-events-catalog.md — シナリオ別の運用手順書：references/sop-*.md（索引：references/README.md）。

---

9. ベストプラクティス

読み取り専用： 制御プレーン API による変更は行わず、ティアダウンもしません。

1. 段階的に進め、根拠に基づく：スキャン → SOP の詳細調査。すべての結論でメトリクス／ログ／イベントを引用します。ES に到達できない場合は、制限を明記してください（es-api-call-failures.md）。
2. 優先度と説明：緊急度は P0→P2 で示します。時間とともに複数の観点が異なる場合は、インシデントのタイムラインを使用します（Step 4）。認証情報／TLS／パラメーター： §1–2 および §4。
3. Green は「問題なし」を意味しません — ウォーターマーク、ブロック、誤設定された制限も重要です。MUST + 到達可能な ES： クラスターが Green であることや、OpenAPI が症状を「説明」していることを理由に、§5／§7 の証拠確認を省略しないでください。
4. スレッドプールの rejected： 差分を示さない限り、累積値です — sop-query-thread-pool.md §1–2。書き込み／バルク：sop-write-performance.md §2。

---

10. 参考リンク

• references/verification-method.md — 検証（診断の検証方法：メトリクス、API、ワークフロー）
• references/report-template.md — 構造化された診断レポートのひな形
• references/README.md — 言語マップ（参考資料と sop-*.md ランブック。このリポジトリでは英語です）
• references/ram-policies.md — RAM ポリシー一覧
• references/acceptance-criteria.md — 正しいパターンと誤ったパターン、および受け入れ基準（認証情報や安全性に関するアンチパターンを含みます）
• references/cli-installation-guide.md — Aliyun CLI のインストール
• references/es-api-catalog.md — Elasticsearch REST API カタログ
• references/health-events-catalog.md — ヘルスイベントカタログ
• references/sop-*.md — シナリオ別 SOP（例：activating／変更の停止や、レイヤーをまたぐ根本原因を扱う sop-activating-change-stuck.md）
• references/es-api-diagnosis-strategy.md — Elasticsearch API 診断戦略