Elasticsearch와 ELK 스택

Elasticsearch란

Elasticsearch는 Apache Lucene 검색 라이브러리를 여러 서버에 나눠 돌리는 분산 검색·분석 엔진이다. 스키마를 미리 정하지 않아도 되는 JSON 문서를 HTTP API로 넣고 꺼낸다.

세 가지 성격을 함께 가진다.

역인덱스·토큰화·BM25 같은 검색의 원리는 검색엔진의 원리: 역인덱스와 랭킹에, 매핑·분석기·Query DSL·집계 같은 검색 기능은 Elasticsearch 검색: 매핑·분석기·Query DSL에 있다. 이 노트는 Elasticsearch가 데이터를 어떻게 나누고 복제하고 운영하는지와 어디에 쓰는지를 다룬다.

구조

구성 요소

인덱스는 문서를 담는 논리적 이름이고, 실제 저장은 샤드 단위로 노드에 흩어진다. 문서가 어느 주 샤드로 갈지는 hash(_routing) % 주 샤드 수로 정한다. _routing의 기본값은 _id다. 이 식 때문에 주 샤드 수는 인덱스를 만들 때 정하면 바꿀 수 없다(바꾸려면 split·shrink API나 재색인).

flowchart TB
  cluster["클러스터"] --> index["인덱스 (RDB의 테이블에 해당)"]
  index --> p0["주 샤드 0"]
  index --> p1["주 샤드 1"]
  index --> more["..."]
  p0 -->|"복제 (서로 다른 노드에 둔다)"| r0["복제 샤드 0"]
  p1 -->|"복제 (서로 다른 노드에 둔다)"| r1["복제 샤드 1"]
  more --> lucene["샤드 하나 = Lucene 인덱스 하나"]
  lucene --> seg["세그먼트들 (불변 파일, 백그라운드에서 병합)"]

주 샤드와 복제 샤드

주 샤드 수는 데이터를 나누는 단위(쓰기·용량 확장)이고, 복제 샤드 수는 가용성과 읽기 확장 수단이다.

노드 역할

노드는 node.roles로 역할을 정한다. 작은 클러스터는 한 노드가 여러 역할을 겸하고, 커지면 나눈다.

모든 노드는 기본적으로 조정 노드(coordinating node) 역할도 한다. 요청을 받은 노드가 관련 샤드에 일을 나눠 주고(scatter), 결과를 합쳐(gather) 응답한다. 마스터 후보는 3개 이상(홀수) 둔다. 7.0부터 마스터 선출은 과반 투표 구성으로 자동 관리되므로, 네트워크가 갈라져도 과반을 가진 쪽만 마스터를 뽑아 두 마스터가 생기는 분할 뇌(split brain)를 막는다.

쓰기 경로와 세그먼트

flowchart TB
  req["색인 요청"] --> coord["조정 노드"] --> route["라우팅으로 주 샤드 결정"]
  route --> primary["주 샤드: 메모리 버퍼에 쓰고 트랜스로그(translog)에 기록"]
  primary -->|"같은 작업을 전달"| replicas["동기화된 복제본(in-sync copies)"]
  replicas -->|"모두 성공하면"| resp["응답"]
  primary --> refresh["refresh (기본 1초): 버퍼를 새 세그먼트로 만들어 검색에 보이게 한다"]
  primary --> flush["flush: 세그먼트를 디스크에 확정(Lucene commit)하고 트랜스로그를 비운다"]
  primary --> merge["merge: 작은 세그먼트를 백그라운드에서 큰 것으로 합친다"]

• 문서가 들어오면 메모리 버퍼에 모였다가 refresh(기본 1초)로 새 세그먼트가 되어 검색에 보인다. 그래서 「실시간」이 아니라 거의 실시간(near real-time)이다. refresh_interval을 따로 정하지 않은 인덱스는 30초 넘게 검색이 없으면 다음 검색 때까지 refresh를 미룬다.
• 트랜스로그는 refresh·flush 전의 변경을 장애에서 되살리는 로그다. 기본값(index.translog.durability: request)은 요청마다 fsync한 뒤 응답한다. DB의 WAL과 같은 역할이다.
• 세그먼트는 한 번 쓰면 바꾸지 않는다. 수정은 새 문서를 쓰고 옛 문서에 삭제 표시를 하는 방식이다. 쓰기를 순차 추가로 바꾸고 나중에 합치는 발상은 LSM 트리와 같다.
• 각 세그먼트의 용어 사전(term dictionary)은 정렬된 용어 목록이고, 그 앞에 접두사를 압축한 FST(유한 상태 변환기) 색인을 둬서 메모리에 올린 채 빠르게 찾는다.

