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 Index Scopes를 참고합니다.

낮은 동시성으로 고급 검색을 활성화한 후 검색 결과가 없는 경우#

고급 검색을 활성화한 후 문서가 인덱싱되지 않고 코드를 검색할 수 없는 경우가 있을 수 있습니다. Sidekiq 로그에서 다음과 유사한 메시지가 표시될 수 있습니다.

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

이 문제를 해결하려면:

1. Rake 작업 gitlab-rake gitlab:elastic:info를 사용하여 Indexing queues의 상태를 확인합니다.
2. Concurrency limit code queue가 0이 아니면 Code indexing concurrency 값을 확인합니다. 값이 너무 낮으면 인덱싱 진행이 저해될 수 있습니다. 이 값을 늘리고 Rake 작업으로 진행 상황을 확인하는 것을 고려합니다.

Elasticsearch 서버를 전환한 후 검색 결과가 없는 경우#

데이터베이스, 리포지터리, 위키를 다시 인덱싱하려면 인스턴스를 인덱싱합니다.

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)를 초과하는 요청을 거부하도록 구성된 경우 발생합니다. 이는 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 클러스터를 공유하고 있어서 발생하는 문제일 수 있습니다.

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

자세한 내용은 issue 3421을 참고합니다.

too_many_clauses: maxClauseCount is set to 1024 오류로 검색이 실패하는 경우#

이 오류는 쿼리의 절(clause) 수가 indices.query.bool.max_clause_count 설정에 정의된 수보다 많을 때 발생합니다.

• Elasticsearch 7.17 이하에서는 기본값이 1024입니다.
• Elasticsearch 8.0에서는 기본값이 4096입니다.
• Elasticsearch 8.1 이상에서는 이 설정이 지원 중단되었으며 값이 동적으로 결정됩니다.

이 문제를 해결하려면 값을 늘리거나 Elasticsearch 8.1 이상으로 업그레이드합니다. 값을 늘리면 성능이 저하될 수 있습니다.

검색 결과가 여러 페이지에 걸쳐 중복되는 경우#

고급 검색을 사용할 때 여러 페이지에 걸친 검색 결과에 중복 항목이 포함될 수 있습니다. 중복이 나타나면 일부 일치 결과가 반환되지 않습니다.

GitLab은 Elasticsearch에서 반환된 고유한 일치 결과 수를 기준으로 결과 페이지를 구성합니다. 그러나 Elasticsearch가 결과를 정렬하는 방식으로 인해 같은 결과가 여러 페이지에 나타날 수 있습니다. 이 문제는 결과를 관련도순으로 정렬할 때 더 자주 발생합니다.

해결 방법으로 다음을 고려합니다.

• 결과 범위를 좁히는 더 구체적인 검색 쿼리
• 가능하면 다른 정렬 옵션

자세한 내용은 issue 416286을 참고합니다.

오류: 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

최후의 수단으로 인덱스 다시 생성#

데이터가 어떤 이유로든 인덱싱되지 않고 큐에도 없거나, 인덱스가 마이그레이션을 진행할 수 없는 상태에 있는 경우가 있을 수 있습니다. 항상 로그를 확인하여 문제의 근본 원인을 먼저 조사하는 것이 좋습니다.

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

앞의 주의 사항을 읽었고 계속 진행하려면, 다음 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

Dead queue#

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

상태 확인#

dead queue의 크기와 세부 정보를 확인하려면:

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

   sudo gitlab-rails console
   

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

   Search::Elastic::DeadQueue.queue_size
   

3. 실패한 항목의 세부 정보를 확인합니다.

   Search::Elastic::DeadQueue.queued_items
   

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

항목 재시도#

재시도하려는 항목을 큐에 넣습니다. 이 항목이 다시 실패하면 dead queue로 다시 이동합니다.

dead queue의 항목을 재시도하려면:

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

   sudo gitlab-rails console
   

2. dead queue의 항목을 retry queue로 이동합니다.

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

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

dead queue의 항목을 재시도하지 않고 삭제하려면 다음 명령을 실행합니다.

Search::Elastic::DeadQueue.clear_tracking!

GitLab 지원팀 문의#

dead queue 항목에 대해 도움이 필요하면 다음 정보를 GitLab 지원팀과 공유합니다.

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

Elasticsearch 성능 개선#

성능을 개선하려면 다음을 확인합니다.

• Elasticsearch 서버가 GitLab과 같은 노드에서 실행되고 있지 않은지
• Elasticsearch 서버에 충분한 RAM과 CPU 코어가 있는지
• 샤딩이 사용되고 있는지

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

Elasticsearch에서 핵심 리소스는 RAM입니다. Elasticsearch에서는 다음을 권장합니다.

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

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

기본적인 사항 외에도 샤딩이 중요한 역할을 합니다. 샤딩은 Elasticsearch의 핵심 부분입니다. 샤딩을 사용하면 인덱스를 수평으로 확장할 수 있으며, 이는 대량의 데이터를 다룰 때 유용합니다.

GitLab의 인덱싱 방식상 인덱싱되는 문서 수가 매우 많습니다. 샤딩을 사용하면 각 샤드가 하나의 Lucene 인덱스이므로 Elasticsearch가 데이터를 찾는 속도를 높일 수 있습니다.

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

샤드가 하나뿐인 인덱스는 확장 계수가 없으며 어느 정도 빈번하게 호출될 때 문제가 발생할 가능성이 높습니다. Elasticsearch의 용량 계획 문서를 참고합니다.

샤딩이 사용되고 있는지 확인하는 가장 쉬운 방법은 Elasticsearch Health API의 출력을 확인하는 것입니다.

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

프로덕션 환경에서는 항상 초록색이어야 합니다.

이 단계를 넘어서면 병합이나 캐싱 같은 좀 더 복잡한 사항을 확인해야 합니다. 이런 사항은 복잡해질 수 있고 익히는 데 시간이 걸리므로, 더 깊이 파고들어야 한다면 Elasticsearch 전문가와 협력하거나 에스컬레이션하는 것이 좋습니다.

GitLab 지원팀에 문의할 수 있지만, 이는 숙련된 Elasticsearch 관리자가 더 많은 경험을 가지고 있을 가능성이 높은 영역입니다.

느린 초기 인덱싱#

GitLab 인스턴스의 데이터가 많을수록 인덱싱에 걸리는 시간이 길어집니다. Rake 작업 sudo gitlab-rake gitlab:elastic:estimate_cluster_size로 클러스터 크기를 추정할 수 있습니다.

코드 문서의 경우#

코드, 커밋, 위키를 효율적으로 인덱싱할 수 있도록 충분한 Sidekiq 노드와 프로세스를 확보합니다. 초기 인덱싱이 느리다면 전용 Sidekiq 노드 또는 프로세스를 고려합니다.

비코드 문서의 경우#

초기 인덱싱이 느리지만 Sidekiq에 충분한 노드와 프로세스가 있다면, GitLab에서 고급 검색 워커 설정을 조정할 수 있습니다. Requeue indexing workers의 기본값은 false입니다. Number of shards for non-code indexing의 기본값은 2입니다. 이 설정은 인덱싱을 분당 2000개 문서로 제한합니다.

사전 요구 사항:

• 관리자 액세스 권한

워커 설정을 조정하려면:

1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Search를 선택합니다.
3. Advanced search를 확장합니다.
4. Requeue indexing workers 체크박스를 선택합니다.
5. Number of shards for non-code indexing 텍스트 상자에 2보다 큰 값을 입력합니다.
6. Save changes를 선택합니다.