개발하는 콩

Java - Grafana + K6 + Jaeger로 부하테스트 해보기

Cold Bean — Thu, 4 Sep 2025 15:04:08 +0900

개요

부하 테스트의 목적은 목표 부하에서 SLO(서비스 수준 목표)를 지키며 얼마나 안정적·효율적으로 운영할 수 있는지를 수치로 확인하고, 그 근거로 용량·설정·코드를 결정하는 데 있다.

사용 툴

K6: 부하 테스트 진행 (v1.2.3)
InfluxDB: 부하 테스트 결과 데이터 저장할 시계열 DB (v1.11)
Grafana: 부하테스트 결과를 대시보드 형태로 시각화 (v11.6.1)
Jaeger: 트레이스 시각화를 통해 병목 구간 판단

아키텍처 개요

개발자가 작성한 시나리오로 K6가 HTTP 트래픽을 생성하여 부하 발생
각 요청에 대한 메트릭 데이터를 InfluxDB에 저장
Grafana가 InfluxDB에 쿼리를 날려 실시간 대시보드 표시(p95, 에러율, RPS 등 주요 지표 시각화)
Jaeger는 Spirng Boot에서 발생한 스팬을 수집하여 Jaeger UI에 시각화

부하 테스트 준비

1. 툴 설치 및 연결

2. 테스트 시나리오 설정

부하 테스트는 정의된 시나리오가 있어야 결과가 재현·해석·의사결정이 가능하다.

간단하게 테스트 시나리오 종류와 예시 스크립트를 확인해보자

기본 부하 테스트

목적: 정상 응답 및 안정된 응답 시간 유지

export const options = {
  scenarios: {
    /* =========================
     * 기본 부하 테스트 (Steady-state)
     * - 일정 TPS로 5분 유지, 안정 구간 성능(SLI) 확인
     * - preAllocatedVUs ≈ rate × p95(sec) × 3 (대략치)
     * ========================= */
    basic_load: {
      executor: 'constant-arrival-rate',
      rate: 60,                  // 초당 60TPS
      timeUnit: '1s',
      duration: '5m',
      preAllocatedVUs: 40, 
      maxVUs: 120,
    },
  },
};

점진적 부하 증가 테스트

목적: 사용자 증가 시 시스템 대응 능력 확인

export let options = {
  scenarios: {
    // 점진적 부하 증가 테스트
    ramping_load: {
      executor: 'ramping-arrival-rate',
      timeUnit: '1s',   // 요청이 만들어지는 기본 단위
      startRate: '0',   // 시작 TPS
      preAllocatedVUs: 20,
      maxVUs: 200,
      stages: [
        // 워밍업 (20TPS): 낮은 TPS에서 시작해서 천천히 올림 - 예열 단계
        {duration: '30s', target: 20},
        // 램프업 (100TPS): 목표 TPS까지 점진적으로 증가시키면서 시스템 확장성 확인
        {duration: '2m', target: 100},
        // 소크 (100TPS): 일정 TPS를 유지하면서 시스템 안정성 확인
        {duration: '1m30s',target: 100},
        // 램프다운 (0TPS): 부하를 점진적으로 감소시켜 리소스 정리 과정 확인
        {duration: '1m', target: 0},
      ]
    },
  },
};

스트레스 테스트

목적: 시스템 최대 처리 한계 및 장애 점검

export const options = {
  scenarios: {
    /* =========================
     * 스트레스 테스트 (Stress)
     * - 목표를 서서히 초과하며 한계점/붕괴지점 탐색 → 회복 구간 확인
     * - 총 6분
     * ========================= */
    stress_test: {
      executor: 'ramping-arrival-rate',
      timeUnit: '1s',
      startRate: 0,
      preAllocatedVUs: 80,
      maxVUs: 400,
      stages: [
        { duration: '1m', target: 50 },   // 워밍업
        { duration: '1m', target: 150 },  // 정상 상한 근처
        { duration: '1m', target: 250 },  // 스트레스 시작
        { duration: '1m', target: 350 },  // 한계 넘김(붕괴 관찰)
        { duration: '1m', target: 200 },  // 완화
        { duration: '1m', target: 100 },  // 회복 관찰
      ],
    },
  },
};

스파이크 테스트

목적: 갑작스러운 트래픽 증가 시 시스템 안정성 확인

export const options = {
  scenarios: {
    /* =========================
     * 스파이크 테스트 (Spike)
     * - 짧은 시간 급증/급락에 대한 탄력성 확인
     * - keep-alive/TLS/풀/큐 즉시 대응 확인
     * - 총 ~2.5분
     * ========================= */
    spike_test: {
      executor: 'ramping-arrival-rate',
      timeUnit: '1s',
      startRate: 10,             // 베이스라인
      preAllocatedVUs: 60,
      maxVUs: 400,
      stages: [
        { duration: '30s', target: 10 },   // 안정 구간
        { duration: '10s', target: 250 },  // 급상승(스파이크)
        { duration: '20s', target: 10 },   // 급락
        { duration: '10s', target: 250 },  // 2차 스파이크
        { duration: '50s', target: 50 },   // 상향 안정화
        { duration: '30s', target: 0 },    // 램프다운
      ],
    },
  },
};

본 테스트에서는 점진적 부하 시나리오로 진행했고, 진행 순서는 다음과 같다.

워밍업 단계 (30초, 0 → 20TPS)
- 테스트 시작 시 요청 속도를 0에서 출발해 30초 동안 20TPS까지 올림.
- 목적: 갑작스러운 과부하를 주지 않고, 시스템/캐시/DB 커넥션 등을 예열(warm-up)하기 위함.
램프업 단계 (2분, 20TPS → 100TPS)
- 2분 동안 요청 속도를 점진적으로 100TPS까지 끌어올림.
- 목적: 서비스가 점차 늘어나는 트래픽에 맞춰 확장성(Scalability)을 잘 보장하는지 확인.
소크(Soak) 단계 (1분 30초, 100TPS 유지)
- 100TPS를 일정하게 유지하면서 시스템이 안정적으로 처리할 수 있는지 검증.
- 목적: 지속 부하 상황에서 지속 성능(throughput, latency, error율) 확인.
램프다운 단계 (1분, 100TPS → 0TPS)
- 1분 동안 점진적으로 요청 속도를 줄여 0TPS까지 내림.
- 목적: 트래픽 감소 시 리소스(스레드, 커넥션, 메모리)가 정상적으로 해제되는지, 리소스 정리(tear-down) 과정을 확인.

3. SLO 설정

SLO란 서비스의 성능과 안정성을 위한 내부적인 지표로 테스트 결과를 감으로 보지 않고, 정량 기준으로 성공/실패 여부를 판단하기 위해 필요하다. READ/WRITE API를 분리해서 설정하는 것이 좋다.

권장 SLO

READ: p95 ≤ 300ms , p99 ≤ 600ms, 1s 초과 비율 < 0.1%, 실패율 < 0.0.1%
WRITE: p95 ≤ 500ms, p99 ≤ 900ms, 1.5s 초과 비율 < 0.2%, 실패율 < 0.0.1%

  thresholds: {
    // 레이턴시
    'http_req_duration': [
      'p(95)<500',     // p95 ≤ 500ms
      'p(99)<900',     // p99 ≤ 900ms
      'rate<=0.002@1.5s', // 1.5s 초과 비율 < 0.2%
    ],
    // 실패율 (0.1% 미만)
    'http_req_failed': ['rate<0.001'],
  },

평가 기준: k6 지표(p95/p99, 에러율), InfluxDB/Grafana 대시보드, Jaeger 트레이스(병목 구간) 종합 판단

