Elasticsearchのインデックス作成と検索のトラブルシューティング

プラン: Premium、Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated

Elasticsearchのインデックス作成または検索を行う際に、以下の問題に遭遇することがあります。

空のインデックスを作成する

インデックス作成に関する問題については、まず空のインデックスを作成してみてください。Elasticsearchインスタンスでgitlab-productionインデックスが存在するかどうかを確認してください。存在する場合は、Elasticsearchインスタンス上のインデックスを手動で削除し、recreate_index Rakeタスクから再作成を試みてください。

それでも問題が発生する場合は、Elasticsearchインスタンス上に手動でインデックスを作成してみてください。次の場合:

インデックスを作成できない場合は、Elasticsearch管理者に問い合わせてください。
インデックスを作成できる場合は、GitLabサポートに問い合わせてください。

インデックス化されたプロジェクトのステータスをチェックする

プロジェクトのインデックス作成中にエラーがないか確認できます。エラーは以下で発生する可能性があります:

GitLabインスタンス: ご自身で修正できない場合は、GitLabサポートにガイダンスを求めてください。
Elasticsearchインスタンス: エラーがリストにない場合は、Elasticsearch管理者に問い合わせてください。

インデックス作成でエラーが返されない場合は、以下のRakeタスクでインデックス化されたプロジェクトのステータスを確認してください:

全体的なステータスを確認するにはsudo gitlab-rake gitlab:elastic:index_projects_status
インデックス化されていない特定のプロジェクトについてはsudo gitlab-rake gitlab:elastic:projects_not_indexed

インデックス作成が以下の場合:

完了した場合は、GitLabサポートに問い合わせてください。
完了していない場合は、sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=<project ID> ID_TO=<project ID>を実行してそのプロジェクトを再インデックスしてみてください。

プロジェクトの再インデックス作成でエラーが表示される場合:

GitLabインスタンス: GitLabサポートに問い合わせてください。
Elasticsearchインスタンス、またはエラーが全くない場合: Elasticsearch管理者に連絡して、インスタンスを確認してもらってください。

GitLabを更新した後に検索結果が表示されない

私たちはインデックス作成戦略を継続的に更新し、より新しいバージョンのElasticsearchをサポートすることを目指しています。インデックス作成に変更があった場合、GitLabを更新した後に再インデックス作成が必要になる場合があります。

すべてのリポジトリをインデックス化した後に検索結果が表示されない

ネームスペースのサブセットのみをインデックス作成するシナリオでは、これらの手順を使用しないでください。

すべてのデータベースデータをインデックス化したことを確認してください。

UI検索で結果（ヒット）がない場合は、Railsコンソール（sudo gitlab-rails console）経由で同じ結果が表示されるか確認してください:

u = User.find_by_username('your-username')
s = SearchService.new(u, {:search => 'search_term', :scope => 'blobs'})
pp s.search_objects.to_a

それに加えて、Elasticsearch Search APIを介して、Elasticsearch側でデータが表示されるか確認してください:

curl --request GET <elasticsearch_server_ip>:9200/gitlab-production/_search?q=<search_term>

より複雑なElasticsearch APIコールも可能です。

結果が以下の場合:

同期する場合は、サポートされている構文を使用していることを確認してください。高度な検索は厳密な部分文字列マッチングをサポートしていません厳密な部分文字列マッチング。
一致しない場合、これはプロジェクトから生成されたドキュメントに問題があることを示します。そのプロジェクトを再インデックス作成するのが最善です。

特定の種類のデータを検索する方法の詳細については、Elasticsearchインデックススコープを参照してください。

低い並行処理で高度な検索を有効にした後に検索結果がない

高度な検索を有効にした後、ドキュメントがインデックス化されず、コードが検索できないことに気付くかもしれません。Sidekiqログに次のようなメッセージが表示されることがあります:

"job_status":"concurrency_limit","message":"Search::Elastic::CommitIndexerWorker JID-352e0b9ee88af9f455c69b81: concurrency_limit: paused"

この問題を解決するには:

