Elasticsearch cat API 상세 정리

cat API는 엘라스틱서치의 현재 상태를 사람이 보기 편한 텍스트 형태로 조회할 수 있는 API

JSON 형식이 기본인 일반 REST API와 달리, 터미널 환경에서 직관적으로 상태를 파악하는 데 매우 유용하다.

cat은 'compact and aligned text'의 약자이며, 실제 운영 시 모니터링 용도로 자주 호출하게 된다

1. 주요 cat API 종류 및 용도

• health

  • 클러스터의 전반적인 상태를 빠르게 조회한다. 노드 수, 활동 중인 샤드 수, 복구 중인 샤드 수, 전체 복구율 등을 한 번에 알 수 있다.

  • 상태는 green(모든 샤드 잘 할당됨), yellow(모든 주 샤드 할당됨), red(하나 이상의 주 샤드 미할당)로 구분된다.

  • 전반적인 정보를 알 수 있어 제일 많이 호출하게 될 API

• indices

  • 인덱스의 종류와 상태를 조회한다.

  • 주 샤드와 복제본 샤드 수, 색인된 문서 수, 디스크 용량 등을 확인할 수 있어 용량을 많이 차지하거나 상태가 좋지 않은 인덱스를 찾는 데 사용한다.

• nodes

  • 각 노드의 상태를 조회한다.

  • 노드의 역할, 이름, IP, 힙 사용량, 평균 부하(load average) 등을 확인할 수 있어 노드 목록 및 자원 확인을 위해 자주 호출한다.

• shards

  • 샤드의 상태를 조회한다.

  • 샤드별 문서 수, 크기, 배치된 노드 등을 확인할 수 있다. 샤드 크기가 너무 커지면 성능이 저하되므로 이를 모니터링하거나 초기화 중인 샤드 목록을 파악할 때 유용하다.

• segments

  • 루씬 세그먼트의 상태를 조회한다.

• recovery

  • 진행 중이거나 완료된 샤드 복구 작업 정보를 조회한다.

  • 복구해야 할 파일 개수, 크기, 진행률, 소요 시간 등을 확인하여 작업 완료 예상 시간을 가늠할 때 사용한다.

• allocation

  • 샤드 할당과 관련된 정보를 조회한다.

  • 각 노드에 샤드가 얼마나 할당되었는지, 미할당된 샤드는 몇 개인지, 노드별 디스크 사용량은 얼마인지 확인할 수 있다.

• thread_pool

  • 각 노드의 스레드 풀 상태를 조회한다.

• master

  • 현재 마스터로 선출된 노드를 확인한다.

2. API 호출 예시 및 매개변수 활용

기본 호출과 v 매개변수

• GET _cat/health: 기본 상태 정보만 나열되어 각 숫자의 의미를 알기 어렵다.

• GET _cat/health?v: v 매개변수를 추가하면 각 칼럼의 제목(헤더)이 포함되어 가독성이 높아진다.

주요 공통 매개변수

• h: 지정한 칼럼만 표시한다. (예: GET _cat/health?h=status,active_shards_percent)

• s: 결과를 특정 칼럼 기준으로 정렬한다. (예: GET _cat/indices?s=store.size:desc - 용량이 큰 인덱스부터 정렬)

• help: 각 칼럼에 대한 상세 설명을 보여준다.

• format: 출력 형식을 지정한다. 기본은 text이지만, 모니터링 툴 등에서 파싱하기 좋게 json이나 yaml로 변경할 수 있다.