4. 대용량 데이터 적재

인덱스, 캐시, 버퍼 등 성능 변화 및 병목 구간 확인을 위해 10만~100만 건 데이터 적재
주요 테이블: transaction, member, card 등
데이터 생성: 프로시저 또는 Mockaroo 활용
예시: 사용자 10만 명, 카드 20만 개, 거래내역 50만 건

5. K6 스크립트 작성

자세한 내용은 K6 공식 문서 가 잘 작성되어 있기 때문에 읽어보자.

본 테스트에서는 점진적 부하 증가 시나리오로 테스트 진행했다.

import http from 'k6/http';
import exec from 'k6/execution';
import {group, check} from 'k6';
import {randomString} from '../js/k6-utils.js';

export let options = {
  scenarios: {
    // 점진적 부하 증가 테스트
    ramping_load: {
      executor: 'ramping-arrival-rate',
      timeUnit: '1s',   // 요청이 만들어지는 기본 단위
      startRate: '0',   // 시작 TPS
      preAllocatedVUs: 20,
      maxVUs: 200,
      stages: [
        // 워밍업 (20TPS): 낮은 TPS에서 시작해서 천천히 올림 - 예열 단계
        {duration: '30s', target: 20},
        // 램프업 (100TPS): 목표 TPS까지 점진적으로 증가시키면서 시스템 확장성 확인
        {duration: '2m', target: 100},
        // 소크 (100TPS): 일정 TPS를 유지하면서 시스템 안정성 확인
        {duration: '1m30s',target: 100},
        // 램프다운 (0TPS): 부하를 점진적으로 감소시켜 리소스 정리 과정 확인
        {duration: '1m', target: 0},
      ]
    },
  },
  thresholds: {
    // 읽기 요청 SLO
    'http_req_duration{endopoint:read}': [
      'p(95)<300',     // 95% 요청 처리 시간 ≤ 300ms
      'p(99)<600',     // 99% 요청 처리 시간 ≤ 600ms
      'rate<=0.002@1s', // 1s 초과 비율 < 0.2%
    ],
    // 쓰기 요청 SLO
    'http_req_duration{endpoint:write}': [
      'p(95)<500',     // 95% 요청 처리 시간 ≤ 500ms
      'p(99)<900',     // 99% 요청 처리 시간 ≤ 900ms
      'rate<=0.002@1.5s', // 1.5s 초과 비율 < 0.2%
    ],
    http_req_failed: ['rate<0.001']  // 실패율 < 0.1%
  },
  tags: {
    testId: '${serverName}-${testId}',
    endpoint: 'write'  // 읽기 API 테스트: 'read', 쓰기 API 테스트: 'write'
  }
}

/**
 * 부하 테스트가 실행되기 전에 한 번 실행되는 function.
 * 테스트에 필요한 데이터를 생성하거나 외부에서 불러와 전달 가능
 */
const BASE_URL = 'http://localhost:8080';
export function setup() {
  // 부하테스트에 사용할 JWT 토큰 발급
  const url = BASE_URL + '/oauth/token';
  const basicAuth = 'Basic {yourAuthValue}';
  
  const params = {
    headers: {
      'Authorization': basicAuth,
    }
  }

  const response = http.post(url, null, params);
  const token = response.json('data.accessToken');

  return token;  // setup function의 리턴 값은 default 함수에서 인자로 받음
}

/**
 * 테스트 시나리오에 맞춰 반복적으로 실행되는 function
 */
export default function (token) {
  // 카드 발급 API 부하테스트
  const url = BASE_URL + '/your/api';
  const payload = JSON.stringify({
    cardNo: randomString(16, '0123456789'),
    trafficCardNo: randomString(16, '0123456789'),
    validDt: '3512',
  });

  const response = http.post(url, payload, params);
  
  check(response, {'status was 200': (r) => r.status === 200});  // 응답 status가 200인지 체크
}

/**
 * 부하 테스트가 실행된 후에 한 번 실행되는 function.
 */
export function teardown(data) {}

부하 테스트 진행

1. K6 스크립트 실행

$ ./k6 run --out influxdb=http://localhost:15086/k6 scripts/script.js

2. 실시간 Dashboard 확인

주요 지표에 대한 설명은 다음과 같다.

http_req_duration: 전체 HTTP 요청 소요 시간 (ms)
http_req_blocked: 네트워크 스택 대기 시간(CPU, OS 포함)
http_req_connecting: TCP 연결 설정 시간
http_req_tls_handshaking: TLS hand shake 시간
http_req_sending: 요청 데이터 전송 시간
http_req_wating: 서버 응답 대기 시간 (서버 처릭 시간)
http_req_receiving: 서버 응답 데잉터 수신 시간

3. Jaeger를 통해 문제되는 요청에 대한 트레이스 확인

개선하기

문제 상황

점진적 부하 테스트를 수행하던 중 특정 구간에서 요청 처리 시간이 급격히 증가하는 것을 확인할 수 있다.

원인 분석

Jaeger를 통해 문제되는 구간의 요청 Trace를 분석했다.
여러 요청에서 스팬과 스팬 사이의 공백 구간이 길게 관찰되는 것을 볼 수 있다.
이는 애플리케이션 내부 로직 지연보다는 리소스 확보 대기 시간이 길어지고 있음을 의미한다.

가설 설정

트래픽이 증가하는 과정에서 커넥션 풀 사이즈가 부하 테스트 트래픽을 감당하지 못해 대기 시간이 증가했다고 판단했다.

해결 시도

HikariCP 공식 Wiki를 참고하여 maximumPoolSize 값을 조정

pool size = Tn x (Cm - 1) + 1

Tn: 전체 Thread 갯수
Cm: 하나의 Task에서 동시에 필요한 Connection 수

pool size = 200 x (2 - 1) + 1 = 201

spring: 
   datasource: 
      hikari: 
         maximum-pool-size: 201 # 10 -> 201 변경

결과

동일한 조건에서 다시 부하 테스트 진행했다.
지표 상 요청 처리 시간이 안정화되고, Trace 상 스팬 간 공백 구간이 크게 줄어든 것을 확인할 수 있다.

참조

https://grafana.com/docs/grafana/latest/getting-started/

Get started with Grafana Open Source | Grafana documentation

Getting started with managing your metrics, logs, and traces using Grafana In this webinar, we’ll demo how to get started using the LGTM Stack: Loki for logs, Grafana for visualization, Tempo for traces, and Mimir for metrics.

grafana.com

https://docs.influxdata.com/influxdb/v2/get-started/

Get started with InfluxDB | InfluxDB OSS v2 Documentation

Thank you for your feedback! Let us know what we can do better:

docs.influxdata.com

Querydsl - Cannot invoke "com.querydsl.core.types.Expressions.accept(com.querydsl.core.types.Visitor, Object)" because "arg" is null" 원인과 해결 방법

Cold Bean — Mon, 28 Jul 2025 15:56:32 +0900

Cannot invoke "com.querydsl.core.types.Expressions.accept(com.querydsl.core.types.Visitor, Object)" because "arg" is null

Querydsl에서 @QueryProjection을 사용해 DTO를 조회하는 과정에서 발생한 예외이다.

원인

Querydsl에서 DTO를 @QueryProjection으로 조회할 때, select 절에 일부 필드를 null로 반환하고자 직접 null을 명시하면 아래와 같은 예외가 발생할 수 있다.

예외가 발생한 코드는 아래와 같다.

import com.querydsl.core.types.dsl.Expressions;
import com.querydsl.core.types.Projections;

QMember member = QMember.member;