복제와 일관성 모델

Elasticsearch는 주-백업(primary-backup) 복제다. 쓰기는 주 샤드가 먼저 처리하고, 마스터가 관리하는 「동기화된 사본 목록」의 모든 복제본에 보낸 뒤 응답한다. 응답하지 않는 복제본은 목록에서 빠지고 나중에 따라잡는다.

트랜잭션은 없다. 문서 하나의 쓰기만 원자적이고, 여러 문서·인덱스에 걸친 원자적 갱신이나 롤백은 없다. 대신 문서 단위 낙관적 동시성 제어를 한다. 모든 문서는 _seq_no와 _primary_term을 가지며, if_seq_no·if_primary_term을 붙여 쓰면 그사이 누가 바꿨을 때 409 Conflict로 실패한다. 원본 DB의 버전 번호를 그대로 쓰려면 version_type=external을 쓴다. 여러 저장소에 걸친 정합성은 원본 DB를 기준으로 CDC나 재색인으로 맞춘다(데이터 관리 패턴).

어디에 쓰나

주 데이터베이스로 쓰지 않는다. 트랜잭션이 없고, 색인이 거의 실시간이며, 매핑을 바꾸려면 재색인이 필요하다. 원본은 RDB 등에 두고 Elasticsearch에는 검색용 사본을 동기화하는 구성이 기본이다. 그래서 검색엔진의 색인은 캐시의 한 형태로 볼 수 있다(캐시 전략).

인덱스 관리

인덱스 설정과 템플릿

인덱스 하나는 설정(settings) 과 매핑(mappings) 을 가진다. 매핑은 필드 타입과 분석 방법이고(Elasticsearch 검색), 설정은 인덱스를 어떻게 저장·운영할지다.

로그처럼 인덱스가 계속 새로 생기면 매번 설정·매핑을 줄 수 없다. 인덱스 템플릿은 이름 패턴에 맞는 새 인덱스에 설정·매핑·별칭을 자동으로 입힌다.

PUT _component_template/logs-mappings
{ "template": { "mappings": { "properties": { "@timestamp": { "type": "date" }, "message": { "type": "text" } } } } }
 
PUT _index_template/logs
{
  "index_patterns": ["logs-app-*"],
  "data_stream": {},
  "composed_of": ["logs-mappings"],
  "priority": 200,
  "template": { "settings": { "number_of_shards": 1, "index.lifecycle.name": "logs-policy" } }
}

재사용 조각인 컴포넌트 템플릿을 조합해 조합형 인덱스 템플릿(_index_template)을 만든다. 여러 템플릿이 겹치면 priority가 높은 하나만 적용된다. 옛 _template API는 지원이 끝나 가는 방식이다. 템플릿은 인덱스가 만들어질 때만 적용되므로, 바꾼 템플릿은 다음 인덱스부터 반영된다.

시간 기반 인덱스와 롤오버

로그·지표·이벤트처럼 시간순으로 쌓이고 오래될수록 덜 읽는 데이터는 시간 단위로 인덱스를 나눈다(logs-2026.10.30).

• 오래된 데이터는 인덱스를 통째로 지운다. 문서를 하나씩 지우는 것보다 훨씬 싸다(아래 「데이터 삭제」).
• 최근 인덱스에만 쓰기가 몰리므로 그 인덱스만 좋은 하드웨어에 두고, 지난 인덱스는 읽기 전용으로 병합·압축한다.
• 검색은 와일드카드(logs-*)나 별칭으로 여러 인덱스를 함께 묻는다.

