Spring Boot와 Elasticsearch로 로그 검색 구축

소개

로그는 시스템 상태와 문제 원인 파악의 핵심이다. Spring Boot와 Elasticsearch를 결합하면 대용량 로그를 빠르게 검색하고 애널리틱스를 수행할 수 있다. 이 글은 처음 접하는 개발자도 이해할 수 있도록 구성 요소, 설정 예시, 쿼리와 시각화까지 단계별로 설명한다. 주요 키워드는 spring boot elasticsearch logging, elk spring boot 로그 검색, elastic stack spring boot integration이다.

아키텍처 개요

기본적인 흐름은 다음과 같다. 애플리케이션에서 로그를 JSON 형태로 변환해 Logstash 또는 Filebeat로 전송하고, Elasticsearch에 색인한 뒤 Kibana로 시각화한다. 요구에 따라 Beats 대신 직접 Elasticsearch로 전송하거나 Kafka를 중간에 둘 수 있다.

핵심 컴포넌트

• Spring Boot 애플리케이션: 구조화된 로그 생성
• Logstash / Filebeat: 로그 수집 및 파싱
• Elasticsearch: 색인 및 검색 엔진
• Kibana: 대시보드와 시각화

Spring Boot 설정

Maven 의존성과 Logback 설정으로 JSON 로그를 만들면 ELK 스택과 자연스럽게 통합된다. 예를 들어 logstash-logback-encoder를 사용하면 로그를 JSON으로 직렬화해 전송할 수 있다.

Maven 의존성

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.3</version>
  </dependency>
</dependencies>

application.yml 예시

spring:
  profiles: default
  elasticsearch:
    rest:
      uris: http://localhost:9200
logging:
  level:
    root: INFO

Logback으로 JSON 로그 만들기

Logstash로 전송할 경우 TCP/UDP appender 또는 HTTP appender를 사용할 수 있다. 아래는 logstash-logback-encoder를 이용한 간단한 설정 예시이다.

<configuration>
  <appender name="LOGSTASH" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
    <destination>localhost:5000</destination>
    <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
      <providers>
        <timestamp/>
        <message/>
        <loggerName/>
        <logLevel/>
        <threadName/>
        <mdc/>
        <stackTrace/>
      </providers>
    </encoder>
  </appender>

  <root level="INFO">
    <appender-ref ref="LOGSTASH"/>
  </root>
</configuration>

Elasticsearch 매핑 및 색인 설계

로그는 대체로 타임스탬프, 레벨, 서비스명, 메시지, 메타데이터(MDC) 등을 포함한다. 적절한 매핑을 만들면 검색 성능과 애널리틱스 품질이 향상된다. 예를 들어 timestamp는 date 타입, level과 service는 keyword로 설정한다.

{
  "mappings": {
    "properties": {
      "@timestamp": { "type": "date" },
      "level": { "type": "keyword" },
      "service": { "type": "keyword" },
      "message": { "type": "text" },
      "host": { "type": "keyword" }
    }
  }
}

Spring에서 검색 쿼리 실행

애플리케이션에서 운영 중 빠른 검색이 필요하면 Elasticsearch REST 클라이언트를 사용한다. 간단한 예시는 최근 에러 로그를 시간 범위로 조회하는 방식이다.

import org.elasticsearch.client.RequestOptions;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.action.search.SearchRequest;
import org.elasticsearch.index.query.QueryBuilders;
import org.elasticsearch.search.builder.SearchSourceBuilder;

// RestHighLevelClient를 주입받아 사용
SearchRequest request = new SearchRequest("logs-*" /* 인덱스 패턴 */);
SearchSourceBuilder sourceBuilder = new SearchSourceBuilder();
sourceBuilder.query(QueryBuilders.boolQuery()
  .must(QueryBuilders.termQuery("level", "ERROR"))
  .filter(QueryBuilders.rangeQuery("@timestamp").gte("now-24h")));
request.source(sourceBuilder);
client.search(request, RequestOptions.DEFAULT);

Kibana로 시각화

Kibana에서 인덱스 패턴을 등록한 뒤 Discover로 로그를 탐색하고, Lens 또는 TSVB로 대시보드를 만든다. 흔히 사용하는 시각화는 에러 추이, 서비스별 요청 비율, 호스트별 에러 분포다.

운영 고려사항

• 인덱스 수명 주기 관리: ILM으로 보존 정책 설정
• 샤드와 복제 수 조정: 색인량과 검색량에 따라 튜닝
• 로그 샘플링: 과대 색인을 방지하기 위한 샘플링 전략
• 보안: 인증과 전송 암호화(HTTPS, TLS) 적용

성능 최적화 팁

구조화된 JSON 로그를 쓰면 검색이 빨라진다. 메시지를 full-text로 자주 검색하지 않으면 keyword 타입을 적극 활용한다. 또한 bulk API를 사용해 색인 처리량을 높이고, 색인 파이프라인에서 불필요한 필드 제거로 디스크 사용량을 줄일 수 있다.

정리

Spring Boot와 Elasticsearch를 이용한 로그 검색 및 애널리틱스는 아키텍처 설계와 색인 구조, 로그 포맷이 핵심이다. 위 설정과 흐름을 기준으로 시작하면 로그 수집, 검색, 시각화까지 실무에 적용 가능한 환경을 빠르게 구성할 수 있다. 이후 운영 데이터에 맞춰 ILM, 샤드 정책, 모니터링을 추가하면 안정성과 확장성을 확보할 수 있다.