List<MemberDto> results = queryFactory.select(Projections.constructor(MemberDto.class, 
        member.id,
        null, // 에러 원인
        member.email))
    .from(member)
    .fetch();

해결 방법

null 대신 Querydsl에서 제공하는 Expressions.nullExpression(필드타입.class)을 사용해 null 값을 표현해야 한다. 타입을 명확히 지정해서 빈 값을 만들어주는 셈이다.

import com.querydsl.core.types.dsl.Expressions;
import com.querydsl.core.types.Projections;

QMember member = QMember.member;

List<MemberDto> results = queryFactory.select(Projections.constructor(MemberDto.class, 
        member.id,
        Expressions.nullExpression(String.class),  // null 대체
        member.email))
    .from(member)
    .fetch();

Spring - ContentCachingRequestWrapper에서 getContentAsByteArray가 빈 값을 반환하는 이유와 해결 방법

Cold Bean — Thu, 17 Jul 2025 17:03:17 +0900

배경

실제 프로젝트에서 Request Body로부터 traceId를 전달받아 이를 저장하고, 이후 로깅이나 트레이싱 등에 활용해야 하는 요구사항이 있었다. 이를 위해 Spring에서 제공하는 ContentCachingRequestWrapper를 사용하기로 했다.

ContentCachingRequestWrapper는 원래 InputStream, Reader, 혹은 @RequestBody로 Request Body를 한번 읽고 나면 다시 읽을 수 없다는 한계를 깔끔하게 해결해 주는 유용한 클래스이다. 덕분에 traceId 같은 중요한 데이터를 여러 계층에서 반복적으로 로깅하거나 재사용할 수 있다.

그런데 실제로 적용하는 과정에서, ContentCachingRequestWrapper로 감쌌음에도 불구하고 Request Body에서 null이나 빈 값이 반환되는 현상을 경험하게 됐다. 이번 글에서는 이 트러블슈팅 경험과 원인, 그리고 실질적인 해결 방법을 정리해 공유한다.

코드는 아래 링크에서 확인할 수 있다.

practice-java-spring/spring-data-envers at c9d7609aa09d546408c531ede48434ca5dfb27f9 · chanbinme/practice-java-spring

Contribute to chanbinme/practice-java-spring development by creating an account on GitHub.

github.com

개발 환경

Java 17
Spring Boot 3.4.x
Gradle
IntelliJ

코드

RequestCachingFilter

한 번만 읽을 수 있는 Request를 ContentCachingRequestWrapper로 감싸 여러 번 읽을 수 있도록 하는 Filter이다. 반드시 filterChain.doFilter()에 Wrapper로 감싼 request를 전달해야 이후 계층(Filter, Controller, ExceptionHandler 등)에서 Body에 접근할 수 있다.

/**
 * 요청을 ContentCachingRequestWrapper로 래핑하여 요청 본문을 캐싱하는 필터.
 * 이 필터는 요청 본문을 읽을 수 있도록 하여, 이후의 필터나 컨트롤러에서 요청 본문에 접근할 수 있게 한다.
 */
@Component
@Order(1)
public class RequescCachingFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        ContentCachingRequestWrapper wrappedRequest = new ContentCachingRequestWrapper(request);
        filterChain.doFilter(wrappedRequest, response);
    }
}

TraceIdFilter

request를 ContentCachingRequestWrapper로 cast해서 body에 있는 traceId를 조회하는 Filter이다.

/**
 * 요청 본문에서 traceId를 추출하는 필터.
 * 이 필터는 ContentCachingRequestWrapper를 사용하여 요청 본문을 읽고, traceId를 추출하여 로그에 출력한다.
 */
@Component
@Order(2)
public class TraceIdFilter extends OncePerRequestFilter {

    private static final String TRACE_ID_FIELD = "traceId";

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        if (request instanceof ContentCachingRequestWrapper cachingRequest) {
            // 요청의 ContentCachingRequestWrapper를 사용하여 요청 본문을 읽을 수 있다.
            String requestBody = new String(cachingRequest.getContentAsByteArray(), cachingRequest.getCharacterEncoding());

            // 요청 본문에서 traceId를 추출한다.
            String traceId = extractTraceId(requestBody);

            // traceId를 로그에 출력하거나 다른 용도로 사용할 수 있습니다.
            System.out.println("############### Trace ID Filter Start ###############");
            System.out.println("Trace ID: " + traceId);
            System.out.println("############### Trace ID Filter End ###############");
        }

        filterChain.doFilter(request, response);
    }

    private String extractTraceId(String requestBody) throws JsonProcessingException {
        JsonNode node = objectMapper.readTree(requestBody);
        if (node.has(TRACE_ID_FIELD)) {
            return node.get(TRACE_ID_FIELD).asText();
        }
        return null;
    }
}

문제

이렇게 구현한 후 실제로 traceId를 로그에 찍어보았지만, null 값이 출력됐다.

############### Trace ID Filter Start ###############
Trace ID: null
############### Trace ID Filter End ###############

Request Body 자체가 아예 오지 않는 건 아닌지 의심했지만, CommonsRequestLoggingFilter의 로그를 보면 정상적으로 Body 값이 들어가는 것을 확인할 수 있었다.

2025-07-17T23:13:34.261+09:00 DEBUG 23020 --- [nio-8080-exec-1] o.s.w.f.CommonsRequestLoggingFilter      : Request Data: POST /posts, payload={
    "traceId": "00001",
    "title": "배고픈데",
    "content": "뭐먹지"
}]

왜 조회되지 않는지 원인과 해결 방법을 알아보자

원인

결국 문제의 원인은 ContentCachingRequestWrapper의 동작 원리를 완전히 이해하지 못한 것에 있었다.

공식 주석을 보면 다음과 같다.

입력 스트림과 리더(reader)로부터 읽은 모든 내용을 캐시하고, 이 내용을 바이트 배열을 통해 가져올 수 있게 해주는 HttpServletRequest 래퍼입니다. 이 클래스는 실제로 내용이 읽힐 때만 그 내용을 캐시 하는 인터셉터 역할을 하며, 그렇지 않은 경우에는 내용을 강제로 읽지 않습니다. 즉, 요청의 내용이 소비되지 않으면 캐시도 되지 않으므로, getContentAsByteArray()를 통해 내용을 가져올 수 없습니다.

즉, ContentCachingRequestWrapper로 감싸더라도, 요청 Body가 실제로 한 번이라도 InputStream (또는 Reader, @RequestBody 등)으로 읽혀야 캐시가 생긴다는 것이.

해결 방법

정리하자면, 개발자가 getInputStream()이나 getReader()로 Request Body를 수동으로 읽지 않는 이상, 그리고 컨트롤러의 @RequestBody가 호출되지 않은 상태라면, ContentCachingRequestWrapper 내부 캐시는 비어 있게 된다.

그래서 Body를 제대로 얻으려면 @RequestBody 등에서 본문을 읽은 시점 이후의 계층(예: 인터셉터의 postHandle, afterCompletion같은)에서 getContentAsByteArray()를 사용해야 한다. 보통 Filter는 DispatcherServlet보다 먼저 실행되므로, Filter에서는 Body가 아직 읽히지 않은 상태이기 때문에 getContentAsByteArray()가 빈 배열을 반환하는 것이다.

생각만 하면 의미가 없기 때문에 실제로 그런지 테스트해보자

테스트

TraceIdInterceptor

아래 interceptor에서 각 메서드별로 wrapper 감싸진 request에서 traceId를 조회하도록 했다.

