DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

トラブルシューティング：Elasticsearchクラスタのヘルスステータスの確認と解釈

Elasticsearchクラスタのヘルス診断に不可欠なテクニックを習得します。このガイドでは、`_cat/health` APIを使用してステータスを確認し、重要なGreen、Yellow、Redのインジケーターを解釈する方法を詳しく説明します。未割り当てシャードの根本原因、`_cat/shards`や`_cluster/allocation/explain`などの高度なAPIを使用した詳細診断、および重大なクラスタの不安定性を迅速かつ効果的に解決するための実行可能な手順を学びます。

トラブルシューティング：Elasticsearchクラスタのヘルスステータスの確認と解釈

Elasticsearchクラスタのヘルスは、ページャーが鳴るまでは単純に見えるチェックの1つです。APIは色を返しますが、その色は出発点に過ぎません。グリーンのクラスタでも遅いことはあります。イエローのクラスタでも短いメンテナンス期間中は完全に使用可能です。レッドのクラスタは、小さなテストインデックスが利用不可であることを意味する場合もあれば、顧客向け検索で実際のデータが欠落していることを意味する場合もあります。

Elasticsearchクラスタのヘルスを確認するとき、私はredから危険なリカバリコマンドにすぐに飛びつかないようにしています。最初に3つの質問に答えたいと思います：プライマリシャードは割り当てられているか、レプリカは割り当てられているか、クラスタは現在自分自身でリカバリしようとしているか。以下のコマンドは、大まかなヘルスカラーから具体的な理由に移行するために私が使用するものです。

ヘルスAPIから始める

クイックターミナルビューには、_cat/healthで十分です：

curl -s "http://localhost:9200/_cat/health?v"

典型的なレスポンスは次のようになります：

epoch      timestamp cluster     status node.total node.data shards pri relo init unassign pending_tasks
1762219800 12:10:00  logs-prod   yellow          3         3    124  62    0    0        2             0

私が最初に確認するフィールドは、status、node.total、node.data、relo、init、unassign、pending_tasksです。initまたはreloがゼロより大きいイエローステータスは、単に再起動後にリカバリ中のクラスタである可能性があります。未割り当てシャードがあり動きがないイエローステータスは、通常調査が必要です。

自動化の場合は、_cat出力を解析する代わりにJSON APIを使用します：

curl -s "http://localhost:9200/_cluster/health?pretty"

そのレスポンスには、active_primary_shards、active_shards、relocating_shards、initializing_shards、unassigned_shards、delayed_unassigned_shardsなどのフィールドが含まれます。これらの名前は、スクリプトや監視チェックで使用するのが簡単です。

グリーン、イエロー、レッドの本当の意味

グリーンは、すべてのプライマリシャードと設定されたすべてのレプリカシャードが割り当てられていることを意味します。クエリが高速であること、ディスクが正常であること、マッピングが適切に設計されていることを意味するわけではありません。Elasticsearchが割り当てるべきシャードを配置したことだけを意味します。

イエローは、すべてのプライマリシャードが割り当てられているが、少なくとも1つのレプリカシャードが未割り当てであることを意味します。プライマリが利用可能であるため、データは検索可能であるはずです。リスクは冗長性です。レプリカがまだ未割り当ての状態でプライマリを保持するノードが失敗した場合、そのインデックスはレッドになる可能性があります。

レッドは、少なくとも1つのプライマリシャードが未割り当てであることを意味します。影響を受けるインデックスに対する検索は失敗するか、部分的な結果を返す可能性があり、それらのシャードへの書き込みは正常に進行できません。レッドは即座の注意を必要としますが、正しいアクションはプライマリが未割り当てである理由によって異なります。

一般的な小規模クラスタの例は、1つのレプリカが設定されたシングルノード開発クラスタです。Elasticsearchはプライマリと同じノードにレプリカを配置しないため、イエローのままになります。これは謎ではなく、割り当てを強制する理由でもありません。別のデータノードを追加するか、そのインデックスのレプリカをゼロに設定します：