날짜로만 자르면 하루 양이 들쭉날쭉할 때 샤드 크기가 고르지 않다. 롤오버(rollover) 는 조건을 만족하면 쓰기 대상을 새 인덱스로 넘긴다.

데이터 스트림(data stream) 이 이 구조를 감싼다. 이름 하나(logs-app-default)로 쓰고 읽으면, 실제로는 숨은 백업 인덱스(.ds-logs-app-default-2026.10.30-000001)들이 롤오버로 이어진다. 데이터 스트림은 추가 전용이라 @timestamp 필드가 있어야 하고, 개별 문서 수정은 백업 인덱스를 직접 지정해서 한다.

ILM과 데이터 티어(Hot-Warm-Cold)

ILM(Index Lifecycle Management) 은 인덱스가 나이를 먹으며 거칠 단계와 단계마다 할 일을 정책으로 정해 자동으로 실행한다. 사람이 cron으로 지우고 옮기던 일을 대신한다.

Hot-Warm-Cold 아키텍처는 이 단계를 하드웨어로 나눈 구성이다. 노드에 data_hot(빠른 NVMe·많은 CPU), data_warm(큰 HDD·적은 CPU), data_cold·data_frozen(가장 싼 저장소) 역할을 주고, ILM이 단계를 옮길 때 인덱스의 _tier_preference를 바꿔 샤드를 해당 티어 노드로 자동 이동한다. 최신 데이터는 빠르게, 오래된 데이터는 싸게 둔다. 검색 가능한 스냅숏과 frozen 티어는 유료 구독 기능이다.

로그·이벤트 클러스터는 흔히 최근 N개월만 hot·warm 티어에 두고 그 이전은 스냅숏으로 내리거나 지운다. 검색 대상을 줄여 클러스터 크기를 일정하게 유지한다. 날짜별 인덱스는 SQL 엔진에서 하나의 테이블처럼 읽을 수도 있다. Trino의 Elasticsearch 커넥터는 인덱스를 테이블로 보여 주고, "page_views_*" 같은 와일드카드나 별칭으로 공통 접두사의 인덱스들을 한 번에 질의한다(모든 인덱스의 필드 매핑이 호환돼야 한다). 다른 저장소의 테이블과 조인하는 분석이 쉬워진다.

데이터 삭제

삭제 표시가 많은 읽기 전용 인덱스는 _forcemerge?only_expunge_deletes=true로 정리한다. 쓰기 중인 인덱스에 강제 병합하면 거대한 세그먼트가 생겨 이후 병합이 꼬이므로 하지 않는다. 실수로 지우는 것을 막으려면 action.destructive_requires_name(기본 true)으로 와일드카드 삭제를 막아 둔다.

재색인(Reindex)

매핑의 필드 타입, 분석기, 주 샤드 수는 기존 인덱스에서 바꿀 수 없으므로 새 인덱스를 만들어 데이터를 옮긴다.

POST _reindex?slices=auto&wait_for_completion=false
{ "source": { "index": "products-v1" }, "dest": { "index": "products-v2" } }

• 원본을 스냅숏 기준으로 묶음 단위로 읽어 대상에 색인한다. 설정·매핑은 복사하지 않으므로 대상 인덱스를 먼저 만든다. script로 옮기며 필드를 바꾸고, remote로 다른 클러스터에서 가져오고, 버전 업그레이드 때 옛 인덱스를 새 형식으로 다시 쓰는 데도 쓴다.
• 무중단 교체는 별칭(alias) 으로 한다. 앱은 products 별칭만 보고, 재색인이 끝나면 별칭을 v1에서 v2로 한 번에 바꾼다. 재색인 중 들어온 변경은 원본 DB 기준으로 다시 반영하거나 이중 쓰기를 둔다.
• 대량 재색인 동안 대상 인덱스는 refresh를 끄고 복제본을 0으로 두면 빠르다. 끝나면 되돌린다.

스냅숏과 복원

복제본은 노드 장애를 막을 뿐, 실수로 지운 인덱스나 클러스터 전체 손실은 막지 못한다. 유일하게 믿을 수 있는 백업은 스냅숏이다. 데이터 디렉터리를 파일 복사하는 백업은 일관성을 보장하지 않는다.