/**
 * 요청에서 traceId를 추출하는 인터셉터.
 * ContentCachingRequestWrapper로 감싼다고 해서 body를 읽을 수 있는 것은 아니다.
 * body가 한 번도 읽히지 않았다면, getContentAsByteArray()는 빈 배열을 반환한다.
 * 일반적으로 body가 읽히는 시점은 @RequestBody가 있는 컨트롤러 메소드가 호출될 때이다.
 */
@Component
@RequiredArgsConstructor
public class TraceIdInterceptor implements HandlerInterceptor {

    private static final String TRACE_ID_FIELD = "traceId";

    private final ObjectMapper objectMapper;

    /**
     * 요청이 컨트롤러에 도달하기 전에 호출되는 메소드.
     * 아직 @RequestBoyd를 호출하지 않았기 때문에 ContentCachingRequestWrapper를 사용하여 요청 본문을 읽을 수 없다.
     */
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        if (request instanceof ContentCachingRequestWrapper cachingRequest) {
            // 요청의 ContentCachingRequestWrapper를 사용하여 요청 본문을 읽을 수 있다.
            String requestBody = new String(cachingRequest.getContentAsByteArray(), cachingRequest.getCharacterEncoding());

            // 요청 본문에서 traceId를 추출한다.
            String traceId = extractTraceId(requestBody);

            // traceId를 로그에 출력하거나 다른 용도로 사용할 수 있습니다.
            System.out.println("############### Trace ID Interceptor.preHandle Start ###############");
            System.out.println("Trace ID: " + traceId);
            System.out.println("############### Trace ID Interceptor.preHandle End ###############");
        }

        return true;
    }

    /**
     * 컨트롤러 메소드가 호출된 후에 호출되는 메소드.
     * 이 시점에서는 @RequestBody가 호출되어 ContentCachingRequestWrapper가 요청 본문을 캐싱했기 때문에, 본문을 읽을 수 있다.
     * 하지만 예외가 발생하면 이 메소드는 호출되지 않는다.
     */
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        if (request instanceof ContentCachingRequestWrapper cachingRequest) {
            // 요청의 ContentCachingRequestWrapper를 사용하여 요청 본문을 읽을 수 있다.
            String requestBody = new String(cachingRequest.getContentAsByteArray(), cachingRequest.getCharacterEncoding());

            // 요청 본문에서 traceId를 추출한다.
            String traceId = extractTraceId(requestBody);

            // traceId를 로그에 출력하거나 다른 용도로 사용할 수 있습니다.
            System.out.println("############### Trace ID Interceptor.postHandle Start ###############");
            System.out.println("Trace ID: " + traceId);
            System.out.println("############### Trace ID Interceptor.postHandle End ###############");
        }
    }

    /**
     * 컨트롤러 메소드가 호출된 후에 호출되는 메소드.
     * 이 시점에서는 @RequestBody가 호출되어 ContentCachingRequestWrapper가 요청 본문을 캐싱했기 때문에, 본문을 읽을 수 있다.
     * afterCompletion 메소드는 요청 처리 후에 항상 호출되며, 예외가 발생하더라도 호출된다.
     */
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        if (request instanceof ContentCachingRequestWrapper cachingRequest) {
            // 요청의 ContentCachingRequestWrapper를 사용하여 요청 본문을 읽을 수 있다.
            String requestBody = new String(cachingRequest.getContentAsByteArray(), cachingRequest.getCharacterEncoding());

            // 요청 본문에서 traceId를 추출한다.
            String traceId = extractTraceId(requestBody);

            // traceId를 로그에 출력하거나 다른 용도로 사용할 수 있습니다.
            System.out.println("############### Trace ID Interceptor.afterCompletion Start ###############");
            System.out.println("Trace ID: " + traceId);
            System.out.println("############### Trace ID Interceptor.afterCompletion End ###############");
        }
    }

    private String extractTraceId(String requestBody) throws JsonProcessingException {
        JsonNode node = objectMapper.readTree(requestBody);
        if (node.has(TRACE_ID_FIELD)) {
            return node.get(TRACE_ID_FIELD).asText();
        }
        return null;
    }
}

@Configuration
@EnableWebMvc
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {

    private final ObjectMapper objectMapper;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new TraceIdInterceptor(objectMapper))
                .addPathPatterns("/**") // 모든 경로에 대해 인터셉터 적용
                .excludePathPatterns("/error"); // 에러 페이지는 제외
    }
}

Controller

@RestController
@RequestMapping("/posts")
@RequiredArgsConstructor
public class PostController {

    private final PostService postService;

    @PostMapping
    public void createPost(@RequestBody PostCreateRequestDto postCreateRequestDto) {
    }
}

############### Trace ID Interceptor.preHandle Start ###############
Trace ID: null
############### Trace ID Interceptor.preHandle End ###############

############### Trace ID Interceptor.postHandle Start ###############
Trace ID: 00001
############### Trace ID Interceptor.postHandle End ###############

############### Trace ID Interceptor.afterCompletion Start ###############
Trace ID: 00001
############### Trace ID Interceptor.afterCompletion End ###############

예상한 대로 postHandler, afterCompletion에서 조회되는 걸 볼 수 있다.

예외가 발생했을 때는 어떻게 될까?

@RestController
@RequestMapping("/posts")
@RequiredArgsConstructor
public class PostController {

    private final PostService postService;

    @PostMapping
    public void createPost(@RequestBody PostCreateRequestDto postCreateRequestDto) {
        throw new Exception("test");    // 예외 발생
    }
}

############### Trace ID Filter Start ###############
Trace ID: null
############### Trace ID Filter End ###############

############### Trace ID Interceptor.preHandle Start ###############
Trace ID: null
############### Trace ID Interceptor.preHandle End ###############

############### Trace ID Interceptor.afterCompletion Start ###############
Trace ID: 00001
############### Trace ID Interceptor.afterCompletion End ###############

afterCompletion()에서만 호출되는 걸 확인할 수 있다.

이 외에도 Filter에서 filterChain.doFilter()를 호출한 이후에 Request를 조회하면 요청이 완료된 이후 DispatcherServlet - WAS 후처리를 담당하기 때문에 조회할 수 있다.

@Component
public class TraceIdFilter extends OncePerRequestFilter {

    private static final String TRACE_ID_FIELD = "traceId";

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        if (request instanceof ContentCachingRequestWrapper cachingRequest) {
            String requestBody = new String(cachingRequest.getContentAsByteArray(), cachingRequest.getCharacterEncoding());

            String traceId = extractTraceId(requestBody);

            System.out.println("############### Trace ID Filter.doFilter before Start ###############");
            System.out.println("Trace ID: " + traceId);
            System.out.println("############### Trace ID Filter.doFilter before End ###############");
        }

        try {
            filterChain.doFilter(request, response);
        } finally {
            if (request instanceof ContentCachingRequestWrapper cachingRequest) {
                String requestBody = new String(cachingRequest.getContentAsByteArray(), cachingRequest.getCharacterEncoding());

                String traceId = extractTraceId(requestBody);

                System.out.println("############### Trace ID Filter.doFilter after Start ###############");
                System.out.println("Trace ID: " + traceId);
                System.out.println("############### Trace ID Filter.doFilter after End ###############");
            }
        }
    }

    private String extractTraceId(String requestBody) throws JsonProcessingException {
        JsonNode node = objectMapper.readTree(requestBody);
        if (node.has(TRACE_ID_FIELD)) {
            return node.get(TRACE_ID_FIELD).asText();
        }
        return null;
    }
}

############### Trace ID Filter.doFilter before Start ###############
Trace ID: null
############### Trace ID Filter.doFilter before End ###############

############### Trace ID Filter.doFilter after Start ###############
Trace ID: 00001
############### Trace ID Filter.doFilter after End ###############