curl -X PUT "http://localhost:9200/my-index/_settings"   -H 'Content-Type: application/json'   -d '{"index":{"number_of_replicas":0}}'

本番環境でこの設定を軽率に使用しないでください。そのインデックスの冗長性が削除されます。

正確な未割り当てシャードを見つける

ヘルスカラーの後、シャードをリストします：

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason" | sort

UNASSIGNEDを探します。prirep列は、シャードがプライマリ（p）かレプリカ（r）かを示します。この区別は、カラー自体よりも重要です。いくつかの未割り当てレプリカは、通常、フォールトトレランスの低下を意味します。1つの未割り当てプライマリは、インデックスの少なくとも一部が利用不可であることを意味します。

計画されたノード再起動後に多くの未割り当てシャードが見られる場合は、遅延割り当ても確認します：

curl -s "http://localhost:9200/_cluster/health?pretty" | grep delayed_unassigned_shards

Elasticsearchは、ノードが離脱した後、レプリカの再割り当てを待つ場合があります。ノードがすぐに戻ってくる可能性があるためです。この動作は、ローリング再起動中の不要なネットワークとディスクのチャーンを回避します。

Elasticsearchに割り当てが失敗した理由を尋ねる

割り当て説明APIは、最良の次のステップです。任意の未割り当てシャードについて尋ねることができます：

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{}'

または、特定のシャードについて尋ねます：

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "logs-2026.05.24",
    "shard": 0,
    "primary": false
  }'

unassigned_info、can_allocate、node_allocation_decisionsを読みます。有用な部分は通常、平易な英語です：ディスクのウォーターマーク超過、割り当て無効、一致するノード属性なし、ノード上のシャードが多すぎる、またはノードが1つしかないためレプリカを配置できない。

説明がallocation_delayedと言っている場合、欠落しているノードがすぐに戻ってくることが予想される場合のみ待機します。説明が割り当てルールを満たすノードがないと言っている場合、待機しても解決しません。

イエロークラスタのプレイブック

イエローヘルスの場合、私は次の順序を使用します：

  1. クラスタに設定されたレプリカ数に対して十分なデータノードがあるか確認します。
  2. _cat/allocationでディスクのウォーターマークを確認します。
  3. メンテナンス中に割り当てが無効にされていないか確認します。
  4. インデックスレベルのルーティングフィルターとアウェアネスルールを確認します。
  5. 容量を追加するか、レプリカ数を減らすか、不良ルールを修正するかを決定します。

ノード数の確認は簡単です。インデックスにnumber_of_replicas: 2がある場合、Elasticsearchは1つのプライマリと2つのレプリカを配置するために3つの適切なデータノードを必要とします。「適切」が重要です。割り当てアウェアネスが個別のゾーンを必要とする場合、単に任意の3つのノードではなく、それらのゾーンにノードが必要です。

割り当てとディスクを確認します：

curl -s "http://localhost:9200/_cat/allocation?v"

ノードがディスクのウォーターマークを超えている場合、Elasticsearchは新しいシャードの割り当てを拒否する可能性があります。空き容量を確保するか、ノードを追加するか、ディスクを拡張するか、スナップショットを取得した後に古いインデックスを削除します。ウォーターマークを上げることは、管理された緊急時には時間を稼ぐことができますが、容量を作成するわけではありません。

割り当て設定を確認します：

curl -s "http://localhost:9200/_cluster/settings?include_defaults=true&pretty"

cluster.routing.allocation.enableがnoneの場合、割り当ては無効です。これは、メンテナンススクリプトが元に戻すのを忘れた後によく見られます。次のようにして再度有効にします：

curl -X PUT "http://localhost:9200/_cluster/settings?pretty"   -H 'Content-Type: application/json'   -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "all"
    }
  }'