백업 전략은 SLM 정기 스냅숏 + 다른 리전·계정의 저장소 + 주기적인 복원 연습이다. 스냅숏은 같은 메이저나 직전 메이저 버전의 클러스터에만 복원된다.

확장과 튜닝

스케일 아웃

샤드 크기는 대략 10~50GB, 샤드당 문서 2억 개 미만이 권장 범위다. 샤드가 너무 작고 많으면 샤드마다 드는 메모리·클러스터 상태·검색 조정 비용이 커지고(over-sharding), 너무 크면 복구와 재배치가 오래 걸린다.

지연 시간과 처리량 튜닝

인덱스·문서 크기 줄이기

컨테이너로 운영하기

노드를 늘릴 때마다 설치·설정을 반복하는 문제는 이미지로 푼다.

• 설정 파일, 플러그인, 한국어 분석기와 사용자 사전을 이미지에 굽고 버전을 고정한다. 서버를 옮기거나 버전을 올릴 때마다 설치 문서를 다시 찾지 않는다. 한국어는 6.4부터 공식 분석기 nori가 있어 예전처럼 은전한닢(mecab-ko)을 빌드해 넣는 수고가 줄었다(Elasticsearch 검색).
• 컨테이너 안의 IP는 다른 노드가 닿을 수 없으므로 network.publish_host에 호스트 주소를 주고 9200(HTTP)·9300(노드 간) 포트를 연다. 데이터 디렉터리는 호스트 볼륨에 둔다.
• 노드 찾기는 7.0부터 discovery.seed_hosts(마스터 후보 목록)와 첫 기동 때만 쓰는 cluster.initial_master_nodes로 한다. 예전의 멀티캐스트·discovery.zen.* 설정은 없어졌다.
• 접근 제어는 예전에는 앞에 basic auth 프록시를 두었지만, 지금은 인증·TLS가 무료 기본 라이선스에 들어 있고 8.0부터 기본으로 켜진다(아래 「보안」).
• 한 번에 하나만 바꾼다. 컨테이너로 옮긴 뒤 로그 수집기가 31시간마다 접속에 실패하는 문제가 생겼는데, 원인은 컨테이너가 아니라 함께 올린 수집기 플러그인 버전이었다. 여러 변경을 섞으면 원인을 가릴 수 없다.

모니터링과 장애 진단

클러스터 상태와 지표

GET _cluster/health의 상태는 샤드 배치만 말해 준다.

복제본이 부족할 때: 노드가 하나뿐이면 복제 샤드를 같은 노드에 둘 수 없어 영원히 yellow다. 노드를 늘리거나 단일 노드 개발 환경이면 복제본을 0으로 둔다. 노드 장애 뒤의 yellow는 남은 노드에 복제본이 다시 만들어지면 green이 된다. 원인을 모르겠으면 _cluster/allocation/explain이 디스크 워터마크, 배치 규칙, 노드 속성 불일치 같은 이유를 알려 준다. 복제본이 0인데 노드를 잃으면 red가 되고 스냅숏에서 복원해야 한다.

green인데 검색이 느릴 때

green은 「모든 샤드가 어딘가에 있다」는 뜻일 뿐 성능과는 무관하다.

Bulk 색인 중 429

429 Too Many Requests(es_rejected_execution_exception)는 노드의 write 스레드 풀 대기열이 가득 차서 새 작업을 거절했다는 뜻이다. 일시적인 역압(backpressure) 신호이고, 클러스터가 고장 났다는 뜻은 아니다. 색인 압력(indexing pressure)의 메모리 한도를 넘어도 같은 응답이 온다.

Bulk 요청 크기는 문서 수보다 바이트로 잡는다. 수 MB~수십 MB에서 시작해 처리량이 더 늘지 않는 지점을 측정으로 찾는다. 너무 크면 메모리를 압박하고 하나의 실패가 큰 재시도가 된다.

디스크 워터마크

디스크 사용률이 기준을 넘으면 마스터가 샤드 배치와 쓰기를 제한한다.