Rakeタスクgitlab-rake gitlab:elastic:infoを使用して、Indexing queuesのステータスを確認します。
Concurrency limit code queueがゼロでない場合は、コードインデックスの並行処理の値を確認してください。低すぎる値はインデックス作成の進行を妨げる可能性があります。この値を増やし、Rakeタスクで進行状況を確認することを検討してください。

Elasticsearchサーバーを切り替えた後に検索結果がない

データベース、リポジトリ、およびWikiを再インデックス作成するには、インスタンスをインデックス作成します。

`error: elastic: Error 429 (Too Many Requests)`でインデックス作成が失敗する

Search::Elastic::CommitIndexerWorker Sidekiqワーカーがインデックス作成中にこのエラーで失敗する場合、通常、Elasticsearchがインデックス作成リクエストの並行処理に追いついていないことを意味します。対処するには、以下の設定を変更してください:

インデックス作成のスループットを減らすには、Bulk request concurrencyを減らすことができます（高度な検索設定を参照）。これはデフォルトで10に設定されていますが、同時インデックス作成操作の数を減らすために1まで低く変更することができます。
Bulk request concurrencyの変更が役立たなかった場合、ルーティングルールオプションを使用してインデックス作成ジョブを特定のSidekiqノードのみに制限し、それによってインデックス作成リクエストの数を減らすことができます。

エラー: `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge`

[413] {"Message":"Request size exceeded 10485760 bytes"}

この例外は、Elasticsearchクラスターが特定のサイズ（この場合は10 MiB）を超えるリクエストを拒否するように構成されている場合に発生します。これはhttp.max_content_length設定とelasticsearch.ymlの対応です。それをより大きなサイズに増やし、Elasticsearchクラスターを再起動してください。

AWSには、基盤となるインスタンスのサイズに基づいてHTTPリクエストペイロードの最大サイズに関するネットワーク制限があります。最大バルクリクエストサイズを10 MiBよりも低い値に設定してください。

インデックス作成が非常に遅い、または`rejected execution of coordinating operation`で失敗する

Elasticsearchノードによって拒否されるバルクリクエストは、負荷と利用可能なメモリの不足が原因である可能性があります。Elasticsearchクラスターがシステム要件を満たしており、バルク操作を実行するのに十分なリソースがあることを確認してください。エラー「429 (Too Many Requests)」も参照してください。

`strict_dynamic_mapping_exception`でインデックス作成が失敗する

メジャーアップグレードを行う前にすべての高度な検索移行が完了していなかった場合、インデックス作成が失敗する可能性があります。このエラーには、大規模なSidekiqバックログが伴う場合があります。インデックス作成の失敗を修正するには、データベース、リポジトリ、およびWikiを再インデックス作成する必要があります。

Sidekiqが追いつくようにインデックス作成を一時停止します:
```
sudo gitlab-rake gitlab:elastic:pause_indexing
```
インデックスをゼロから再作成する。

インデックス作成を再開します:

sudo gitlab-rake gitlab:elastic:resume_indexing

`elasticsearch_pause_indexing setting is enabled`でインデックス作成が一時停止し続ける

検索を実行しても新しいデータが検出されないことに気づくかもしれません。

このエラーは、新しいデータが適切にインデックス化されていない場合に発生します。

このエラーを解決するには、データを再インデックス作成してください。

ただし、再インデックス作成時に、インデックス作成プロセスが一時停止し続けるというエラーが発生し、Elasticsearchログに以下の表示がされることがあります:

"message":"elasticsearch_pause_indexing setting is enabled. Job was added to the waiting queue"

再インデックス作成でこの問題が解決せず、手動でインデックス作成プロセスを一時停止しなかった場合、このエラーは2つのGitLabインスタンスが1つのElasticsearchクラスターを共有しているために発生している可能性があります。

このエラーを解決するには、GitLabインスタンスの1つをElasticsearchクラスターの使用から切断してください。

詳細については、イシュー3421を参照してください。

`too_many_clauses: maxClauseCount is set to 1024`で検索が失敗する

このエラーは、クエリの句がindices.query.bool.max_clause_count設定で定義されている数よりも多い場合に発生します:

Elasticsearch 7.17以前では、デフォルト値は1024です。
Elasticsearch 8.0では、デフォルト値は4096です。
Elasticsearch 8.1以降では、設定は非推奨であり、値は動的に決定されます。

この問題を解決するには、値を増やすか、Elasticsearch 8.1以降にアップグレードしてください。値を増やすと、パフォーマンスの低下につながる可能性があります。

エラー: `disk usage exceeded flood-stage watermark, index has read-only-allow-delete block`

このエラーは、Elasticsearchクラスターにディスク容量が危機的に低いノードが少なくとも1つある場合に発生します。デフォルトの透かししきい値である95%を超えるクラスターは、その後のすべての書き込み操作を防止する読み取り専用ブロックを強制します。このブロックにより、新しいインデックス操作が失敗し、古い検索結果が生じる可能性があります。

以下のRakeタスクでクラスターが読み取り専用モードかどうかを確認できます:

sudo gitlab-rake gitlab:elastic:info

blocks.writeまたはblocks.read_only_allow_deleteがtrueであることを示す出力を探してください。

Elasticsearchクラスターのディスク使用量を確認するには、以下のコマンドを実行してください:

curl --request GET '<your_ES_cluster>:9200/_cat/allocation?v&pretty'

この問題を解決するには、フルノードのディスクボリュームを増やしてください。以下のRakeタスクでクラスターサイズを見積もることができます:

sudo gitlab-rake gitlab:elastic:estimate_cluster_size

インデックスを再作成する最後の手段

何らかの理由でデータがインデックス化されずキューに入っていない場合、またはインデックスが何らかの状態で移行を進めることができない場合があります。ログを確認することで、問題の根本原因をトラブルシューティングするのが常に最善です。

最後の手段として、インデックスをゼロから再作成することができます。小規模なGitLabインストールの場合、インデックスの再作成は一部の問題を解決する迅速な方法となり得ます。しかし、大規模なGitLabインストールの場合、この方法は非常に長い時間がかかる可能性があります。インデックス作成が完了するまで、インデックスは正しい検索結果を表示しません。インデックス作成の実行中に、高度な検索による検索チェックボックスをクリアすることができます。

以前の警告を読み、続行したい場合は、以下のRakeタスクを実行して全体のインデックスをゼロから再作成する必要があります。

# WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE
sudo gitlab-rake gitlab:elastic:index

# WARNING: DO NOT RUN THIS UNTIL YOU READ THE DESCRIPTION ABOVE
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:index

デッドキュー

項目は、1回再試行された後に失敗するとデッドキューに入ります。デッドキューの項目は手動による調査が必要であり、自動的に再試行されることはありません。

ステータスの確認

デッドキューのサイズと詳細を確認するには:

Railsコンソールを開始します:
```
sudo gitlab-rails console
```
失敗した項目の数を確認します:
```
Search::Elastic::DeadQueue.queue_size
```
失敗した項目の詳細を検査します:
```
Search::Elastic::DeadQueue.queued_items
```
このコマンドは、各キーがシャード番号であり、各値が[spec, score]ペアの配列であるハッシュを返します。仕様には、失敗した項目に関する情報が含まれています。

項目の再試行

再試行したい項目をキューに入れます。これらの項目が再び失敗した場合、それらはデッドキューに戻されます。

デッドキュー内の項目を再試行するには:

Railsコンソールを開始します:
```
sudo gitlab-rails console
```

デッドキューから再試行キューに項目を移動します:

specs = Search::Elastic::DeadQueue.queued_items.flat_map { |_, items| items.map { |spec, _| spec } }

Search::Elastic::DeadQueue.clear_tracking!
Search::Elastic::RetryQueue.track!(*specs)

（オプション）インデックス作成状態を確認します。

デッドキュー内の項目を再試行せずに破棄するには、以下のコマンドを実行します:

Search::Elastic::DeadQueue.clear_tracking!

GitLabサポートに連絡する

デッドキューの項目についてヘルプが必要な場合は、以下の情報をGitLabサポートと共有してください:

Search::Elastic::DeadQueue.queue_sizeの出力
使用しているElasticsearchおよびGitLabのバージョン
インデックス作成の失敗がいつ始まったか
関連するアプリケーションログまたはエラーメッセージ