정리하면 다음과 같다.

위치	Body 조회 가능 여부	설명
Filter 내부(doFilter)	X (body 미소비)	Controller에서 @RequestBody가 호출되기 전
Controller(@RequestBody)	O (body 읽음)	실제로 Body가 소비됨, Wrapper에 캐시가 생김
Interceptor preHandle	X	@RequestBody 호출 전이므로 캐시 없음
Interceptor postHandle	O	@RequestBody 이후이므로 캐시로 본문 획득 가능
Interceptor afterCompletion	O	항상 호출됨, 예외 상황 포함
Filter(doFilter 이후)	O	요청 후에는 DispatcherServlet을 지나 Body 캐싱 완료

마무리

ContentCachingRequestWrapper 사용 시 주의할 점은 Request Body가 실제로 한 번이라도 읽혀야 캐싱이 이루어진다는 점이다. Filter 등 DispatcherServlet 이전에는 Body를 바로 읽을 수 없으니, 반드시 적절한 위치(컨트롤러 @RequestBody 이후, Interceptor의 postHandle/afterCompletion 등)에서 본문을 조회해야 원하는 데이터를 얻을 수 있다.

이 점만 명확히 알고 있으면, 실무에서 불필요하게 디버깅에 시간을 낭비하지 않을 수 있으니, 꼭 기억해 두자! (필자는 오늘 이거 때문에 꽤 많은 시간을 소비했다.. ㅎㅎ)

참조

https://docs.spring.io/spring-framework/docs/4.2.3.RELEASE_to_4.2.4.RELEASE/Spring%20Framework%204.2.4.RELEASE/org/springframework/web/util/ContentCachingRequestWrapper.html

ContentCachingRequestWrapper

docs.spring.io

https://stackoverflow.com/questions/79441441/spring-boot-3-4-2-contentcachingrequestwrapper-returns-an-exhausted-inputstream

Spring - 딸깍으로 쉽게 Request 로그 남기기(CommonsRequestLoggingFilter)

Cold Bean — Wed, 16 Jul 2025 17:07:24 +0900

배경

애플리케이션을 운영하다 보면, 클라이언트의 요청이 어떻게 들어오는지, 어떤 데이터가 전달되는지 로그를 남겨둬야 할 때가 있다. 특히, 복잡한 API를 개발하거나, 에러 대응 및 디버깅이 필요할 때 요청 정보를 간단하게 로깅할 수 있다면 작업 효율이 크게 올라갈 것이다.

현재 진행중인 프로젝트에서 Request에 대한 로깅이 필요했고, Spring에서 제공하는 CommonsRequestLoggingFilter라는 도구를 알게되었다. 복잡한 설정 없이 손쉽게 Request 정보를 로깅할 수 있다는 장점이 있다. 이 글에서는 CommonsRequestLoggingFilter를 이용해 딸깍 한 번으로 쉽게 Request 요청을 로그로 남길 수 있는지 공유하려고 한다.

코드는 아래 링크에서 확인할 수 있다.

practice-java-spring/spring-data-envers at master · chanbinme/practice-java-spring

Contribute to chanbinme/practice-java-spring development by creating an account on GitHub.

github.com

개발 환경

Java 17
Spring Boot 3.4.x
Gradle
IntelliJ

CommonsRequestLoggingFilter이란?

CommonsRequestLoggingFilter는 Spring에서 제공하는 서블릿 필터로, HTTP 요청 정보를 자동으로 로그로 남겨주는 기능을 제공한다. 별도의 코드 작성 없이 Bean 등록과 간단한 설정만으로 로그 출력을 활성화 할 수 있다.

구현하기

RequestLoggingConfig

다른 코드를 작성할 필요 없이 아래와 같이 CommonsRequestLoggingFilter의 빈 설정만 해주면 된다.

@Configuration
public class RequestLoggingConfig {

    @Bean
    public CommonsRequestLoggingFilter requestLoggingFilter() {
        CommonsRequestLoggingFilter filter = new CommonsRequestLoggingFilter();
        filter.setIncludeClientInfo(false);  // IP 주소 및 사용자 에이전트 정보 포함
        filter.setIncludeQueryString(false); // 쿼리 문자열 포함
        filter.setIncludePayload(true); // 요청 페이로드 포함
        filter.setMaxPayloadLength(10000); // 최대 페이로드 길이 설정
        filter.setIncludeHeaders(false); // 헤더 정보 포함
        filter.setAfterMessagePrefix("Request Data: "); // 로그 메시지 접두사 설정

        return filter;
    }
}

주요 설정 옵션은 아래와 같다.

setIncludeClientInfo(boolean): 클라이언트 IP, 세션 ID 등의 정보 포함 여부
setIncludeHeaders(boolean): HTTP 헤더 로그 포함 여부
setIncludePayload(boolean): Request body(본문) 로그 포함 여부
setIncludeQueryString(boolean): 쿼리 파라미터 포함 여부
setMaxPayloadLength(int): 로그로 남기는 본문의 최대 길이 설정

application.yml

로그 출력 레벨은 기본적으로 DEBUG이므로, CommonsRequestLoggingFilter의 로깅 레벨을 DEBUG로 맞추면 로그가 남기 시작한다.

logging:
  level:
    org.springframework.web.filter.CommonsRequestLoggingFilter: DEBUG

테스트

PostController

@RestController
@RequestMapping("/posts")
@RequiredArgsConstructor
public class PostController {

    private final PostService postService;
    
    @PostMapping
    public void createPost(@RequestBody PostCreateRequestDto postCreateRequestDto) {
        postService.createPost(postCreateRequestDto);
    }
}

setIncludePayload 옵션만 true로 설정했을 때

모든 옵션을 true로 설정했을 때

참조

https://www.baeldung.com/spring-http-logging

JPA - SemanticException: Query specified join fetching, but the owner of the fetched association was not present in the select List 원인과 해결 방법

Cold Bean — Wed, 9 Jul 2025 16:47:23 +0900

배경

Querydsl을 작성하여 테스트하던 중 아래와 같은 에러를 만났다.

public Optional<Partner> searchPartnerByMerNo(String merNo) {
    return Optional.ofNullable(
        query.select(partner)
             .from(merchant)
             .innerJoin(merchant.partner, partner).fetchJoin()
             .where(merchant.merchantNo.eq(merNo))
             .fetchOne()
    );
}

SemanticException: Query specified join fetching, but the owner of the fetched association was not present in the select List

해석해 보면 “조인된 연관관계의 주인이 select 절에 포함되지 않았다” 라고 한다.

개발 환경

Java 17
Spring Boot 3.4.x
Spring Data JPA
Querydsl
Gradle
IntelliJ

원인

원인은 fetchJoin에 있다. fetchJoin은 단순히 join해서 데이터를 가져오는 것뿐만이 아니라, 연관된 엔티티들을 한 번에 영속성 컨텍스트에 채워 넣겠다는 의미를 갖는다. (그러한 이유때문에 N+1을 해결하기 위한 방법으로 많이 사용된다.)

그런데 위 코드처럼 partner만 select하고 merchant는 select에서 빠져있으면, Hibernate는 어떤 엔티티를 기준으로 그래프를 로딩해야할지 알 수 없다. 여기서 owner 엔티티는 merchant이기 때문이다.

해결 방법

fetchJoin은 반드시 owner 엔티티를 select해야 한다. 이렇게 하면 merchant가 select 되고, partner도 fetchJoin을 통해 함께 로딩된다. 즉 한 번의 쿼리로 두 엔티티가 영속성 컨텍스트에 채워지게 된다.

query.select(merchant)
     .from(merchant)
     .join(merchant.partner, partner).fetchJoin()
     .where(...);