• 큰 디스크에서는 비율 대신 남은 용량 상한(max_headroom, 기본 low 200GB·high 150GB·flood 100GB)이 적용돼 여유를 과하게 남기지 않는다.
• flood_stage 블록은 사용률이 high 아래로 내려가면 자동으로 풀린다. 그 전에 공간을 확보해야 한다. 오래된 인덱스 삭제, 복제본 축소, 노드 추가.
• 모든 노드가 high를 넘으면 옮길 곳이 없어 결국 쓰기가 멈춘다. 디스크 사용률 경보는 low 아래에서 울리게 둔다.

장애와 복구 전략

보안

8.0부터 보안이 기본으로 켜진다. 처음 시작할 때 TLS 인증서와 elastic 사용자 비밀번호를 자동으로 만들고, 노드 간·HTTP 통신을 TLS로 암호화한다. 기본 보안(인증, RBAC, TLS)은 무료 라이선스에 포함된다. 과거 X-Pack Security라 부르던 기능이다.

로그 수집기와 검색 API의 권한을 나누는 예: 수집기에는 쓰기만, 검색 API에는 읽기만 준다.

POST _security/role/log_writer
{ "indices": [ { "names": ["logs-*"], "privileges": ["create_doc", "auto_configure"] } ] }
 
POST _security/role/search_reader
{ "indices": [ { "names": ["products", "logs-app-*"], "privileges": ["read", "view_index_metadata"] } ] }

• 수집기는 create_doc(새 문서 추가만, 덮어쓰기·삭제 불가)과 데이터 스트림 자동 생성(auto_configure)만 받는다. 검색 API는 read만 받아 색인·삭제를 못 한다.
• 각 역할로 API 키를 발급해 서비스에 준다. 키는 만료 시간을 두고 개별로 폐기할 수 있어 사용자 비밀번호보다 관리가 쉽다. Elastic Agent는 Fleet이 출력 전용 API 키를 자동으로 발급한다.
• elastic 초사용자는 초기 설정에만 쓰고 서비스에 넘기지 않는다.

멀티테넌시

한 클러스터를 여러 고객(테넌트)이 나눠 쓰는 방법은 셋이다.

보통은 큰 고객은 전용 인덱스, 작은 고객 다수는 공유 인덱스로 섞는다. Kibana의 Spaces는 대시보드·저장 객체를 나누는 기능이고 데이터 격리 장치는 아니다.

버전 업그레이드

• 같은 메이저 안에서는 노드를 하나씩 내렸다 올리는 롤링 업그레이드로 무중단 업그레이드한다. 시작 전에 샤드 재배치를 잠시 끄고(cluster.routing.allocation.enable: primaries), 끝나면 켠다.
• 메이저 업그레이드는 직전 메이저의 마지막 마이너에서만 한다(8.x 마지막 마이너 → 9.x). Kibana의 업그레이드 도우미(Upgrade Assistant)가 사용 중단된 설정·API와, 너무 옛 버전에서 만들어 재색인이 필요한 인덱스를 알려 준다.
• 각 메이저는 직전 메이저에서 만든 인덱스까지만 읽는다. 더 오래된 인덱스는 업그레이드 전에 재색인한다.
• 업그레이드 전에 스냅숏을 찍는다. 업그레이드한 노드는 이전 버전으로 되돌릴 수 없다. 클라이언트 라이브러리, Kibana, Beats·Logstash의 호환 버전도 함께 맞춘다. 순서는 Elasticsearch를 먼저, Kibana를 그다음에 올린다.

ELK 스택: 로그 파이프라인

ELK는 Elasticsearch, Logstash, Kibana의 머리글자다. 수집기 Beats가 더해진 뒤로는 Elastic Stack이라고도 부른다.

flowchart LR
  beats["서버들의 Beats<br/>수집"] --> mq["(Kafka 등 메시지 큐)<br/>생산·소비 속도 분리"] --> ls["Logstash<br/>파싱·변환"] --> es["Elasticsearch<br/>색인·저장"] --> kb["Kibana<br/>검색·대시보드"]

