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 검색 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"

이 문제를 해결하려면:

1. Rake 작업 gitlab-rake gitlab:elastic:info를 사용하여 인덱싱 큐 상태를 확인합니다.
2. 동시성 제한 코드 큐가 0이 아닌 경우 코드 인덱싱 동시성 값을 확인합니다. 너무 낮은 값은 인덱싱 진행을 방해할 수 있습니다. 이 값을 높이고 Rake 작업으로 진행 상황을 확인해 보세요.

Elasticsearch 서버 전환 후 검색 결과 없음#

데이터베이스, 저장소 및 위키를 다시 인덱싱하려면 인스턴스를 인덱싱합니다.

error: elastic: Error 429 (Too Many Requests)로 인덱싱 실패#

인덱싱 중에 Search::Elastic::CommitIndexerWorker Sidekiq 워커가 이 오류로 실패하면, 일반적으로 Elasticsearch가 인덱싱 요청의 동시성을 따라갈 수 없다는 의미입니다. 다음 설정을 변경하여 해결합니다:

• 인덱싱 처리량을 줄이려면 대량 요청 동시성을 줄일 수 있습니다(고급 검색 설정 참조). 기본값은 10이지만, 동시 인덱싱 작업 수를 줄이기 위해 1로 낮출 수 있습니다.
• 대량 요청 동시성 변경이 도움이 되지 않으면 라우팅 규칙 옵션을 사용하여 특정 Sidekiq 노드만으로 인덱싱 잡을 제한할 수 있으며, 이는 인덱싱 요청 수를 줄여야 합니다.

오류: Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge#

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

이 예외는 Elasticsearch 클러스터가 특정 크기(이 경우 10 MiB) 이상의 요청을 거부하도록 구성된 경우 발생합니다. 이는 elasticsearch.yml의 http.max_content_length 설정에 해당합니다. 더 큰 값으로 늘리고 Elasticsearch 클러스터를 재시작하세요.

AWS는 기본 인스턴스 크기에 따라 최대 HTTP 요청 페이로드 크기에 대한 네트워크 제한이 있습니다. 최대 대량 요청 크기를 10 MiB보다 낮은 값으로 설정하세요.

인덱싱이 매우 느리거나 rejected execution of coordinating operation으로 실패#

Elasticsearch 노드에서 거부되는 대량 요청은 부하와 사용 가능한 메모리 부족으로 인한 것일 가능성이 높습니다. Elasticsearch 클러스터가 시스템 요구 사항을 충족하고 대량 작업을 수행하기에 충분한 리소스가 있는지 확인합니다. "429 (Too Many Requests)" 오류도 참조하세요.

strict_dynamic_mapping_exception으로 인덱싱 실패#

주요 업그레이드 전에 모든 고급 검색 마이그레이션이 완료되지 않은 경우 인덱싱이 실패할 수 있습니다. 이 오류와 함께 대규모 Sidekiq 백로그가 발생할 수 있습니다. 인덱싱 실패를 해결하려면 데이터베이스, 저장소 및 위키를 다시 인덱싱해야 합니다.

1. Sidekiq이 따라잡을 수 있도록 인덱싱을 일시 중지합니다:

   sudo gitlab-rake gitlab:elastic:pause_indexing
   

2. 처음부터 인덱스를 다시 생성합니다.

3. 인덱싱을 재개합니다:

   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"

다시 인덱싱이 이 문제를 해결하지 못하고 인덱싱 프로세스를 수동으로 일시 중지하지 않은 경우, 두 개의 GitLab 인스턴스가 하나의 Elasticsearch 클러스터를 공유하기 때문에 이 오류가 발생할 수 있습니다.

이 오류를 해결하려면 Elasticsearch 클러스터를 사용하는 GitLab 인스턴스 중 하나를 연결 해제합니다.

자세한 내용은 이슈 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 클러스터에 디스크 공간이 심각하게 부족한 노드가 하나 이상 있을 때 발생합니다. 기본 워터마크 임계값인 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