만약 단순히 partner만 뽑아오고 싶다면, fetch Join은 사용하지 말아야한다.

query.select(partner)
     .from(merchant)
     .join(merchant.partner, partner)
     .where(...)

MySQL - Recursive query aborted after 1001 iterations. Try increasing @@cte_max_recursion_depth to a larger value.

Cold Bean — Mon, 7 Jul 2025 09:56:12 +0900

배경

테스트에 사용할 더미 데이터 생성을 위해 MySQL에서 재귀 CTE를 사용하다가 아래와 같은 에러를 만났었다.

WITH RECURSIVE seq AS (
    SELECT 1 AS seq
    UNION ALL
    SELECT seq + 1 FROM seq WHERE seq < 1000000
)
SELECT
    DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY) AS transaction_dt,
    FLOOR(50000 + (RAND() * 990)) * 100 AS request_amount,
    FLOOR(RAND() + (FLOOR(1000 + (RAND() * 500)) + 1)) * 100 AS processing_amount,
    DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY) AS created_dt,
    LPAD(seq, 6, '0') AS approval_no
FROM seq
LIMIT 1000000;

Recursive query aborted after 1001 iterations. Try increasing @@cte_max_recursion_depth to a larger value.

테스트 데이터를 대량으로 만들기 위해 WITH RECURSIVE 구문으로 시퀀스를 생성했는데, 1001번째에서 쿼리가 중단되는 문제가 발생했었다.

원인

알고 보니 MySQL은 무한 루프를 방지하기 위해 재귀 CTE의 최대 반복 횟수를 1000으로 제한하고 있었다. 따라서 1000개까지만 순차적으로 생성이 가능했고, 그 이상으로 반복하려 하면 위 에러가 발생했던 것이었다. 이 제한 값은 시스템 변수 cte_max_recursion_depth로 관리되고 있었고, 기본값은 1000이었다.

해결 방법

나는 세션 단위에서 cte_max_recursion_depth 값을 늘려주는 방식으로 해결했다.

SET SESSION cte_max_recursion_depth = 100000;

아래처럼 글로벌 설정도 가능하지만, 글로벌로 설정하면 MySQL 서버 전체에 영향을 주기 때문에 주의해야 한다.

SET GLOBAL cte_max_recursion_depth = 100000;

참조

https://dba.stackexchange.com/questions/338291/setting-cte-max-recursion-depth-value-has-no-effect

Setting cte_max_recursion_depth value has no effect

I am using MySQL 8.0.36, I have a recursive query to insert 5 million rows to a table. I get the error ERROR 3636 (HY000): Recursive query aborted after 1001 iterations. Try increasing @@

dba.stackexchange.com

https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_cte_max_recursion_depth

MySQL :: MySQL 8.0 Reference Manual :: 7.1.8 Server System Variables

dev.mysql.com

소프트웨어 버전 관리

Cold Bean — Sun, 29 Jun 2025 17:39:06 +0900

{Major}.{Minor}.{PATCH} 구조

Major 버전: 이전 버전과 호환되지 않는 API 변경 시 증가
Minor 버전: 하위 호환 가능한 새로운 기능 추가 시 증가
Patch 버전: 하위 호환 가능한 버그 수정 시 증가

버전 증가 규칙

각 버전 번호는 음수가 아닌 정수여야 함
상위 버전이 증가하면 하위 버전은 0으로 리셋 (예: 1.9.0 → 1.10.0 → 2.0.0)
버전 배포 후 해당 버전의 내용은 절대 변경 금지. 변경사항이 있다면 반드시 새로운 버전으로 배포

Spring - Spring Data Envers로 엔티티 변경 이력을 쉽게 관리해보기

Cold Bean — Fri, 27 Jun 2025 14:04:54 +0900

배경

사이드 프로젝트나 실제 서비스에서 데이터 변경 이력 관리가 필요할 때가 많다. “누가, 언제, 무엇을, 어떻게 바꿨는지” 추적이 필요하다면, Spring Data Envers가 딱이다. 이번 글에서는 Spring Data Envers를 실제로 적용하는 방법을, 내가 직접 해보면서 겪은 시행착오와 함께 정리해본다.

Envers란?

Hibernate Envers는 JPA 엔티티의 변경 이력을 자동으로 관리해준다. Spring Data Envers는 이를 Spring Data JPA와 자연스럽게 통합해주기 때문에, 기존 Repository 패턴을 그대로 쓰면서도 이력 관리가 가능하다

프로젝트에 Envers 적용하기

의존성 추가

build.gradle에 아래 의존성을 추가한다.

implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.springframework.data:spring-data-envers'

엔터티 설정

변경 이력을 관리하고 싶은 엔터티에 @Audited 어노테이션만 붙이면 된다.

클래스에 @Audited를 사용하면 엔티티 전체 이력을 관리하게 되고, 특정 필드에 사용하면 해당 필드의 변경 이력만 관리하게 된다.

특정 필드에 @NotAudited를 붙이면 해당 필드는 이력 관리에서 제외된다. 보통 민감 정보, 빈번히 변경되는 값 등을 이력 관리에서 제외할 때 사용한다.

어노테이션	적용 대상	효과
@Audited	엔티티/필드	변경 이력 관리 대상에 포함
@NotAudited	필드	해당 필드만 이력 관리에서 제외

@Getter
@Builder
@Entity
@Audited   // 엔티티 전체 이력 관리
@EqualsAndHashCode
@AllArgsConstructor
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class Post {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private String content;

    @OneToMany(mappedBy = "post")
    private List<Comment> comments;

    public void addComment(Comment comment) {
        if (comments == null) {
            comments = new ArrayList<>();
        }

        if (!comments.contains(comment)) {
            comments.add(comment);
        }
    }

    public void removeComment(Comment comment) {
        if (comments != null) {
            comments.remove(comment);
        }
    }
}

@Getter
@Builder
@Entity
@EqualsAndHashCode
@AllArgsConstructor
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class Comment {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Audited   // 특정 필드의 이력 관리
    private String content;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "post_id", nullable = false)
    private Post post;

    public void setPost(Post post) {
        this.post = post;
        post.addComment(this);
    }

    public void removePost() {
        if (this.post != null) {
            this.post.removeComment(this);
            this.post = null;
        }
    }
}

❓연관관계 필드에서 @Audited를 붙이면 어떻게 될까?

연관관계(@ManyToOne, @OneToMany) 필드에 @Audited를 붙이면 해당 연관관계 엔티티의 변경 이력까지 기록하게 된다. 다만, 해당 엔티티에도 @Audited가 붙어 있어야 한다.

만약 연관관계 엔티티의 변경 이력까지는 기록하지 않고, 연관 관계의 현재 FK(id) 값만 이력 테이블에 저장하고 싶다면 @Audited(targetAuditMode = RelationTargetAuditMode.NOT_AUDITED)으로 옵션을 붙여서 사용하면 된다. FK까지도 기록하고싶지 않으면 @NotAudited를 붙이면 된다.

데이터베이스에 테이블 자동 생성

이제 애플리케이션을 ddl-auto를 사용해 테이블이 생성해보면 COMMENT, POST 테이블 외에 COMMNET_HISTORY, POST_HISTORY, REVINFO 테이블이 생긴 것을 볼 수 있다.

기본적으로 Hibernate Envers는 엔티티 이력 테이블에 _AUD 접미사를 사용한다. 예를 들어, Post 엔티티라면 post_AUD 테이블이 생성된다. 이 접미사를 바꾸고 싶다면, application.yml 또는 application.properties에서 설정할 수 있다. 나는 _history로 변경했다.