• 로그 양이 많으면 Beats와 Logstash 사이에 메시지 큐를 끼워 생산자와 소비자를 분리한다. Logstash가 잠시 밀려도 로그를 잃지 않는다.
• 변환이 단순하면 Logstash 없이 Beats(또는 Elastic Agent)가 Elasticsearch로 바로 보내고, 파싱은 Elasticsearch의 수집 파이프라인에서 한다.
• Kibana는 Elasticsearch의 REST API를 부르는 웹 애플리케이션이다. 자체 저장소가 없고 대시보드·설정 같은 저장 객체도 Elasticsearch의 시스템 인덱스에 둔다. 연결은 kibana.yml의 elasticsearch.hosts와 서비스 계정 토큰으로 하고, 8.x에서는 등록 토큰(enrollment token)으로 TLS 신뢰와 인증을 한 번에 맞춘다. Kibana와 Elasticsearch는 같은 버전으로 맞춘다.

수집 파이프라인(Ingest Pipeline)

Elasticsearch 안에서 문서를 색인하기 직전에 변환하는 처리기(processor)의 연쇄다. ingest 역할 노드에서 돈다.

PUT _ingest/pipeline/nginx-logs
{
  "processors": [
    { "grok":   { "field": "message", "patterns": ["%{IP:client.ip} %{WORD:http.method} %{URIPATHPARAM:url.path} %{NUMBER:http.status:int}"] } },
    { "date":   { "field": "ts", "formats": ["ISO8601"], "target_field": "@timestamp" } },
    { "geoip":  { "field": "client.ip" } },
    { "remove": { "field": "ts" } }
  ],
  "on_failure": [ { "set": { "field": "error.message", "value": "{{ _ingest.on_failure_message }}" } } ]
}

• 대표 처리기: grok·dissect(문자열 파싱), date, rename·set·remove, convert, geoip, user_agent, enrich(다른 인덱스 값으로 보강), script.
• 색인 요청에 ?pipeline=이름을 붙이거나 인덱스 설정 index.default_pipeline으로 지정한다.
• Logstash와 비교하면 별도 서버가 필요 없지만, 변환 비용이 데이터 노드 CPU를 쓰므로 양이 많으면 전용 ingest 노드를 둔다. 여러 목적지로 보내거나 복잡한 상태 처리가 필요하면 Logstash가 맞다.

OpenSearch(+ OpenSearch Dashboards)도 같은 구조로 쓴다. 2021년 Elastic이 라이선스를 소스는 공개하지만 OSI 승인 오픈소스는 아닌 쪽(SSPL·Elastic License)으로 바꾸자 AWS가 갈라낸 포크이고, 2024년 9월부터 리눅스 재단 산하 OpenSearch Software Foundation이 관리한다. Elasticsearch도 2024년 8월 AGPL을 라이선스 선택지에 다시 넣어 오픈소스로 돌아왔다. 지표·트레이스까지 묶은 관측성(observability) 도구로는 Grafana 계열(Loki·Prometheus) 같은 대안도 흔하다.

정리

• Elasticsearch는 Lucene을 샤드 단위로 분산한 검색·분석 엔진이다. 주 샤드 수는 고정이고 복제본 수는 언제든 바꾼다.
• 세그먼트는 불변이고 refresh로 거의 실시간에 검색된다. 쓰기는 주 샤드 → 복제본 순으로 동기 전달되지만, 검색 가시성은 최종 일관성이고 트랜잭션은 없다.
• 시간순 데이터는 데이터 스트림·롤오버·ILM으로 hot → warm → cold → delete로 흘려보내고, 백업은 SLM 스냅숏으로 한다.
• green은 성능을 말해 주지 않는다. 스레드 풀 거절, 힙·GC, 슬로 로그, 디스크 워터마크를 본다. 429는 역압 신호이므로 백오프 재시도한다.
• 원본 저장소가 아니라 검색용 사본으로 둔다. ELK는 Beats(수집) → Logstash(변환) → Elasticsearch(색인) → Kibana(시각화)다.

관련 노트: Elasticsearch 검색: 매핑·분석기·Query DSL, 검색엔진의 원리: 역인덱스와 랭킹, 웹 검색 엔진, 웹 확장성의 구성 요소, 캐시 전략, 와이드 컬럼 데이터베이스, 데이터베이스 샤딩