인덱스를 다시 생성하는 최후의 수단 {#last-resort-to-recreate-an-index}#

데이터가 인덱싱되지 않고 큐에도 없거나, 마이그레이션을 진행할 수 없는 상태에 인덱스가 있는 경우가 있습니다. 로그를 보고 문제의 근본 원인을 해결하는 것이 항상 최선입니다.

최후의 수단으로, 처음부터 인덱스를 다시 생성할 수 있습니다. 소규모 GitLab 설치의 경우 인덱스를 다시 생성하면 일부 문제를 빠르게 해결할 수 있습니다. 그러나 대규모 GitLab 설치의 경우 이 방법은 매우 오래 걸릴 수 있습니다. 인덱싱이 완료될 때까지 인덱스에 올바른 검색 결과가 표시되지 않습니다. 인덱싱이 실행되는 동안 고급 검색으로 검색 확인란을 지울 수 있습니다.

이전 주의 사항을 읽고 진행하려는 경우 다음 Rake 작업을 실행하여 전체 인덱스를 처음부터 다시 생성합니다.

# 경고: 위의 설명을 읽기 전까지 이 명령을 실행하지 마세요
sudo gitlab-rake gitlab:elastic:index

# 경고: 위의 설명을 읽기 전까지 이 명령을 실행하지 마세요
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:index

데드 큐#

항목은 한 번 재시도한 후 실패하면 데드 큐에 들어갑니다. 데드 큐 항목은 수동 조사가 필요하며 자동으로 재시도되지 않습니다.

상태 확인#

데드 큐의 크기와 세부 사항을 확인하려면:

1. Rails 콘솔을 시작합니다:

   sudo gitlab-rails console
   

2. 실패한 항목 수를 확인합니다:

   Search::Elastic::DeadQueue.queue_size
   

3. 실패한 항목의 세부 사항을 검사합니다:

   Search::Elastic::DeadQueue.queued_items
   

   이 명령은 각 키가 샤드 번호이고 각 값이 [spec, score] 쌍의 배열인 해시를 반환합니다. 사양에는 실패한 항목에 대한 정보가 포함됩니다.

항목 재시도#

재시도할 항목을 큐에 넣습니다. 이 항목이 다시 실패하면 데드 큐로 다시 이동됩니다.

데드 큐의 항목을 재시도하려면:

1. Rails 콘솔을 시작합니다:

   sudo gitlab-rails console
   

2. 항목을 데드 큐에서 재시도 큐로 이동합니다:

   specs = Search::Elastic::DeadQueue.queued_items.flat_map { |_, items| items.map { |spec, _| spec } }
   
   Search::Elastic::DeadQueue.clear_tracking!
   Search::Elastic::RetryQueue.track!(*specs)
   

3. 선택 사항. 인덱싱 상태를 확인합니다.

재시도하지 않고 데드 큐의 항목을 삭제하려면 다음 명령을 실행합니다:

Search::Elastic::DeadQueue.clear_tracking!

GitLab 지원팀에 문의#

데드 큐 항목에 대한 도움이 필요한 경우 GitLab 지원팀에 다음 정보를 공유합니다:

• Search::Elastic::DeadQueue.queue_size의 출력
• Elasticsearch 및 GitLab 버전
• 인덱싱 실패가 시작된 시기
• 관련 애플리케이션 로그 또는 오류 메시지

Elasticsearch 성능 향상#

성능을 향상하려면 다음을 확인합니다:

• Elasticsearch 서버가 GitLab과 동일한 노드에서 실행되지 않아야 합니다.
• Elasticsearch 서버에 충분한 RAM과 CPU 코어가 있어야 합니다.
• 샤딩이 사용되고 있어야 합니다.

더 자세히 설명하면, Elasticsearch가 GitLab과 동일한 서버에서 실행되는 경우 리소스 경합이 매우 발생할 가능성이 높습니다. 이상적으로는 충분한 리소스가 필요한 Elasticsearch가 자체 서버에서 실행되어야 합니다(Logstash 및 Kibana와 함께 결합될 수도 있음).

Elasticsearch의 경우 RAM이 핵심 리소스입니다. Elasticsearch 자체에서 권장하는 사항:

• 비프로덕션 인스턴스의 경우 최소 8 GB RAM.
• 프로덕션 인스턴스의 경우 최소 16 GB RAM.
• 이상적으로는 64 GB RAM.

CPU의 경우 Elasticsearch는 최소 2개의 CPU 코어를 권장하지만, Elasticsearch에서는 일반적인 설정이 최대 8개 코어를 사용한다고 말합니다. 서버 사양에 대한 자세한 내용은 Elasticsearch 하드웨어 가이드를 참조하세요.

명백한 것 외에도 샤딩이 중요합니다. 샤딩은 Elasticsearch의 핵심 부분입니다. 대량의 데이터를 처리할 때 도움이 되는 인덱스의 수평 확장을 허용합니다.

GitLab이 인덱싱하는 방식으로 인해 엄청난 양의 문서가 인덱싱됩니다. 샤딩을 사용하면 각 샤드가 Lucene 인덱스이기 때문에 Elasticsearch가 데이터를 찾는 속도를 높일 수 있습니다.

샤딩을 사용하지 않으면 프로덕션 환경에서 Elasticsearch를 사용하기 시작할 때 문제가 발생할 가능성이 높습니다.

단일 샤드만 있는 인덱스는 확장 인수가 없으며 어느 정도의 빈도로 호출될 때 문제가 발생할 가능성이 있습니다. Elasticsearch 용량 계획 문서를 참조하세요.

샤딩이 사용 중인지 확인하는 가장 쉬운 방법은 Elasticsearch 상태 API의 출력을 확인하는 것입니다:

• 빨간색은 클러스터가 다운된 것입니다.
• 노란색은 샤딩/복제 없이 실행 중입니다.
• 초록색은 정상(실행 중, 샤딩, 복제 중)입니다.

프로덕션 사용의 경우 항상 초록색이어야 합니다.

이러한 단계 외에도 병합 및 캐싱과 같은 더 복잡한 사항을 확인해야 합니다. 이는 복잡해질 수 있고 학습하는 데 시간이 걸리므로, 더 깊이 파고들어야 한다면 Elasticsearch 전문가에게 에스컬레이션하거나 협력하는 것이 좋습니다.

GitLab 지원팀에 연락하세요. 하지만 이는 숙련된 Elasticsearch 관리자가 더 많은 경험을 가진 것일 가능성이 높습니다.

초기 인덱싱 느림#

GitLab 인스턴스에 더 많은 데이터가 있을수록 인덱싱에 더 오래 걸립니다. Rake 작업 sudo gitlab-rake gitlab:elastic:estimate_cluster_size로 클러스터 크기를 추정할 수 있습니다.

코드 문서의 경우#

코드, 커밋 및 위키를 효율적으로 인덱싱하기 위해 충분한 Sidekiq 노드와 프로세스가 있는지 확인합니다. 초기 인덱싱이 느리면 전용 Sidekiq 노드 또는 프로세스를 고려하세요.

비코드 문서의 경우#

초기 인덱싱이 느리지만 Sidekiq에 충분한 노드와 프로세스가 있는 경우, GitLab에서 고급 검색 워커 설정을 조정할 수 있습니다. 인덱싱 워커 재큐의 기본값은 false입니다. 비코드 인덱싱의 샤드 수의 기본값은 2입니다. 이 설정은 인덱싱을 분당 2000개 문서로 제한합니다.

사전 조건:

• 관리자 액세스.

워커 설정을 조정하려면:

1. 오른쪽 상단에서 관리자를 선택합니다.
2. 왼쪽 사이드바에서 설정 > 검색을 선택합니다.
3. 고급 검색을 확장합니다.
4. 인덱싱 워커 재큐 확인란을 선택합니다.
5. 비코드 인덱싱의 샤드 수 텍스트 상자에 2보다 높은 값을 입력합니다.
6. 변경 사항 저장을 선택합니다.