spring:
  jpa:
    properties:
      org:
        hibernate:
          envers:
            audit_table_suffix: _history   # 이력 테이블 접미사 변경

엔티티 변경

이제 엔티티가 변경되었을 때 어떻게 기록되는지 확인해보자. 게시판 생성, 수정, 삭제를 순차적으로 진행했다.

PostController

@RestController
@RequestMapping("/posts")
@RequiredArgsConstructor
public class PostController {

    private final PostService postService;

    @PostMapping
    public void createPost() {
        postService.createPost();
    }

    @PatchMapping
    public void updatePost() {
        postService.updatePost();
    }

    @DeleteMapping
    public void deletePost() {
        postService.deletePost();
    }
}

PostService

@Service
@Transactional
@RequiredArgsConstructor
public class PostService {

    private final PostRepository postRepository;

    public void createPost() {
        Post post = Post.builder().title("아 덥다").content("더워 죽겠다. 너무너무 덥다...").build();
        postRepository.save(post);
    }

    public void updatePost() {
        postRepository.findById(1L)
            .ifPresent(post -> post.updateContent("에어컨 틀었더니 조금 시원하다. 에어컨 최고!"));
    }

    public void deletePost() {
        postRepository.deleteById(1L);
    }
}

PostRepository

public interface PostRepository extends JpaRepository<Post, Long> {
}

위 이미지를 보면 이력이 자동 생성된 걸 확인할 수 있다. 이제 이 이력에 대한 정보가 무엇을 나타내는걸까?

이력 테이블(_AUD지만 내가 별도 설정해두어서 현재는 _HISTORY가 붙은 테이블)과 REVINFO 테이블에 대해 알아보자

이력 테이블(_AUD 테이블)

Envers를 적용한 엔티티마다 생성되는 이력 테이블은 아래와 같은 구조를 갖는다.

컬럼명	설명
엔티티 PK (ID)	엔티티의 기본키(PK). 복합키라면 여러 컬럼이 될 수 있다.
엔티티 필드(CONTENT, TITLE)	엔티티의 이력 관리 대상 필드 값
REV	해당 변경 이력이 속한 리비전 번호. REVINFO 테이블의 REV와 FK로 연결된다.
REVTYPE	변경 유형 - 0 : 추가(INSERT) - 1 : 수정(UPDATE) - 2 : 삭제(DELETE)

REVINFO 테이블

REVINFO 테이블은 리비전(변경 이력의 묶음)을 관리한다.

컬럼명	설명
REV	리비전 번호(순차 증가 PK)
REVSTMP	리비전 생성 시각(Unix timestamp, ms)

REVINFO는 @RevisionEntity를 사용해 커스텀할 수 있다.

이 정보를 바탕으로 이미지를 보면 각 변경 타입(REVTYPE)에 맞게 잘 저장된걸 확인할 수 있다. 이렇게 설정만 해두면 이렇게 편하게 자동으로 이력을 관리해준다.

REVINFO 커스텀

지금도 충분히 편할 수 있지만 뭔가 아쉽다. 예를 들어, 변경 요청을 한 IP를 저장하고 싶을 수도 있다.

이럴 때는@RevisionEntity와 RevisionListener를 사용해서 원하는대로 Revinfo(리비전 엔티티)를 커스텀할 수 있다.

변경 이력에 변경 요청을 한 IP를 자동으로 저장할 수 있도록 해보자

CustomRevisionEntity

DefaultRevisionEntity를 상속 받아 IP 컬럼을 추가할 커스텀 엔티티를 작성한다.

/**
 * Envers에서 사용하는 커스텀 리비전 엔티티.
 * 기본 리비전 엔티티에 IP 주소 필드를 추가한다.
 */
@Getter
@Setter
@Entity
@Table(name = "revinfo")    // Envers에서 사용하는 기본 테이블 이름
@RevisionEntity(CustomRevisionListener.class) // 리스너 연결
public class CustomRevisionEntity extends DefaultRevisionEntity {

    private String ipAddress;
}

CustomRevisionListener

Revision이 생성될 때마다 현재 요청의 IP 주소를 커스텀 리비전 엔티티에 세팅한다.

public class CustomRevisionListener implements RevisionListener {

    /**
     * Envers에서 새로운 리비전이 생성될 때 호출되는 메소드.
     * 현재 요청의 IP 주소를 CustomRevisionEntity에 설정한다.
     *
     * @param revisionEntity 새로 생성된 리비전 엔티티
     */
    @Override
    public void newRevision(Object revisionEntity) {
        CustomRevisionEntity rev = (CustomRevisionEntity) revisionEntity;

        String ip = "unknown";

        // 현재 요청의 HttpServletRequest에서 IP 추출
        ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (attrs != null) {
            HttpServletRequest request = attrs.getRequest();
            ip = request.getHeader("X-Forwarded-For");
            if (ip == null || ip.isEmpty()) {
                ip = request.getRemoteAddr();
            }
        }
        rev.setIpAddress(ip);
    }
}

REVINFO에 IP_ADDRESS가 추가된 것을 확인할 수 있다. 이제 우리는 매번 직접 IP 주소를 저장할 필요가 없어졌다. envers가 알아서 다 해주니까!

마무리

Envers는 이번에 우리 팀에서 도입하게 되면서 처음 알게 되었다.

Envers는 설정이 간단하지만, 실제로 써보면 “이렇게까지 자동화가 되나?” 싶을 정도로 강력하다.
사이드 프로젝트든, 실무든 데이터 이력 관리가 필요하다면 한 번쯤 꼭 도입해보길 추천한다.

다만, 이력 테이블도 결국 DB 리소스를 잡아먹기 때문에 꼭 필요한 엔티티/필드에만 @Audited를 적용하자. 그리고 DB 마이그레이션 시 REVINFO 및 _AUD 테이블 구조도 함께 변경해줘야 할 수 있다.

참조

https://www.baeldung.com/java-hibernate-envers-extending-revision-custom-fields

https://docs.spring.io/spring-data/envers/docs/current/reference/html/

Spring Data Envers - Reference Documentation

Example 10. Repository definitions using domain classes with annotations interface PersonRepository extends Repository { … } @Entity class Person { … } interface UserRepository extends Repository { … } @Document class User { … } PersonRepository re

docs.spring.io

Docker - standard_init_linux.go:xxx: exec user process caused "exec format error“ 원인과 해결 방법

Cold Bean — Thu, 26 Jun 2025 14:17:10 +0900

배경

기존에는 Dockerfile에서 Java 애플리케이션을 실행할 때 ENTRYPOINT에 모든 JVM 옵션과 실행 명령어를 길게 나열해서 작성했었다. 하지만 JVM 옵션이 많아지고 환경별로 다른 설정이 필요해지면서 관리가 어려워졌다. 그래서 별도의 쉘 스크립트 파일에서 이런 복잡한 실행 로직을 관리할 수 있도록 entrypoint.sh를 만들게 되었다.

entrypoint.sh를 추가하여 Docker 컨테이너를 실행하자 entrypoint.sh에서 예상치 못한 format 에러가 발생했다.

standard_init_linux.go:xxx: exec user process caused "exec format error“

개발 환경

Docker
Portainer
Linux
Java 17
Spring Boot 3.4.x
Bash/Shell Script

문제

기존 Dockerfile

처음에는 Dockerfile에서 다음과 같이 ENTRYPOINT를 직접 작성했었다. 하지만 JVM 옵션이 길어질수록 가독성이 저하되는 문제가 있었다.

FROM openjdk:17-jre-slim

COPY app.jar /app.jar