Elasticsearchのパフォーマンスを向上させる

パフォーマンスを向上させるには、次のことを確認してください:

ElasticsearchサーバーはGitLabと同じノードで実行されて等しくないことを確認してください。
Elasticsearchサーバーに十分なRAMとCPUコアがあること。
シャーディングが使用されていることに等しい。

ここでさらに詳しく説明すると、ElasticsearchがGitLabと同じサーバーで実行されている場合、リソース競合が発生する可能性がvery高いです。理想的には、十分なリソースを必要とするElasticsearchは、独自のサーバー（LogstashおよびKibanaと組み合わせることも可能）で実行されるべきです。

Elasticsearchに関しては、RAMが重要なリソースです。Elasticsearch自身が推奨しています:

非本番環境インスタンスの場合、At least8 GBのRAM。
本番環境インスタンスの場合、At least16 GBのRAM。
理想的には、64 GBのRAM。

CPUに関しては、Elasticsearchは少なくとも2つのCPUコアを推奨していますが、一般的なセットアップでは最大8コアを使用すると述べています。サーバー仕様の詳細については、Elasticsearchハードウェアガイドを確認してください。

明白なこと以外に、シャーディングが関係してきます。シャーディングはElasticsearchのコアな部分です。これにより、インデックスの水平スケーリングが可能になり、大量のデータを扱う場合に役立ちます。

GitLabがインデックス作成を行う方法では、インデックス化されるドキュメントのhuge量があります。シャーディングを使用することで、各シャードがLuceneインデックスであるため、Elasticsearchがデータを特定する能力を高速化できます。

シャーディングを使用していない場合、本番環境でElasticsearchの使用を開始すると問題が発生する可能性があります。

1つのシャードのみを持つインデックスにはno scale factor、ある程度の頻度で呼び出されると問題が発生する可能性があります。Elasticsearchのキャパシティプランニングに関するドキュメントを参照してください。

シャーディングが使用されているかどうかを判断する最も簡単な方法は、Elasticsearch Health APIの出力を確認することです:

赤はクラスターがダウンしていることを意味します。
黄はシャーディング/レプリケーションなしで稼働していることを意味します。
緑は正常であること（稼働中、シャーディング中、レプリケーション中）を意味します。

本番用途では、常に緑である必要があります。

これらの手順を超えて、マージやキャッシュなど、より複雑な確認事項に入ります。これらは複雑になる可能性があり、習得には時間がかかるため、さらに深く掘り下げる必要がある場合はElasticsearchの専門家とエスカレート/ペアを組むのが最善です。

GitLabサポートに問い合わせてください。ただし、これは熟練したElasticsearch管理者がより多くの経験を持っている可能性が高い問題です。

遅い初期インデックス作成

GitLabインスタンスのデータが多いほど、インデックス作成にかかる時間は長くなります。Rakeタスクsudo gitlab-rake gitlab:elastic:estimate_cluster_sizeでクラスターサイズを見積もることができます。

コードドキュメントの場合

コード、コミット、およびWikiを効率的にインデックス作成するために、十分なSidekiqノードとプロセスがあることを確認してください。初期インデックス作成が遅い場合は、専用のSidekiqノードまたはプロセスを検討してください。

非コードドキュメントの場合

初期インデックス作成が遅いものの、Sidekiqに十分なノードとプロセスがある場合は、GitLabで高度な検索ワーカー設定を調整できます。インデックス作成ワーカーをキューに再度追加の場合、デフォルト値はfalseです。非コードインデックス作成のシャード数の場合、デフォルト値は2です。これらの設定により、インデックス作成は1分あたり2000ドキュメントに制限されます。

前提条件:

管理者アクセス権が必要です。

ワーカー設定を調整するには:

右上隅で、管理者を選択します。
設定 > 検索を選択します。
高度な検索を展開します。
インデックス作成ワーカーをキューに再度追加チェックボックスを選択します。
非コードインデックス作成のシャード数テキストボックスに、2よりも大きい値を入力します。
変更を保存を選択します。