Elasticsearch 클러스터 문제 디버깅을 위한 필수 도구 및 기술

Elasticsearch 클러스터 문제는 일반적으로 red 또는 yellow 상태, 느린 검색, 쓰기 거부, 또는 노드가 클러스터에서 이탈하는 형태로 나타납니다. 가장 빠른 디버깅 방법은 클러스터 상태부터 시작하여 샤드, 노드, 할당 규칙, 로그 또는 리소스 압박으로 문제를 좁혀가는 것입니다.

이 가이드는 가장 자주 사용하게 될 내장 도구인 _cat API, _cluster/allocation/explain, 노드 통계, 대기 중인 작업 및 Elasticsearch 로그를 설명합니다.

Elasticsearch 클러스터 상태 이해

클러스터 상태는 첫 번째 신호를 제공합니다:

green: 모든 기본 및 복제 샤드가 할당되었습니다.
yellow: 모든 기본 샤드가 할당되었지만 하나 이상의 복제 샤드가 할당되지 않았습니다.
red: 하나 이상의 기본 샤드가 할당되지 않아 일부 데이터를 사용할 수 없습니다.

yellow 클러스터는 사용 가능한 기본 샤드에 대한 읽기 및 쓰기를 계속 제공할 수 있지만 중복성이 낮습니다. red 클러스터는 영향을 받은 기본 샤드를 사용할 수 없으므로 즉시 조사가 필요합니다.

`_cat` API로 시작하기

_cat API는 빠른 사람이 읽을 수 있는 확인을 위해 설계되었습니다.

curl -X GET "localhost:9200/_cat/health?v"
curl -X GET "localhost:9200/_cat/nodes?v&h=name,ip,heap.percent,ram.percent,cpu,disk.used_percent,load_1m,node.role"
curl -X GET "localhost:9200/_cat/shards?v"
curl -X GET "localhost:9200/_cat/indices?v"

_cat/health를 사용하여 전체 상태를 확인합니다. _cat/shards를 사용하여 UNASSIGNED, INITIALIZING 또는 반복적으로 재배치되는 샤드를 찾습니다. _cat/nodes를 사용하여 특정 노드의 힙, CPU 또는 디스크 압박을 확인합니다.

red 또는 yellow 클러스터의 경우 다음 명령이 집중된 보기를 제공합니다:

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

샤드 할당 설명

샤드가 할당되지 않은 경우 _cluster/allocation/explain은 Elasticsearch가 이를 배치할 수 없는 이유를 알려줍니다.

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

또한 Elasticsearch가 찾은 첫 번째 할당되지 않은 샤드를 설명하도록 요청할 수 있습니다:

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

can_allocate, allocate_explanation 및 node_allocation_decisions 필드를 읽습니다. 일반적인 원인으로는 디스크 워터마크, 할당 필터링, 누락된 노드, 호환되지 않는 인덱스 설정 또는 요청된 복제본 수에 비해 데이터 노드가 너무 적은 경우가 있습니다.

노드 및 클러스터 통계 확인

상태가 녹색이지만 검색 또는 쓰기가 느린 경우 리소스 압박을 확인합니다.

curl -X GET "localhost:9200/_nodes/stats/jvm,fs,os,process,thread_pool?pretty"
curl -X GET "localhost:9200/_cluster/stats?pretty"

높은 JVM 힙 사용량, 디스크 압박, 거부된 검색 또는 쓰기 작업, 그리고 동료보다 훨씬 높은 부하를 가진 노드를 찾습니다. 과부하된 단일 노드는 핫 샤드를 소유한 경우 전체 클러스터를 느리게 만들 수 있습니다.

스레드 풀 거부의 경우 다음을 사용합니다:

curl -X GET "localhost:9200/_cat/thread_pool/search,write?v&h=node_name,name,active,queue,rejected,completed"

거부된 작업은 일반적으로 노드가 요청 속도를 따라잡지 못했음을 의미합니다. 큐를 늘리기 전에 원인을 해결하세요: 쿼리 비용을 줄이고, 샤드를 분산시키고, 노드를 확장하거나, 대량 인덱싱 속도를 늦추세요.

대기 중인 작업 및 복구 검토

클러스터 상태 변경이 멈춘 것처럼 느껴지면 대기 중인 작업을 확인합니다:

curl -X GET "localhost:9200/_cluster/pending_tasks?pretty"

긴 큐는 마스터 노드 압박, 빈번한 매핑 업데이트, 샤드 변동 또는 불안정한 노드를 가리킬 수 있습니다.

샤드 이동 및 복구의 경우 다음을 사용합니다:

curl -X GET "localhost:9200/_cat/recovery?v&active_only=true"

이것은 활발히 복구 중인 클러스터와 할당 규칙이나 누락된 데이터로 인해 차단된 클러스터를 구분하는 데 도움이 됩니다.

Elasticsearch 로그 읽기

Elasticsearch 로그는 종종 API가 암시하는 것만을 설명합니다. 클러스터의 임의 노드가 아닌 영향을 받은 노드의 로그를 확인합니다.

다음과 같은 메시지를 검색합니다:

master not discovered
flood-stage disk watermark
circuit_breaking_exception
rejected execution
failed to obtain node locks
shard failed

예를 들어, 플러드 스테이지 디스크 워터마크는 디스크 압박이 해결될 때까지 영향을 받은 인덱스를 읽기 전용으로 설정하여 쓰기를 차단할 수 있습니다. 디스크를 확보하거나 용량을 추가한 후, 디스크가 가득 찬 이유를 이해한 후에만 쓰기 차단을 해제합니다:

curl -X PUT "localhost:9200/*/_settings?expand_wildcards=all" \
  -H 'Content-Type: application/json' -d'
{
  "index.blocks.read_only_allow_delete": null
}'

실용적인 디버깅 흐름

어디서부터 시작해야 할지 모를 때는 이 순서를 사용합니다:

_cat/health?v를 확인하여 문제가 클러스터 전체에 해당하는지 확인합니다.
_cat/shards?v를 사용하여 할당되지 않았거나, 재배치 중이거나, 핫 샤드를 찾습니다.
할당되지 않은 샤드에 대해 _cluster/allocation/explain을 실행합니다.
_cat/nodes에서 힙, CPU, 디스크 및 노드 역할을 확인합니다.
할당, 디스크, JVM 및 회로 차단기 메시지에 대한 노드 로그를 검토합니다.
지연 시간 또는 거부된 요청 문제인 경우 노드 통계 및 스레드 풀 통계를 사용합니다.

핵심 요점

Elasticsearch 디버깅은 광범위한 상태 확인에서 문제를 일으키는 정확한 샤드, 노드 또는 설정으로 이동할 때 가장 효과적입니다. _cat/health, _cat/shards 및 할당 설명으로 시작한 다음 로그와 노드 통계를 사용하여 설정을 변경하기 전에 근본 원인을 확인합니다.