ENTRYPOINT ["java", "-Xms512m", "-Xmx1024m", "-XX:+UseG1GC", "-XX:+UseStringDeduplication", "-Dspring.profiles.active=prod", "-jar", "/app.jar"]

개선된 Dockerfile (문제 발생)

별도의 쉘 스크립트로 분리해서 더 유연하게 관리할 수 있도록 개선했다.

하지만 추가된 entrypoint.sh 파일에서 format 에러가 발생했다.

FROM openjdk:17-jre-slim

COPY app.jar /app.jar
COPY entrypoint.sh /entrypoint.sh

RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

# entrypoint.sh

# JVM 기본 옵션 설정
JAVA_OPTS="-Xms512m -Xmx2g"
JAVA_OPTS="$JAVA_OPTS -XX:+UseG1GC"
JAVA_OPTS="$JAVA_OPTS -XX:+UseStringDeduplication"
JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=prod"

# 애플리케이션 실행
exec java $JAVA_OPTS -jar /app.jar "$@"

원인

exec format error는 주로 다음과 같은 상황에서 발생한다.

실행 파일의 아키텍처가 맞지 않는 경우 (예: ARM 바이너를 x86에서 실행)
실행 파일이 손상된 경우
스크립트 파일에 shebang 라인이 없는 경우

내 경우에는 세 번째 케이스였다. Shebang 라인은 스크립트의 실행 환경을 결정하기 때문에 반드시 있어야 한다. Shebang 라인이 없으면 Docker는 entrypoint.sh 파일을 실행할 때 어떤 인터프리터로 실행해야 하는지 알 수 없어서 바이너리 파일로 인식하려고 실행하려다가 실패한다.

Shebang이란?

#!/bin/sh

Shebang 라인은 스크립트 파일의 맨 첫 번째 줄에 위치하는 #!(주석 아님) 로 시작하는 라인이다.

Shebang 라인은 스크립트 파일이 어떤 인터프리터의 명령어 집합인지를 시스템에 알려주는 역할을 한다.

#! 뒤에는 명령어들을 해석할 프로그램의 위치를 나타낸다.

# 예시 

#!/bin/sh          # POSIX 호환 shell
#!/bin/bash        # Bash shell  
#!/usr/bin/python  # Python 2
#!/usr/bin/env python # 환경에서 python 찾기

해결 방법

entrypoint.sh 파일 맨 첫 줄에 shebang 라인을 추가해주면 된다.

# entrypoint.sh

# shebang 라인 추가
#!/bin/sh

# JVM 기본 옵션 설정
JAVA_OPTS="-Xms512m -Xmx2g"
JAVA_OPTS="$JAVA_OPTS -XX:+UseG1GC"
JAVA_OPTS="$JAVA_OPTS -XX:+UseStringDeduplication"
JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=prod"

# 애플리케이션 실행
exec java $JAVA_OPTS -jar /app.jar "$@"

참조

https://iksciting.com/what-is-shebang/

Linux: What is Shebang? - IKSciting

Linux에서 script를 열었을 때 첫 줄이 #!로 시작하는 경우를 종종 보게 된다. 이를 shebang이라고 부르는데 어원에 대해서는 sharp + bang, hash + bang, shell + bang 등 여러가지 설이 있지만 이름이나 어원은

iksciting.com

https://github.com/opencontainers/runc/issues/1773

"exec format error" for ENTRYPOINT pointing to shell script lacking shebang line · Issue #1773 · opencontainers/runc

I'm posting this here because error message is raised by a file in this project: standard_init_linux.go:195: exec user process caused "exec format error" As an end user I'd like it if somehow it wa...

github.com

HTTP - 프록시 환경에서 실제 클라이언트 IP 찾기 (X-Forwarded-For, X-Real-IP)

Cold Bean — Mon, 16 Jun 2025 15:20:26 +0900

배경

새로운 프로젝트에서 화이트리스트 IP 검증 로직(IP 기반 접근 제한)을 구현하게 되었다. 처음에는 단순하게 request.getRemoteAddr()를 사용하면 될 줄 알았는데, 실제 운영 환경에서는 중간에 프록시를 거치다보니 실제 클라이언트 IP가 아닌 프록시 IP가 조회되는 문제가 있었다. 이 문제를 해결하기 위해 알게된 X-Forwarded-For와 X-Real-IP에 대해 알아보자

문제 상황

웹 애플리케이션을 개발하다 보면 클라이언트의 실제 IP 주소가 필요한 경우가 많다. 특히 보안 정책, 접근 제어, 로깅 및 분석 등의 목적으로 사용된다. 하지만 실제 운영을 위한 웹 아키텍처에서는 클라이언트와 서버 사이에 다양한 중간 계층들이 존재한다. 로드 밸런서, 리버스 프록시, CDN 등을 거치면서 서버가 실제로 받는 IP는 클라이언트의 실제 IP 주소가 아닌 바로 직전의 프록시 IP 주소가 된다.

현재 내가 담당한 프로젝트의 아키텍처는 다음과 같다.

Client -> Load Balancer -> Reverse Proxy -> WAS

이런 구조에서 request.getRemoteAddr()를 사용하면 실제 클라이언트 IP가 아닌 바로 직전 프록시의 IP를 반환한다.

화이트리스트 검증에서는 실제 클라이언트의 IP가 필요하기 때문에 이 문제를 해결해야 했다.

X-Forwarded-For (XFF) 헤더

X-Forwarded-For 헤더는 HTTP 프록시나 로드 밸런서를 통해 접속하는 클라이언트의 원 IP 주소를 식별하는 사실상의 표준 헤더이다. 클라이언트와 서버 중간에서 중간 계층을 거치면서 IP가 변경되는데, 클라이언트의 원 IP 주소를 보기 위해서 X-Forwarded-For 요청 헤더가 사용된다.

동작 방식

X-Forwarded-For: <client>, <proxy1>, <proxy2>

각 프록시를 거칠 때마다 우측 끝에 IP를 추가한다.

User(1.1.1.1)
└ Proxy(2.2.2.2) - X-Forwarded-For: 1.1.1.1
  └ Nginx(3.3.3.3) - X-Forwarded-For: 1.1.1.1, 2.2.2.2

가장 왼쪽 IP가 최초 클라이언트의 IP이고, 가장 오른쪽 IP가 마지막 프록시의 IP이다.

X-Real-IP 헤더

X-Real-IP는 바로 직전 클라이언트의 IP를 나타낸다. XFF와 달리 단일 IP 값만을 전달한다.

User - Nginx - Tomcat	# X-Real-IP는 User IP
User - Proxy - Nginx - Tomcat	# X-Real-IP는 Proxy IP

보안 고려사항

XFF와 X-Real-IP 헤더의 문제점은 클라이언트가 조작할 수 있다는 것이다. 악의적인 사용자가 가짜 IP를 헤더에 추가해서 보안 정책을 우회할 수 있는 문제가 있다. 그래서 신뢰할 수 있는 리버스 프록시를 통해서만 접근을 허용하고, 다른 경로로 백엔드 서버로의 직접 접근을 차단해야 한다.

참조

What is X-Forwarded-For and when can you trust it?

The X-Forwarded-For (XFF) HTTP header provides crucial insight into the origin of web requests. The header works as a mechanism for conveying the original...

httptoolkit.com

X-Forwarded-For - HTTP | MDN

X-Forwarded-For (XFF) 헤더는 HTTP 프록시나 로드 밸런서를 통해 웹 서버에 접속하는 클라이언트의 원 IP 주소를 식별하는 사실상의 표준 헤더다. 클라이언트와 서버 중간에서 트래픽이 프록시나 로드

developer.mozilla.org