値がtransientとして設定されているかどうかも確認します。永続的設定と一時的設定の両方が動作に影響を与える可能性があります。

レッドクラスタのプレイブック

レッドヘルスの場合、速度を落として影響範囲を特定します。allocate_empty_primaryから始めないでください。そのコマンドは設計上データ損失を受け入れます。

まず、影響を受けるプライマリシャードを見つけます：

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"   | grep ' p '   | grep UNASSIGNED

次に、割り当て説明で1つを検査します：

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "affected-index",
    "shard": 0,
    "primary": true
  }'

プライマリがノードダウンのために未割り当ての場合、最善のリカバリはそのノードを復元することかもしれません。サービス、ディスク、JVMログ、ネットワークパスを確認します。別のノードにレプリカコピーが存在する場合、Elasticsearchは通常それを昇格させるはずです。そうでない場合、説明出力とログが通常その理由を教えてくれます。

データが失われたか破損している場合は、スナップショットから復元します。これがクリーンなリカバリパスです。スナップショットが存在せず、データを別のソースから再構築できる場合は、空のプライマリを割り当てることを決定するかもしれません：

curl -X POST "http://localhost:9200/_cluster/reroute?pretty"   -H 'Content-Type: application/json'   -d '{
    "commands": [
      {
        "allocate_empty_primary": {
          "index": "affected-index",
          "shard": 0,
          "node": "target-node-name",
          "accept_data_loss": true
        }
      }
    ]
  }'

シャードの内容を失うことが許容される場合にのみ使用してください。名前は文字通りです：Elasticsearchは空のプライマリを割り当てて先に進みます。

推測する代わりにリカバリを監視する

修正後、シャードの動きを監視します：

curl -s "http://localhost:9200/_cat/recovery?v&active_only=true"
curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"
curl -s "http://localhost:9200/_cluster/health?pretty"

リカバリは、ディスク速度、ネットワーク帯域幅、シャードサイズ、クラスタリカバリ設定によって制限される可能性があります。大きなシャードは、予想よりも長くINITIALIZING状態にとどまる場合があります。これはスタックしているのとは異なります。_cat/recoveryでバイト数とファイル数が移動している場合は、そのまま動作させます。

また、ヘルスが変化しない場合の保留中のクラスタタスクも確認します：

curl -s "http://localhost:9200/_cat/pending_tasks?v"

長いキューは、過負荷のマスターノードまたは完了できない繰り返しの割り当て決定を示している可能性があります。

実用的な例

_cat/healthが2つの未割り当てシャードでイエローを示しているとします。_cat/shardsは、両方ともlogs-2026.05.24のレプリカであることを示しています。割り当て説明は、すべてのデータノードが低ディスクウォーターマークを超えているため、クラスタが割り当てできないと言っています。修正は手動でシャードを再ルーティングすることではありません。修正は容量です：スナップショットを取得した後に古いインデックスを削除する、ストレージを追加する、データノードを追加する、またはコールドデータを別の場所に移動します。

別の例：3ノードクラスタがローリング再起動後にイエローになっています。_cluster/healthはdelayed_unassigned_shards: 8を示しています。停止したノードはすでに戻ってきています。その場合、数分待つことが正しいかもしれません。すぐに割り当てを強制すると、余分なリカバリ作業が発生し、再起動が遅くなる可能性があります。

3つ目の例：シングルノードのラボクラスタが永久にイエローです。_cat/shardsは、すべての未割り当てシャードがレプリカであることを示しています。インデックスには1つのレプリカがあります。Elasticsearchは正しく動作しています。ラボの場合はレプリカをゼロに設定するか、2番目のデータノードを追加します。

ヘルスチェックを正直に保つ

クラスタヘルスは監視の一部であるべきですが、アラートルールにはコンテキストが必要です。レッドにはすぐにアラートを出します。イエローには、短いメンテナンス期間を超えて続く場合、未割り当てレプリカが増加している場合、または理由がディスクプレッシャーである場合にアラートを出します。ヘルスカラーとともに、ディスクウォーターマーク、ノード数、JVMプレッシャー、スナップショットの成功を追跡します。カラーはどこから始めるかを教えてくれます。シャードと割り当てAPIは次に何をすべきかを教えてくれます。

ヘルスチェックがユーザーの症状と一致しない場合

クラスタがグリーンでユーザーがまだ不満を言っていることがあります。それは矛盾ではありません。クラスタヘルスはシャード割り当てに関するものであり、クエリレイテンシや正確性に関するものではありません。ヘルスがグリーンでも検索が遅い場合は、検索レイテンシ、スレッドプール、ホットシャード、JVMプレッシャー、ストレージレイテンシに移ります。1つの過負荷データノードを持つグリーンクラスタでも、壊れているように感じられることがあります。

逆も起こります。クラスタが無害な理由、例えばレプリカが設定されたシングルノード開発環境などでイエローになることがあります。有用な習慣は、ヘルス状態をビジネスへの影響に結び付けることです。どのインデックスが影響を受けていますか？プライマリですかレプリカですか？アプリケーションは今そのインデックスから読み取っていますか？これは計画メンテナンス中ですか？これらの質問は、すべてのイエローステータスを災害のように扱うことを防ぎます。

顧客向けシステムの場合、Elasticsearchの外部に小さなランブックテーブルを保持するのが好きです：インデックスパターン、所有サービス、データソース、スナップショットポリシー、データをリプレイできるか、破壊的なリカバリを承認する人。レッドインシデント中、そのテーブルは別のダッシュボードよりも役立つことがよくあります。clickstream-*をKafkaからリプレイできる場合、リカバリの選択は、上流コピーのないユーザー生成ドキュメントを保持するインデックスとは異なります。

より安全なコマンド習慣

可能な場合は明示的なインデックス名を使用します。ワイルドカードは便利ですが、影響範囲を隠します。設定を変更したりデータを削除したりするコマンドを実行する前に、パターンが何に一致するかをリストします：

curl -s "http://localhost:9200/_cat/indices/logs-prod-*?v&s=index"

インシデントからのコマンド出力を保持します。割り当て説明の結果、シャードリスト、ヘルスレスポンスをチケットに貼り付けます。Elasticsearchの状態はリカバリ中に急速に変化し、なぜ決定が下されたかを理解するために以前の出力が必要になる場合があります。

セキュリティが有効な場合、診断には最小限の有用な権限を持つユーザーでこれらのコマンドを実行し、破壊的な操作には別のより制限されたプロセスを使用します。ストレスの多いインシデントでは、ヘルスを検査していただけの同じシェルに書き込みコマンドを貼り付けるのは簡単すぎます。

クラスタがグリーンに戻った後に確認すること

グリーンはインシデントの終わりではありません。レプリカが期待したノードに再構築されたか、ディスクがまだウォーターマークに近いか、number_of_replicas: 0、長いrefresh_interval、または無効な割り当てなどの一時的な設定が残されたインデックスがないかを確認します。

また、リカバリ後にスナップショットが成功していることを確認します。シャードの問題が発生したばかりのクラスタは、保持、リポジトリ資格情報、またはスナップショットスケジューリングのギャップを露呈した可能性があります。リカバリがスナップショットが存在しなかったために運に依存していた場合、それを書き留めて、次の障害の前に修正します。

最後に、アラートを確認します。人間が監視よりも先に問題に気づいた場合、レッドヘルス、長期間続くイエローヘルス、ディスクウォーターマークプレッシャー、欠落ノード、失敗したスナップショット、繰り返されるマスター選出に対するアラートを追加または調整します。クラスタヘルスカラーは有用ですが、最良のアラートは、なぜカラーが変わったか、どのインデックスが影響を受けているかを教えてくれます。