상어코딩

Oracle 아키텍처 해부 — SGA·PGA·백그라운드 프로세스와 RAC의 기반

dding-shark — Wed, 15 Apr 2026 14:49:02 +0900

Oracle 아키텍처 해부 — SGA·PGA·백그라운드 프로세스와 RAC의 기반

들어가며

PostgreSQL은 프로세스 기반, MySQL은 스레드 기반. Oracle은 기본 Dedicated Server의 한 세션 = 한 OS 프로세스 모델이면서, 동시에 Shared·Threaded·DRCP라는 세 갈래를 OS·버전·워크로드에 따라 골라 쓸 수 있는 유일한 상용 DB다. 이 "선택권"이 장점이자 함정이다. 연결 모델 하나 바꿨을 뿐인데 OS 인증이 막히기도 하고(THREADED_EXECUTION=TRUE), LOB·AQ 같은 기능이 호환되지 않기도 한다(Shared Server). 하나의 추상 모델로 모든 것을 설명하는 PG·MySQL과 달리, Oracle을 읽을 때는 어떤 연결 모델을 전제로 하는지부터 먼저 확인해야 한다.

이 글을 쓰는 관점은 하나다 — 단일 인스턴스 Oracle을 설명하는 4개의 축(연결 모델·SGA·백그라운드 프로세스·공유 장치)이 왜 이렇게 설계됐는지를 한 번에 훑는다. RAC·Data Guard 같은 분산 확장은 이 단일 인스턴스 구조를 그대로 복제하고 조율하는 방향으로 붙는다. 즉 여기서 잡는 그림이 뒤이어 나올 RAC 시리즈의 기반이 된다.

Oracle 21c 기준이다. 버전 특화 기능(ACS, DRCP, Threaded Execution 등)은 도입 버전을 함께 명시한다. 1편 PostgreSQL·2편 MySQL InnoDB와 짝을 이루는 편이므로, 같은 주제가 나올 때마다 PG/MySQL과 한 문장씩 비교해 좌표계를 맞춘다.

"MTS"라는 용어는 더 이상 쓰지 않는다 — 공식 명칭은 Shared Server다
THREADED_EXECUTION=TRUE는 속도 튜닝이 아니다 — OS 인증이 막히는 부작용을 동반한다
CKPT가 블록을 디스크에 쓴다는 설명은 틀렸다 — control file과 datafile header만 갱신한다
UNDO가 "MVCC 우월 구조"라는 도식은 절반만 맞다 — ORA-01555는 바로 이 분리가 만드는 장애다
AWR/ASH로 관측하는 게 표준이라는 전제는 라이선스 문제다 — Diagnostic Pack은 유료다

이 글은 왜 → 구조 → 동작 → 주의 → 실무 순으로 정리한다.

1) 연결 모델 네 가지: Dedicated·Shared·Threaded·DRCP
2) SGA 해부: 여섯 영역과 그 쓰임
3) PGA: 세션 사설 메모리와 두 개의 한도
4) 백그라운드 프로세스 생태계: 여덟 주연
5) SCN과 UNDO: 논리 시계와 Read Consistency
6) Library Cache: hard/soft parse와 ACS
7) RAC로 가는 길: 단일 인스턴스에서 공유 everything으로
8) 실무에서 이렇게 읽고 쓴다
9) 한 줄 정리

1) 연결 모델 네 가지: Dedicated·Shared·Threaded·DRCP

Oracle을 처음 잡을 때 반드시 먼저 정리해야 할 축이 연결 모델이다. PG는 모든 연결이 fork, MySQL은 모두 스레드지만 Oracle은 워크로드별로 둘 다 혼용하는 대신 호환성 매트릭스가 존재한다. Dedicated·Shared·Threaded·DRCP 네 가지 중 무엇을 쓰느냐에 따라 OS 인증 여부, 메모리 배치, 세션 상태 저장소가 전부 달라진다. 공식 문서가 짧게 정리한다.

"Each client process communicates with a server process."

— Oracle Database 21c Concepts §15.2

"클라이언트 프로세스 : 서버 프로세스" 관계가 1:1이냐, N:1이냐, 혹은 N:M 풀이냐가 곧 연결 모델의 차이다.

1-1) Dedicated Server — 표준 모델

기본값이자 대부분의 OLTP 현장이 쓰는 모델이다. 세션 하나당 OS 프로세스(Linux에서는 oracle로 시작하는 프로세스) 하나가 붙는다. 세션이 유휴 상태여도 프로세스는 살아 있고, 세션 상태(UGA, User Global Area)는 PGA 안에 들어간다. 직관적이고 격리가 좋지만, 커넥션 수천 개를 OS 프로세스 수천 개로 올리면 메모리·스케줄링 비용이 그대로 부담이 된다.

1-2) Shared Server — "MTS"가 아니다

과거에 MTS(Multi-Threaded Server)라 불리던 모델의 공식 명칭은 Shared Server다. MTS 용어는 더 이상 문서에 쓰지 않는다. 구조는 Dispatcher와 Shared Server 프로세스 풀을 두고, 클라이언트 요청을 Dispatcher가 받아 Shared Server에 큐잉해 분배한다. 여기서 세션 상태 UGA가 PGA에서 SGA의 Large Pool로 이동한다는 점이 특이하다. 이게 나중에 Large Pool을 별도로 튜닝해야 하는 이유다.

함정 두 개. 하나는 LOB 전송·Advanced Queuing 등 일부 기능이 Shared Server와 호환되지 않는다는 점이고, 다른 하나는 Dispatcher가 Listener처럼 보여서 네트워크 진단이 헷갈린다는 점이다. 장기 트랜잭션이 섞인 OLTP에서는 세션 하나가 Shared Server 하나를 오래 점유해 큐가 밀리므로 OLAP 혼용 환경에는 쉽게 안 맞는다.

1-3) Threaded Execution — 12c+ Linux 전용

12c부터 Linux 전용으로 들어온 THREADED_EXECUTION=TRUE 모드는 백그라운드 프로세스 일부와 서버 프로세스를 스레드로 전환한다. 프로세스 수가 줄어드니 ps로 본 모습이 깔끔해지지만, 진짜 함정은 따로 있다.

"If this parameter is set to TRUE, operating system authentication is not supported."

— Oracle Database 21c Reference — THREADED_EXECUTION

OS 인증이 아예 차단된다. sqlplus / as sysdba 같은 무비밀번호 접속이 ORA-01031로 거절된다. 실제 터미널에서 보는 모습은 이렇다.

$ sqlplus / as sysdba

SQL*Plus: Release 21.0.0.0.0 - Production
ERROR:
ORA-01031: insufficient privileges

우회는 패스워드 파일을 다시 만드는 방향이다.

orapwd file=$ORACLE_HOME/dbs/orapwORCL password=... force=y
sqlplus sys/pwd@ORCL as sysdba

운영 스크립트가 OS 인증에 의존하는 경우 스크립트 전량을 고쳐야 하므로, 도입은 신중하게. 메모리 절감 효과도 광고만큼 크지 않다. 서버 프로세스가 차지하던 PGA는 스레드로 전환돼도 세션당 사설 영역이 여전히 동일 수준으로 필요하고, 절감되는 건 프로세스 제어 블록과 페이지 테이블 오버헤드 정도다. 관리 비용은 분명히 오른다.

1-4) DRCP — 웹·API 워크로드용 커넥션 풀

Database Resident Connection Pooling. 애플리케이션이 짧은 연결을 대량으로 만들어 쓰는 패턴(PHP, Python, Node 등)에서 서버 측에 공유된 Pooled Server 풀을 두고 클라이언트들이 빌려 쓰게 하는 방식이다. Shared Server와 비슷해 보이지만 결정적 차이가 있다 — DRCP는 세션 상태까지 pool에 묶였다 풀렸다 하는 반면, Shared Server는 세션은 유지되고 서버 프로세스만 공유된다.

설정은 DBMS_CONNECTION_POOL.CONFIGURE_POOL로 한다. POOL_SIZE, MIN_SIZE, INACTIVITY_TIMEOUT 같은 파라미터가 붙어 있고, ALTER SYSTEM이 아니라 PL/SQL 프로시저로 제어한다는 점이 독특하다.

BEGIN
  DBMS_CONNECTION_POOL.CONFIGURE_POOL(
    pool_name          => 'SYS_DEFAULT_CONNECTION_POOL',
    minsize            => 10,
    maxsize            => 80,
    inactivity_timeout => 300);
  DBMS_CONNECTION_POOL.START_POOL;
END;
/

주의할 점은 세션 상태의 단절이다. 애플리케이션이 ALTER SESSION으로 NLS·optimizer 힌트를 바꿔 놓아도, 풀에 반환된 뒤 다른 커넥션이 해당 Pooled Server를 잡으면 앞서 설정한 상태를 보장받지 못한다. DRCP를 쓰려면 애플리케이션이 매 요청마다 세션 상태를 자기 책임으로 초기화해야 한다.

1-5) 네 모델 비교와 선택 기준

모델	연결당 리소스	UGA 위치	OS 인증	대표 제약
Dedicated	OS 프로세스 1개	PGA	지원	동시 연결 수 확장성
Shared	Dispatcher + Shared Server 풀	Large Pool (SGA)	지원	LOB·AQ 비호환
Threaded	OS 스레드	PGA	차단 (ORA-01031)	Linux 12c+ 전용
DRCP	Pooled Server 풀	Large Pool (SGA)	제한적	세션 상태 단절 고려 필요

결론이 명확하다 — 특별한 사유가 없으면 Dedicated이 표준이고, 나머지는 각자의 제약을 이해한 뒤 고르는 선택지다. "네 가지 중에서 마음에 드는 것을 고르세요"가 아니라 "기본은 Dedicated, 예외 상황에 나머지"가 올바른 독해다.

2) SGA 해부: 여섯 영역과 그 쓰임

SGA(System Global Area)는 인스턴스가 기동되면 공유 메모리 세그먼트로 올라와 모든 세션이 공유하는 영역이다. PG shared_buffers + wal_buffers, MySQL innodb_buffer_pool + log_buffer를 합친 것이 Oracle SGA이되, Library Cache까지 같은 공유 메모리에 올린다. 즉 Oracle은 "실행 계획과 파싱된 SQL"조차 공유 자원으로 관리한다. 이게 뒤에 나올 §6 Library Cache의 경합 구조로 이어진다.

2-1) 여섯 영역과 역할

영역	용도	대표 V$ 뷰	대표 대기 이벤트
Database Buffer Cache	데이터 블록 캐싱 (DEFAULT/KEEP/RECYCLE)	`V$BUFFER_POOL_STATISTICS`	`db file sequential read`
Shared Pool	Library Cache + Row Cache(데이터 딕셔너리)	`V$SGASTAT`, `V$LIBRARYCACHE`	`library cache: mutex X`
Redo Log Buffer	커밋 전 redo 레코드 적재	`V$SYSSTAT` (`redo buffer allocation retries`)	`log buffer space`
Large Pool	RMAN, parallel slave, Shared UGA	`V$SGASTAT`	`enq: RO - fast object reuse`
Java Pool	Java 스토어드 프로시저 JVM 힙	`V$SGASTAT`	실무 관측 드묾
Streams Pool	GoldenGate Capture, AQ 스트리밍	`V$STREAMS_POOL_STATISTICS`	`STREAMS pool` 관련

KEEP·RECYCLE 두 버퍼 풀은 "자주 쓰는 작은 테이블은 KEEP에 고정, 한 번 쓰고 버리는 스캔은 RECYCLE로 격리"하는 분리 전략의 도구다. MySQL InnoDB의 LRU midpoint와 해결하려는 문제가 같지만, Oracle은 스키마 설계자가 명시적으로 선언하는 쪽이고 InnoDB는 엔진이 midpoint로 자동 처리하는 쪽이다.

2-2) AMM vs ASMM — 메모리 자동화의 두 단계

Oracle은 SGA 크기 관리를 두 단계로 자동화해 뒀다. ASMM(Automatic Shared Memory Management) 은 SGA_TARGET을 주면 Shared Pool·Buffer Cache·Large Pool 등의 내부 배분을 Oracle이 동적으로 조정한다. AMM(Automatic Memory Management) 은 거기서 한 발 더 나아가 MEMORY_TARGET 하나로 SGA+PGA 경계까지 Oracle이 옮긴다.

보기엔 AMM이 편해 보이지만 현장 권장은 다르다. AMM은 4GB 이하 소규모 환경 권장, 그 이상이면 ASMM + PGA_AGGREGATE_TARGET 분리가 표준이다. 이유는 두 가지다. 하나는 Linux HugePages가 ASMM에서만 제대로 쓸 수 있다는 점. AMM은 내부적으로 /dev/shm에 tmpfs로 공유 메모리 세그먼트를 만드는데, HugePages는 커널 기동 시점에 미리 예약되는 고정 페이지다. tmpfs가 쓰는 일반 페이지와 pre-reserved HugePages는 서로 다른 물리 풀이라 공존이 안 된다. 즉 AMM이 켜진 순간 HugePages는 버려지는 셈이다. 운영 환경에서 64GB SGA를 AMM으로 돌리면 TLB miss 비용이 그대로 누적된다. 다른 하나는 AMM의 동적 리사이징이 Library Cache 같은 민감 영역을 흔들 때 경합을 키울 수 있다는 점이다.

ASMM + HugePages로 가는 설정은 이렇게 생겼다.

-- SGA 고정 (ASMM)
ALTER SYSTEM SET SGA_TARGET=8G      SCOPE=SPFILE;
ALTER SYSTEM SET SGA_MAX_SIZE=12G   SCOPE=SPFILE;
ALTER SYSTEM SET MEMORY_TARGET=0    SCOPE=SPFILE;  -- AMM off
ALTER SYSTEM SET MEMORY_MAX_TARGET=0 SCOPE=SPFILE;

# /etc/sysctl.conf — 2MB HugePage 6144개 = 12GB 예약
vm.nr_hugepages = 6144

21c부터는 HugePage 배정 현황을 V$HUGEPAGE_INFO에서 직접 조회할 수 있어, 진단 시 OS /proc/meminfo만 보지 않고 인스턴스 안에서도 확인 가능하다.

여기서 틀리기 쉽다. "SGA가 크면 빠르다"는 도식은 성립하지 않는다. HugePages 없이 수십 GB SGA를 올리면 OS 페이지 테이블 비용이 폭증하고, 내부 래치·mutex 경합도 같이 커진다. 사이즈는 워크로드가 요구할 때만 키우는 것이 안전하다.

2-3) Shared Pool의 세 덩어리

Shared Pool은 외부에서 한 덩어리로 보이지만 실제로는 Library Cache + Row Cache(데이터 딕셔너리 캐시) + Reserved Area로 나뉜다. Library Cache는 파싱된 SQL·PL/SQL 캐시, Row Cache는 딕셔너리 객체 메타데이터 캐시, Reserved는 큰 연속 청크 할당용 예약 공간이다. SHARED_POOL_RESERVED_SIZE로 Reserved 크기를 명시해 두면 ORA-04031("unable to allocate") 장애에서 한 겹 방어선이 생긴다.

2-4) Redo Log Buffer의 세 트리거

Redo Log Buffer는 커밋을 기다리지 않고도 (1) 3초 경과, (2) 1MB 적재, (3) 버퍼의 1/3 full 세 조건 중 하나만 맞아도 LGWR이 파일로 내린다. 이 덕에 긴 트랜잭션도 커밋 시점에 수백 MB를 한 번에 밀지 않는다. MySQL의 redo log가 innodb_log_buffer_size에 쌓이다가 innodb_flush_log_at_trx_commit 값대로 flush되는 것과 매커니즘은 비슷하지만, Oracle 쪽 상시 flush의 트리거가 명확하게 세 개로 정의돼 있다는 점이 다르다.

Log Buffer가 부족하면 redo buffer allocation retries(V$SYSSTAT) 값이 증가하고, log buffer space 대기 이벤트(V$SYSTEM_EVENT)가 쌓인다. 12c 이후 기본값(수 MB~수십 MB)으로도 대부분 커버되지만, 대량 batch insert나 CTAS 같은 벌크 DML이 몰리는 시간대에는 이 두 지표로 부족 여부를 판단한다.

2-5) 관측의 라이선스 함정

SGA 내부 상태를 AWR/ASH 리포트로 보는 것이 Oracle 튜닝의 표준 경로다. 그런데 AWR·ASH·ADDM은 Diagnostic Pack 유료 옵션이다. Standard Edition에는 애초에 들어 있지 않고, Enterprise Edition에서도 라이선스를 별도로 사야 한다. V$ACTIVE_SESSION_HISTORY를 무심코 조회해도 라이선스 위반이 될 수 있다. 무료로 쓸 수 있는 것은 V$SESSION·V$SQL·V$SGASTAT 같은 기본 동적 성능 뷰와 Statspack 정도다. 이 한 번 경계만 지키고 이후는 줄여서 말한다.

3) PGA: 세션 사설 메모리와 두 개의 한도

PGA(Program Global Area)는 서버 프로세스마다 따로 잡는 사설 메모리다. SGA가 공유 영역이라면 PGA는 세션 격리 영역이다. 안에는 Private SQL Area(커서별 실행 상태, bind 변수, fetch 상태 등)와 Work Area(정렬·해시 조인·비트맵 머지 작업 공간)가 들어간다. Dedicated Server에서는 UGA도 PGA 안에 들어가고, Shared Server·DRCP에서는 UGA가 Large Pool로 이동한다는 점은 §1-2에서 본 대로다.

3-0) UGA와 CGA — PGA 안의 두 하위 영역

PGA를 덩어리로만 보면 구조가 잘 안 잡힌다. 한 겹 더 내려가면 두 하위 영역이 있다. UGA(User Global Area) 는 세션 수명 동안 살아 있는 세션 상태 저장소다. 로그온/로그오프 트리거 상태, 패키지 변수, OPEN된 커서 정보 같은 세션 전역 변수가 여기 머문다. CGA(Call Global Area) 는 한 DB 콜(call) 수명만큼만 사는 더 짧은 영역이다. recursive SQL 실행 중 쓰는 스택, bind 변수 해석 영역처럼 콜이 끝나면 사라지는 일시 상태가 들어간다.

배치는 연결 모델에 따라 갈린다. Dedicated이면 UGA·CGA 모두 PGA 안, Shared Server면 UGA는 Large Pool(SGA)로 빠지고 CGA만 PGA에 남는다. Shared Server에서 Large Pool 사이징이 중요해지는 이유가 바로 이 UGA 이동이다.

3-1) 두 한도 — target과 limit

Oracle 12c부터 PGA 제어는 두 축으로 쪼개졌다.

파라미터	성격	초과 시 동작
`PGA_AGGREGATE_TARGET`	soft, 권장치	초과해도 점진 조정, 경고만
`PGA_AGGREGATE_LIMIT`	hard, 절대 상한	초과 시 ORA-04036, 세션 강제 종료

PGA_AGGREGATE_TARGET은 오래전부터 있던 "대략 이 정도에서 맞춰 줘"라는 목표치다. 실제로는 워크로드가 몰리면 Oracle이 이 수치를 일시적으로 넘어가기도 한다. 12c에서 PGA_AGGREGATE_LIMIT이 도입되면서 비로소 절대 상한이 생겼다. 기본값은 PGA_AGGREGATE_TARGET의 2배 또는 서버 메모리의 일부 중 큰 값이다. 초과 시 Oracle은 ORA-04036을 던지고, 가장 많이 쓰는 세션부터 종료해 상한을 지킨다.

운영 관점에서 실수가 잦은 지점은 여기다. PGA_AGGREGATE_TARGET만 설정하고 LIMIT를 명시하지 않으면, Oracle이 자동으로 계산한 큰 값이 상한이 돼 OS swap까지 밀어넣는 사고가 난다. 대형 OLAP 쿼리 한 건이 서버 전체를 흔드는 전형적 사례가 이 구조에서 나온다. 두 값을 모두 명시하는 습관이 필요하다.

-- 두 값을 함께 못 박기
ALTER SYSTEM SET PGA_AGGREGATE_TARGET=4G SCOPE=BOTH;
ALTER SYSTEM SET PGA_AGGREGATE_LIMIT=8G  SCOPE=BOTH;

ORA-04036이 실제로 발생하면 Oracle은 V$PROCESS.PGA_USED_MEM이 큰 세션부터 종료한다. 즉 상한에 도달한 "죄"가 아니라 "많이 쓴 세션"이 희생된다. 대형 보고 쿼리가 희생양이 될 수 있으니, 야간 배치와 OLTP를 같은 인스턴스에 두는 환경에서는 PGA_AGGREGATE_LIMIT을 여유 있게 잡거나 Resource Manager로 세션 그룹을 갈라 둔다.

3-2) Work Area의 세 가지 실행 경로

정렬·해시 조인 같은 연산은 Work Area 크기에 따라 실행 경로가 세 단계로 나뉜다 — optimal(메모리에서 끝남), one-pass(temp tablespace 한 번 경유), multi-pass(여러 번 경유). V$SQL_WORKAREA_HISTOGRAM에서 쿼리 유형별로 어떤 경로가 얼마나 찍히는지 볼 수 있다.

SELECT low_optimal_size, high_optimal_size,
       optimal_executions, onepass_executions, multipass_executions
FROM   v$sql_workarea_histogram
ORDER  BY low_optimal_size;

세 경로는 비용 구조가 다르다.

경로	메모리 사용	temp I/O	실행 시간 특성
optimal	Work Area 안에서 완결	없음	가장 빠름, 변동 작음
one-pass	Work Area + temp 한 번	중간 (1패스)	2~5배 느려짐, 예측 가능
multi-pass	Work Area + temp 반복	큼 (여러 패스)	수십 배 느려짐, p99 튐

multi-pass 비율이 높아지면 PGA 총량 자체보다는 개별 Work Area 상한을 키워야 하는 경우가 많다. Oracle은 세션당 Work Area 최대치를 _pga_max_size 같은 숨은 파라미터로 제한한다. 단 이건 hidden parameter라 Oracle Support(MOS) SR 승인 없이 건드리지 않는다 — 잘못 올리면 한 세션이 PGA 대부분을 소진해 ORA-04036 연쇄 장애를 만들 수 있다. 안전한 대안은 병렬 실행 전략 재검토와 쿼리 재작성이다.

4) 백그라운드 프로세스 생태계: 여덟 주연

인스턴스가 올라오면 SGA와 함께 일군의 백그라운드 프로세스가 기동된다. PG는 checkpointer+bgwriter+walwriter 3인, MySQL은 master+page cleaner, Oracle은 V$BGPROCESS에서 8종 이상이 독립 관측된다. 각자가 맡은 책임이 분리돼 있어 이름과 역할을 외우는 것이 SGA 그림을 잡는 것만큼 중요하다.

4-1) 여덟 프로세스 요약

프로세스	역할	트리거	실패 시 영향
DBWR(DBWn)	Buffer Cache의 더티 블록을 datafile에 기록	체크포인트, free buffer 부족, 3초 timeout, dirty list 임계	인스턴스 crash
LGWR	Redo Log Buffer를 online redo log에 기록	commit(동기 fsync), 3초, 1MB, 1/3 full	인스턴스 crash
CKPT	control file과 datafile header에 체크포인트 위치 기록	`LOG_CHECKPOINT_INTERVAL` 등	인스턴스 crash
SMON	인스턴스 복구, temp segment 정리	기동 시, 주기 sweep	인스턴스 crash
PMON	비정상 종료 서버 프로세스 정리, 락 해제	세션 종료 감지	인스턴스 crash
ARCn	redo log 스위치 시 archive log 복사	`LOG_MODE=ARCHIVELOG`에서 스위치	커밋 중단(공간 고갈 시)
MMON	AWR 스냅샷, metric 수집 (Diagnostic Pack 유료)	1시간 주기(기본)	통계 수집 중단
RECO	분산 트랜잭션 in-doubt 복구	네트워크 복구 시	분산 커밋 지연

4-2) DBWR의 쓰기 네 조건

DBWR가 더티 블록을 datafile에 쓰는 타이밍은 네 가지로 정리된다 — (1) 체크포인트 발생, (2) free buffer 부족(쓸 블록 공간이 없을 때), (3) 3초 timeout, (4) dirty list 임계 초과. 1, 2, 4는 부하에 반응하는 트리거고 3은 상시 idle flush다. 한 덩어리를 한 번에 쓰지 않고 여러 조건으로 쪼개 분산 flush하는 구조라, DBWR가 "쓰기를 몰아친다"는 인식은 실제 동작과 맞지 않는다.

각 트리거는 서로 다른 관측 지표로 드러난다. 장애 분석에서 "DBWR가 느리다"를 붙잡을 때 어느 방향으로 봐야 하는지가 여기서 갈린다.

트리거	관측 지표	확인처
free buffer 부족	`free buffer waits`	`V$SYSTEM_EVENT`
checkpoint	`DBWR checkpoint buffers written`	`V$SYSSTAT`
3초 timeout	`DB Writer Timeout`	`V$SYSTEM_EVENT`
dirty list 임계	`dirty buffers inspected`	`V$SYSSTAT`

free buffer waits가 높다는 건 Buffer Cache가 작거나 DBWR가 쓰기를 못 따라간다는 뜻이고, dirty buffers inspected가 부풀면 LRU 스캔 범위가 넓어진다는 신호다. 원인이 다른 만큼 대응도 다르다.

MySQL InnoDB가 page cleaner를 도입해 flush를 비동기 분산한 것과 같은 문제의식이고, 내부 매커니즘은 Oracle 쪽이 먼저다.

4-3) LGWR — 커밋의 동기 fsync

LGWR는 성격이 다르다. 커밋 시점에 fsync를 동기로 걸고, 이 fsync가 끝나야 비로소 클라이언트에 COMMIT OK를 돌려준다. 이게 D(urability)의 뼈대다. 상시 flush 조건은 Redo Log Buffer 쪽에 적었듯 3초·1MB·1/3 full 셋이다. 동기 fsync 비용을 줄이려고 COMMIT_WRITE=BATCH,NOWAIT 같은 옵션이 존재하지만, 지속성 보장을 깎는 옵션이라 금융·결제 시스템에선 건드리지 않는다. 참고로 COMMIT_WRITE는 11g 이후 COMMIT_LOGGING(BATCH/IMMEDIATE)과 COMMIT_WAIT(WAIT/NOWAIT) 두 파라미터로 분리돼 각각 제어할 수 있게 됐다.

4-4) CKPT — 쓰지 않는 체크포인터

이름 때문에 오해하기 쉽다. CKPT는 실제 블록을 쓰지 않는다. 공식 문서가 단호하다.

"CKPT does not write data blocks to data files or redo blocks to online redo log files."

— Oracle Database 21c Concepts §15.3

CKPT가 하는 일은 control file과 datafile header에 체크포인트 SCN을 기록하는 것뿐이다. 실제 더티 블록 flush는 DBWR가, redo flush는 LGWR가 맡는다. 이 분리 덕분에 체크포인트가 자주 일어나도 I/O는 DBWR의 페이스로 분산된다. 여기서 틀리기 쉬운 지점을 다시 못 박아 두자 — "CKPT가 쓴다"는 설명은 틀렸다.

4-5) SMON·PMON·ARCn·RECO

SMON(System Monitor)은 인스턴스 복구의 총책임자다. 비정상 종료 후 재기동 시 복구는 두 단계로 갈린다. (1) roll-forward — online redo log를 따라 커밋·미커밋 가리지 않고 변경분을 전부 재적용해 crash 직전 상태까지 끌어올린다. 이 시점에 DB는 "열린 상태"가 돼 사용자 세션을 받을 수 있다. (2) roll-back — 아직 끝나지 않은(=COMMIT이 없었던) 트랜잭션을 UNDO로 되돌린다. roll-back은 DB가 열린 뒤 백그라운드에서 진행되므로, 가용성 복구 시간은 roll-forward 길이에 거의 수렴한다. PMON(Process Monitor)은 죽은 세션이 남긴 락·리소스를 회수한다. ARCn은 ARCHIVELOG 모드에서 redo가 스위치될 때마다 archive log 영역으로 복사하는 역할이고, 이게 끊기면 online redo log가 다 찰 때 커밋 자체가 막힌다. 증상은 명확하다 — 어느 순간부터 커밋이 전부 log file switch (archiving needed) 대기에 걸려 응답이 돌아오지 않는다. 복구는 archive log destination 공간 확보가 최우선이고, 그 전까지는 인스턴스가 사실상 read-only가 된다. RECO는 분산 트랜잭션에서 in-doubt 상태(2PC prepare 후 commit 응답 유실)를 네트워크 복구 뒤 정리한다. MMON은 AWR 스냅샷을 찍는데, 이 기능 자체가 Diagnostic Pack 유료 영역이라는 점은 §2-5에서 이미 못 박았다.

5) SCN과 UNDO: 논리 시계와 Read Consistency

Oracle의 MVCC는 두 장치가 받친다 — SCN(System Change Number)이라는 논리 시계와 UNDO라는 사전 이미지 창고다. PG는 튜플 버전을 heap에 쌓고 VACUUM으로 치우고, Oracle은 UNDO라는 전용 창고에 보낸다. PG는 bloat, Oracle은 ORA-01555. 같은 문제(오래된 버전 유지)의 두 갈래 해법이다.

5-1) SCN — 64비트 단조 증가 논리 시계

SCN은 64비트 정수로, 모든 커밋마다 부여되는 단조 증가하는 논리 시계 값이다. 트랜잭션 간 순서, redo 레코드의 위치, Read Consistency 스냅샷 기준 시점, 분산 DB 링크 동기화 등 Oracle 내부의 모든 시간 개념이 SCN 위에 앉아 있다. 그래서 SCN은 사실상 Oracle의 논리 클록이다.

함정은 SCN이 무한히 오른쪽으로 갈 수 있다는 생각이다. 실제로는 Headroom 개념이 있다. SCN이 현재 시각에 대해 허용되는 상한을 계산하는 공식이 따로 있고(Oracle Support 문서 MOS 1376995.1 — My Oracle Support 내부 노트, 공개 링크 없음), 이 상한을 넘어서면 인스턴스가 더 이상 커밋을 받지 않는다. 일상 운영에서는 마주치기 어렵지만, SCN Headroom 고갈 이슈는 DB Link로 서로 연결된 노드들 사이에서 전파되는 위험이 보고된 바 있다. 한 노드의 SCN 급증이 링크로 연결된 다른 노드로 번져 동시 고갈을 유발할 수 있다. 멀티 인스턴스 복합 환경을 다룰 땐 SCN도 운영 지표에 포함해 둔다.

5-2) UNDO Tablespace — 사전 이미지 창고

UPDATE·DELETE가 발생하면 Oracle은 변경 전 이미지를 UNDO Tablespace에 쌓는다. 이 저장소는 PG처럼 heap에 버전을 섞어 두는 것이 아니라, 별도 tablespace로 물리 분리된다. 읽기 트랜잭션이 과거 SCN 기준으로 블록을 읽으려 하면, 현재 블록에서 UNDO 체인을 거꾸로 타고 올라가 해당 SCN 시점의 이미지로 재구성한다. 이게 Oracle의 Read Consistency 구현이다.

"The UNDO_RETENTION parameter is honored only if the current undo tablespace has enough space."

— Oracle Database 21c Reference — UNDO_RETENTION

UNDO_RETENTION 기본값은 900초(15분)다. "15분은 UNDO를 보관하겠다"는 값처럼 들리지만 실제로는 best-effort다. UNDO tablespace에 여유 공간이 있을 때만 지켜지고, 공간이 부족하면 retention 값 안에 있는 UNDO도 덮어쓴다. 15분 이상 도는 long-running 쿼리가 있는 환경에서는 이 값만으로는 부족하다.

실제 운영 상태는 V$UNDOSTAT에서 10분 단위 스냅샷으로 확인한다.

SELECT end_time, undoblks, tuned_undoretention, maxquerylen
FROM   v$undostat
ORDER  BY end_time DESC
FETCH  FIRST 5 ROWS ONLY;

여기서 핵심 컬럼은 TUNED_UNDORETENTION이다. Oracle이 파라미터 UNDO_RETENTION과 실제 UNDO tablespace 크기, 그리고 MAXQUERYLEN(최근 관측된 가장 긴 쿼리 수명)을 종합해 자동 튜닝하는 실효 retention 이다. 즉 운영자가 설정한 값이 아니라 Oracle이 "이 정도는 유지해 보겠다"고 실제로 쥐고 있는 값이다. ORA-01555 분석에서 UNDO_RETENTION을 보는 게 아니라 TUNED_UNDORETENTION과 MAXQUERYLEN을 같이 보는 게 정공법이다.

UNDO 용량 사이징은 감각적으로는 이 공식이다 — 분당 UNDO 생성량 × retention(분) × 안전 계수(1.5~2). V$UNDOSTAT.UNDOBLKS로 10분 구간별 생성량을 뽑아 피크를 기준으로 잡고, 여기에 retention과 여유를 곱한다. 이 계산 없이 "대충 크게"로 잡으면 피크 시간대에 TUNED_UNDORETENTION이 확 떨어져 ORA-01555를 부르는 상황이 생긴다.

5-3) RETENTION GUARANTEE — 진짜 보장이 필요할 때

UNDO를 절대 덮어쓰지 말라고 강제하려면 UNDO tablespace에 RETENTION GUARANTEE 절을 명시해야 한다.

ALTER TABLESPACE undotbs1 RETENTION GUARANTEE;

이 옵션을 켜면 retention 안에 있는 UNDO는 공간이 부족해도 보호되지만, 대신 DML이 ORA-30036("unable to extend segment") 으로 실패할 수 있다. 즉 "쿼리 실패" vs "DML 실패"의 교환이다. 장기 분석 쿼리가 도는 DW성 인스턴스에선 켜는 것이, 최우선 OLTP에선 끄는 것이 대체로 맞다.

현재 설정 여부는 DBA_TABLESPACES.RETENTION 컬럼으로 확인한다. GUARANTEE·NOGUARANTEE·NOT APPLY 세 값 중 하나로 드러난다. NOT APPLY는 수동 UNDO 관리 모드라 AUM(Automatic Undo Management)을 쓰는 11g 이후 환경에서는 거의 마주치지 않는다.

5-4) ORA-01555 — 구조적 장애

ORA-01555("snapshot too old") 는 Oracle UNDO 구조의 대표적 구조적 장애다. 읽기 쿼리가 과거 SCN 블록을 UNDO로 재구성하려 할 때, 해당 UNDO가 이미 덮어쓰여 버리면 발생한다. 원인은 (1) UNDO_RETENTION보다 긴 쿼리, (2) UNDO tablespace 용량 부족, (3) COMMIT 이후 일정 시점 뒤에야 재사용 가능한 delayed block cleanout 등 여러 갈래다.

진단 순서는 항상 같다. 먼저 V$UNDOSTAT에서 에러 발생 시각 구간의 TUNED_UNDORETENTION과 MAXQUERYLEN을 비교한다. MAXQUERYLEN > TUNED_UNDORETENTION이면 (1)이 유력하고, UNDOBLKS 피크가 평소의 몇 배라면 (2)가 의심된다. 둘 다 아닌데 commit cleanout failures: block lost 같은 통계가 늘어나 있으면 (3)의 지문이다.

대응도 원인별로 다르다. (1)은 UNDO tablespace 증설 + UNDO_RETENTION 상향 + 필요 시 RETENTION GUARANTEE. (2)는 일시 피크를 유발한 쿼리/배치 식별 후 시간대 분산. (3)은 커밋 직후 같은 블록을 다시 읽는 패턴이 원인이라 쿼리 재작성이나 통계 수집 재조정이 답이다. "ORA-01555 = 쿼리가 너무 길다"로 뭉뚱그리면 원인의 1/3만 맞힌다.

여기서 한 도식만 못 박자. "UNDO 분리 = MVCC 우월"은 절반만 맞다. heap에 버전을 섞지 않아 읽기 경로가 깔끔해지는 장점은 있지만, 대신 UNDO 용량과 retention이라는 별도 운영 축이 붙는다. PG VACUUM bloat가 없는 대가로 ORA-01555라는 고유 장애를 껴안는다. 어느 한쪽이 구조적으로 우월한 게 아니라 서로 다른 운영 체감을 가진 두 설계일 뿐이다.

6) Library Cache: hard/soft parse와 ACS

Library Cache는 Shared Pool의 핵심 덩어리로, 파싱된 SQL·PL/SQL과 그 실행 계획을 공유 메모리에 캐싱하는 영역이다. 새로운 SQL이 들어오면 Oracle은 먼저 Library Cache를 뒤져 같은 SQL이 있는지 확인한다. 찾으면 soft parse(계획 재사용), 못 찾으면 hard parse(파싱+최적화 새로 수행)다. hard parse는 CPU·latch 비용이 크므로 OLTP 성능의 주요 튜닝 축이다.

6-1) CURSOR_SHARING — 세 가지 전략

하지만 "같은 SQL"의 판단 기준이 까다롭다. WHERE id=123과 WHERE id=456은 Oracle 눈에 다른 SQL(리터럴이 다르므로)이다. 이걸 제어하는 것이 CURSOR_SHARING 파라미터다.

값	동작	장점	단점
EXACT (기본)	리터럴이 같아야 공유	최적 실행 계획	hard parse 폭증
FORCE	리터럴을 bind로 자동 치환	parse 비용 절감	스큐 데이터에서 나쁜 공유 계획 고착
ACS (11g+)	bind 값에 따라 다른 계획 생성	두 마리 토끼	관측·이해 난도 ↑

CURSOR_SHARING=FORCE는 한때 만능 튜닝처럼 쓰였지만 함정이 크다. 컬럼 통계 분포가 스큐한 경우(예: 상태값 99%가 N, 1%가 Y), bind 값에 따라 최적 계획이 달라야 하는데 FORCE는 첫 번째 들어온 값 기준 계획을 굳혀 나머지 쿼리에 재사용한다. 결과는 "공유는 됐는데 느리다"다.

11g에서 도입된 Adaptive Cursor Sharing이 이 문제를 풀어 보려는 장치다. 같은 SQL이라도 bind 값의 분포가 계획에 영향을 준다고 Oracle이 판단하면(bind-sensitive), 실제 실행 결과를 관측해 bind 값 범위별로 여러 개의 plan을 생성한다(bind-aware). 관측은 두 개의 플래그로 드러난다.

-- V$SQL에서 cursor의 sharing 상태 확인
SELECT sql_id, child_number, is_bind_sensitive, is_bind_aware
FROM   v$sql
WHERE  sql_text LIKE 'SELECT ... FROM t WHERE col=?';

IS_BIND_SENSITIVE='Y'는 "이 커서는 bind 값에 민감할 가능성이 있다", IS_BIND_AWARE='Y'는 "실제로 여러 계획을 쓰는 상태다"를 뜻한다. ACS는 자동이지만 관측이 필요하고, 갑자기 p99가 튀는 쿼리가 있으면 여기 두 플래그를 먼저 확인하는 게 루틴이다.

한 걸음 더 들어가려면 V$SQL_CS_STATISTICS와 V$SQL_CS_HISTOGRAM을 본다. 전자는 child cursor별로 peek된 bind 범위와 실행 통계를, 후자는 실행 버킷을 보여준다.

SELECT sql_id, child_number, bind_set_hash_value,
       peeked_low, peeked_high, executions, rows_processed
FROM   v$sql_cs_statistics
WHERE  sql_id = '&sql_id';

여기서 틀리기 쉬운 지점이 있다. ACS는 cold-start에 약하다. bind-aware로 전환되려면 Oracle이 "이 bind 값 범위에서는 실행 통계가 다르다"는 증거를 충분히 모아야 하는데, 그 학습 기간에는 첫 번째 hard parse 때 peek된 값 기반의 계획이 모든 bind에 재사용된다. 배포 직후나 Shared Pool flush 직후에는 ACS가 아직 bind-sensitive만 찍혀 있고 bind-aware로 못 올라간 상태라 스큐 데이터에서 나쁜 계획이 몇 분~몇 시간 돌 수 있다. 이 구간을 줄이려면 SQL Plan Baseline이나 SQL Profile로 미리 계획을 고정해 두는 편이 안전하다.

6-3) library cache lock / pin — Oracle 고유 경합

여기서 함정 하나. Library Cache 공유 = 효율 단독 금지다. 파싱된 SQL을 공유 메모리에 둔다는 것은 곧 래치·mutex·lock·pin 같은 동기화 장치가 이 위에 올려져 있다는 의미다. 특히 library cache lock과 library cache pin은 Oracle에 고유한 경합 이벤트로, DDL과 DML이 같은 객체를 동시에 건드리거나, 대규모 hard parse가 몰릴 때 심하게 나타난다. V$SESSION_WAIT나 V$LOCK에서 library cache로 시작하는 이벤트가 자주 보인다면 Shared Pool 내부 경합이 병목이라는 신호다. DDL을 야간으로 미루거나, bind 변수 사용을 강제해 hard parse를 줄이는 쪽으로 대응한다.

두 이벤트는 성격이 다르다. library cache lock은 객체 정의 자체의 변경을 직렬화하는 락으로, DDL이 주범이다. library cache pin은 객체를 실행하는 동안 정의가 바뀌지 않도록 고정하는 장치라, 장시간 PL/SQL 실행과 DDL이 겹칠 때 pin 대기가 길어진다. 둘을 구분해야 대응도 갈린다 — lock 경합이면 DDL 타이밍과 객체 범위 축소, pin 경합이면 장시간 실행 PL/SQL의 분할이 답이다.

7) RAC로 가는 길: 단일 인스턴스에서 공유 everything으로

여기까지 그린 단일 인스턴스 구조 — SGA + PGA + 백그라운드 프로세스 + SCN/UNDO/Library Cache — 가 RAC(Real Application Clusters)의 출발점이다. RAC는 여러 노드가 같은 datafile을 공유하는 shared-everything 아키텍처로, 각 노드가 위에서 본 구조를 그대로 하나씩 가진 뒤 Cache Fusion으로 버퍼 캐시를 노드 간에 조율한다.

Cache Fusion과 GRD. 노드 A가 갖고 있는 버퍼 블록을 노드 B가 읽으려 하면, 디스크를 경유하지 않고 인터커넥트로 블록 이미지를 전송한다. 이 과정을 관리하는 게 GRD(Global Resource Directory) 로, 클러스터 전체에 분산돼 각 블록·락의 "마스터 노드"를 기록한다. 실무 조율 주체는 두 서비스다 — GCS(Global Cache Service) 는 데이터 블록의 global 소유권을, GES(Global Enqueue Service) 는 트랜잭션 락·library cache lock 같은 non-data 자원을 관리한다. 단일 인스턴스의 래치·mutex 개념이 클러스터 단위로 확장된 모습이다.

SCN의 노드 간 동기화. SCN은 단일 인스턴스에서 그냥 단조 증가 카운터였지만, RAC에서는 여러 노드가 동일한 SCN 공간을 공유해야 한다. Oracle은 Lamport 방식 broadcast SCN을 기본으로 쓰면서, 노드 간 메시지에 현재 SCN을 piggyback해 서로를 끌어올린다(필요 시 _lgwr_async_broadcasts·MAX_COMMIT_PROPAGATION_DELAY 계열 파라미터로 조정). 한 노드의 SCN 급증이 다른 노드로 번지는 §5-1 Headroom 위험은 이 동기화 메커니즘의 자연스러운 귀결이다.

Library Cache의 global 경합. 단일 인스턴스에서도 library cache lock·pin 경합이 있었는데, RAC에서는 이 자원 자체가 global resource로 확장된다. 한 노드가 패키지를 컴파일하는 동안 다른 노드에서 같은 객체를 실행하면 gc library cache lock 같은 global 대기가 발생한다. 단일 인스턴스에선 지역 문제였던 DDL 배치 타이밍이 RAC에선 클러스터 전체 성능 이슈로 번지는 이유다.

즉 이 글에서 잡은 네 축은 그대로 RAC 운영 축과 1:1 대응된다 — Buffer Cache → Cache Fusion/GCS, SCN → broadcast SCN, 락/래치 → GES, Library Cache → global library cache. 반대로 말하면, 단일 인스턴스에서 이 네 축을 제대로 못 잡아 두면 RAC에서는 인터커넥트 지연이 곱해져 같은 문제가 몇 배로 커진다. 예컨대 hard parse가 많은 애플리케이션을 RAC로 올리면 gc library cache lock 대기가 새로 붙어 단일 인스턴스 때보다 훨씬 큰 부하를 만든다.

RAC 이야기는 별도 편으로 분리한다. 여기서는 단일 인스턴스 구조가 곧 분산 확장의 기반 언어라는 점만 기억해 두자.

8) 실무에서 이렇게 읽고 쓴다

연결 모델은 기본 Dedicated을 쓰고, 바꿀 땐 제약 체크를 선행한다 — Shared는 LOB/AQ 비호환, Threaded는 OS 인증 차단, DRCP는 세션 상태 단절.
HugePages는 ASMM과 세트로 간다 — AMM + HugePages 조합은 구성 난도가 높아 운영에서는 피하는 쪽이 낫다.
PGA_AGGREGATE_TARGET과 PGA_AGGREGATE_LIMIT을 둘 다 명시한다 — hard limit 없이 운영하면 ORA-04036 방어선이 없어 OS swap까지 밀려갈 수 있다.
UNDO_RETENTION은 best-effort임을 잊지 않는다 — 장기 분석 쿼리가 있는 환경에선 RETENTION GUARANTEE와 UNDO tablespace 사이징을 같이 손본다.
ORA-01555는 쿼리 튜닝 실패가 아니라 UNDO 운영 이슈다 — 먼저 UNDO tablespace 용량·retention·delayed cleanout부터 확인한다.
Library Cache 경합 이벤트는 library cache 접두어로 검색한다 — hard parse 감소(bind 변수), DDL 야간 배치, CURSOR_SHARING 검토가 표준 대응 세트다.
AWR/ASH는 라이선스 경계선을 먼저 확인한다 — 무료 범위는 Statspack + 기본 V$ 뷰. 모르고 쿼리하면 Diagnostic Pack 위반이 될 수 있다.
CKPT가 쓴다는 설명은 다시 보면 틀렸다 — 더티 블록 flush는 DBWR, redo flush는 LGWR, CKPT는 control file과 datafile header의 SCN 갱신. 장애 분석 중 I/O 주체를 헷갈리지 말자.
TUNED_UNDORETENTION을 운영 지표에 포함한다 — 파라미터 UNDO_RETENTION이 아니라 Oracle이 실제로 쥐고 있는 값을 기준으로 장기 쿼리 허용 한도를 잡는다.
ACS가 bind-aware로 올라올 때까지의 cold-start 구간을 각오한다 — 배포·Shared Pool flush 직후 몇 분은 첫 peek 기반 계획이 모두에게 적용되는 위험 구간이다. 핵심 쿼리는 SQL Plan Baseline으로 고정해 두면 안전하다.
DRCP를 쓰면 애플리케이션이 매 요청마다 세션 상태를 초기화한다 — Pooled Server가 다른 요청으로부터 "오염된" 상태일 수 있다고 가정하고 코딩한다.
Library Cache lock과 pin은 성격이 다르다 — lock은 DDL, pin은 장시간 실행 PL/SQL이 주원인. 구분해서 진단한다.
숨은 파라미터(_로 시작)는 Oracle Support SR 없이 건드리지 않는다 — _pga_max_size 같은 값은 되돌릴 수 없는 사이드 이펙트가 있을 수 있다.

9) 한 줄 정리

Oracle은 연결 모델 4종·SGA 6영역·백그라운드 프로세스 8종·SCN·UNDO·Library Cache라는 세 공유 장치로 단일 인스턴스를 설명한다. 이 구조는 우연이 아니라 RAC·Data Guard 확장을 염두에 둔 설계 언어다. 관측 가능성의 상당 부분이 유료이고 UNDO·SCN·Library Cache 각각이 고유 장애 모드를 가진다는 점을 잊지 말자.

tags: oracle, oracle-database, sga, pga, lgwr, dbwr, scn, undo, library-cache, drcp

MySQL(InnoDB) 아키텍처 해부 — 스레드·버퍼 풀·redo/undo·purge·doublewrite·binlog

dding-shark — Wed, 15 Apr 2026 14:48:32 +0900

MySQL(InnoDB) 아키텍처 해부 — 스레드·버퍼 풀·redo/undo·purge·doublewrite·binlog

들어가며

PostgreSQL은 OS를 믿고 편집기를 얹었다. MySQL InnoDB는 OS를 믿지 않고 스토리지 엔진 레이어를 따로 세웠다. 같은 "관계형 DB"라는 이름을 달고 있지만, 두 엔진의 내부 철학은 이 한 문장에서 갈라진다. PG가 shared_buffers를 두고 나머지 캐싱을 OS page cache에 위임하는 쪽이라면, InnoDB는 버퍼 풀·redo·undo·doublewrite·binlog까지 전부 자기 손으로 관리한다. 심지어 서버 레이어와 스토리지 엔진 레이어를 handlerton이라는 가상 테이블 계약으로 나눠 두는 구조다. 이 구조가 머릿속에 없으면 innodb_flush_log_at_trx_commit이나 sync_binlog 같은 파라미터가 "뭔지는 모르지만 일단 1로 둬라"로 끝난다.

이 글을 쓰는 관점은 하나다 — 기본값이 왜 이런 숫자인지, 그리고 언제 바꿔야 하는지를 각 서브시스템 단위로 정리한다. 운영에서 만나는 파라미터가 200개가 넘지만, 실제로 장애와 직결되는 것은 20개 안팎이다. 이 20개를 쓰임새 기준으로 묶어 두면 다음 튜닝 때 머릿속에서 빠르게 소환할 수 있다.

이 글은 MySQL 8.0/8.4 기준으로 스레드 모델 → 버퍼 풀 → redo → doublewrite → undo/purge → binlog → 실무 순서로, InnoDB의 지도를 한 번 그려 둔다. 1편의 PostgreSQL 아키텍처와 짝을 이루는 편이다. 두 엔진을 같은 좌표계에 올려 두면 이후 락·MVCC·복제 비교가 훨씬 가벼워진다.

버퍼 풀은 크게 잡을수록 좋다는 도식은 절반만 맞다 — instance 자동 분할과 mutex contention이 숨어 있다
change buffer가 쓰기를 빠르게 만들어 준다는 서술은 SSD에서 뒤집힌다 — merge 시점의 p99 스파이크
doublewrite를 "무결성 전능 장치"로 오해하지 말자 — partial page write만 방어한다
innodb_flush_log_at_trx_commit=2는 "OS crash만 1초 손실"이다 — mysqld crash는 방어한다
binlog와 redo의 2PC는 group commit 2층 구조다 — TPS 회복은 동시성 조건부다

이 글은 왜 → 구조 → 동작 → 주의 → 실무 순으로 정리한다.

1) 스레드 모델: thread-per-connection과 handlerton
2) InnoDB 버퍼 풀: LRU midpoint·AHI·change buffer
3) redo log: group commit 1층과 flush 전략
4) doublewrite buffer: partial page write 방어선
5) undo tablespace와 purge thread
6) binlog와 2PC: group commit 2층
7) 실무에서 이렇게 읽고 쓴다
8) 한 줄 정리

1) 스레드 모델: thread-per-connection과 handlerton

MySQL을 기동하면 올라오는 단일 프로세스가 mysqld 하나다. 1편에서 본 PostgreSQL의 postmaster와 역할이 비슷해 보이지만 결정적으로 다르다. PG는 postmaster가 fork로 프로세스를 찍는다면, MySQL은 listener 스레드가 accept 후 worker 스레드에 넘긴다. 즉 MySQL은 단일 프로세스 안에서 스레드 풀 모델을 돈다. 이 차이가 연결 비용, 격리 실패 영향 범위, 메모리 사용 패턴까지 줄줄이 달라지게 만든다. 공식 문서의 정의가 한 줄이다.

"one-thread-per-connection: Creates a new thread for each client connection."

— MySQL 8.0 Reference Manual §7.1.12 Connection Management

기본값은 thread_handling=one-thread-per-connection. 연결 하나당 스레드 하나를 새로 만든다. 끝나면 회수하고, 다음 연결에 재사용한다. 프로세스 per connection이 아니라 스레드 per connection이다. fork 비용이 없는 대신, 동시 연결 수천 개가 몰리면 컨텍스트 스위칭이 그대로 병목이 된다.

Linux 커널 관점에서 한 줄 — 스레드는 커널에서 "경량 프로세스"로 스케줄된다. PG의 프로세스 per connection과 구조적 차이는 메모리 공간 공유 여부뿐이다. 스레드는 동일 주소 공간을 공유하므로 연결 간 데이터 공유가 쉽지만, 한 스레드의 힙 손상이 전체 프로세스를 끌어내릴 수 있다는 취약성도 가진다. PG가 "한 세션 죽어도 전체가 살아남는" 안정성을 얻는 대신 fork 비용을 감수하는 이유다.

1-1) thread_handling 세 값

값	동작	가용성
`one-thread-per-connection` (기본)	연결당 스레드 1개	Community + Enterprise
`no-threads`	단일 스레드 (디버그·임베디드)	모든 에디션
`pool-of-threads`	고정 풀에서 dispatch	Enterprise 전용

여기서 틀리기 쉽다. "thread pool을 쓰면 되지 않나"는 OSS MySQL에선 해당 없다. pool-of-threads는 MySQL Enterprise 또는 Percona Server/MariaDB의 자체 구현에서만 제공된다. Community 8.0은 여전히 one-thread-per-connection만 쓸 수 있다. 5천 동시 연결 OLTP에서 Community 그대로 돌리면, 스레드 수 자체가 커널 스케줄러를 끌어내리는 단계로 진입한다. 현실적 대응은 ProxySQL/PgBouncer 같은 풀러를 앞단에 두거나, Percona·MariaDB로 넘어가는 쪽이다.

연결당 스레드가 생기는 비용이 PG의 fork보다 싸다는 점은 맞다. 그렇지만 싸다는 것이 "무한히 만들어도 된다"는 뜻은 아니다. thread_cache_size=N을 통해 종료된 스레드를 일정 수까지 재사용해 생성 비용을 줄일 수 있다. 기본값은 서버 사양에 따라 자동 결정되지만, 연결 rate이 높으면 Threads_created 카운터의 증가 속도를 보고 thread_cache_size를 키운다. 이 값이 커넥션 생성당 1 가깝게 증가하고 있다면 캐시가 부족하다는 뜻이다.

1-2) handlerton — 서버와 엔진 사이의 vtable 계약

MySQL의 아키텍처에서 가장 먼저 익혀야 할 개념이 handlerton이다. 한 단어로 말하면 "스토리지 엔진이 서버 레이어에 자신을 등록하는 가상 테이블" 이다. InnoDB, MyISAM, Memory, Archive 같은 엔진들이 각자 handlerton 구조체에 create, open, commit, rollback, prepare 등의 함수 포인터를 채워 넣어 서버에 내민다. 서버 레이어(파서·옵티마이저·binlog·캐시)는 엔진을 추상화된 API로만 부르고, 구체 구현은 엔진 쪽이 책임진다.

PG와 비교가 명확하다. PG는 heap access method 하나를 중심으로 돌고 (pluggable storage가 12부터 들어왔지만 사실상 heap 단일), 플래너·WAL·MVCC가 heap 구조를 직접 알고 있다. MySQL은 반대로 서버가 엔진을 모르고, 엔진이 서버에 맞춘다. 그래서 MySQL은 엔진을 바꿔 끼울 수 있고 (ENGINE=MyISAM 같은 테이블 옵션), PG는 그럴 수 없다. InnoDB가 MySQL 5.5.5부터 default로 승격된 뒤로 사실상 MySQL = InnoDB처럼 보이지만, 구조상 여전히 별도 레이어다.

이 분리는 기능적으로 양날의 칼이다. 장점은 엔진 선택의 유연성 — 로그 테이블에 MyISAM을 쓰거나, in-memory 세션 테이블에 MEMORY 엔진을 쓰거나, 아카이빙에 ARCHIVE를 쓰는 식의 혼용이 가능하다. 단점은 최적화 깊이가 얕아진다는 점이다. 플래너가 엔진 내부를 모르고 handlerton API로만 부르다 보니, PG처럼 heap 레이아웃에 특화된 실행 계획을 만들기 어렵다. 그래서 MySQL은 Index Condition Pushdown, Multi-Range Read 같은 장치를 handlerton 위에 덧붙여 깊이 부족을 메우는 방향으로 진화해 왔다.

1-3) binlog가 서버 레이어에 있는 이유

handlerton 얘기가 중요한 이유 하나 — binlog는 서버 레이어에 붙어 있다. 엔진별 로그가 아니다. 그래서 InnoDB redo와 binlog의 동기화를 위해 2PC가 필요하고, 이게 §6 binlog와 2PC의 핵심 주제가 된다. PG가 WAL 하나에 모든 정보를 쌓는 것과 달리, MySQL은 엔진 레이어의 redo와 서버 레이어의 binlog를 두 개의 로그로 분리하고 그 사이를 2PC로 묶는다. 복잡해 보이지만 이유가 있다 — binlog는 엔진 중립 포맷이라 이기종 엔진 간 복제가 가능하고, statement/row/mixed 포맷 선택이 엔진과 독립적이다.

이 이중 로그 구조가 만들어 내는 대가는 쓰기 경로가 PG보다 길다는 점이다. PG는 WAL 한 번만 fsync하면 복제와 복구가 같은 로그로 해결되지만, MySQL은 §3-2 innodb_flush_log_at_trx_commit과 sync_binlog 두 값을 각각 조율해야 한다. 두 축의 조합이 곧 지속성 SLA다.

스레드 모델과 레이어 분리를 잡았으니, 이제 InnoDB 엔진 안쪽으로 들어간다. 가장 먼저 만나는 영역이 버퍼 풀이다.

2) InnoDB 버퍼 풀: LRU midpoint·AHI·change buffer

InnoDB 버퍼 풀은 페이지 캐시 + 쓰기 버퍼 + 인덱스 가속기를 한 덩어리로 묶은 공간이다. PG의 shared_buffers와 역할은 같지만 내부 구조가 훨씬 많다. 기본 페이지 크기는 16KB (PG는 8KB). 기본 크기는 innodb_buffer_pool_size=128MB, 운영 권장은 RAM의 50~75%다. PG의 25% 권장과 확연히 다른데, 이유는 간단하다. InnoDB는 OS page cache를 이중으로 쓰지 않는다. innodb_flush_method=O_DIRECT로 OS 캐시를 우회하므로 버퍼 풀이 사실상 유일한 캐시 레이어다. 그래서 RAM을 더 많이 먹어야 한다.

2-1) LRU midpoint — full scan이 hot을 쫓아내지 않게

InnoDB의 LRU는 단순한 LRU가 아니다. 중간 지점(midpoint)으로 쪼갠 변형 LRU다. 리스트의 5/8이 new sublist(hot), 3/8이 old sublist(cold)로 나뉘고, 새로 들어온 페이지는 new의 맨 앞이 아니라 old의 맨 앞에 꽂힌다. 공식 문서가 정확히 적는다.

"3/8 of the buffer pool is devoted to the old sublist."

— MySQL 8.0 Reference Manual §17.5.1 Buffer Pool

이 구조가 막는 것은 full table scan이 hot 페이지를 전부 쓸어내는 현상이다. 전체 테이블 스캔이 들어와도 페이지가 일단 old sublist에만 채워지고, 1초(innodb_old_blocks_time=1000ms) 이상 머물면서 재참조되어야 new로 승격된다. 대부분의 full scan 페이지는 한 번 보고 버려지므로 old 구간에서 바로 evict된다. hot 워킹셋은 흔들림 없이 new에 남는다.

기본값은 innodb_old_blocks_pct=37(3/8 ≈ 37%), innodb_old_blocks_time=1000(ms). 대용량 배치 쿼리가 OLTP와 섞여 도는 환경에서는 old_blocks_time을 더 길게(5000ms 등) 키우는 것이 보호에 유리하다.

관측은 information_schema.innodb_buffer_page_lru에서 is_old='YES'인 페이지 수를 집계해 old sublist의 실제 비율을 확인할 수 있다. 이 값이 설정 비율과 크게 다르다면 scan 워크로드가 왜곡을 만들고 있다는 신호다.

2-2) AHI — 적응형 해시 인덱스

Adaptive Hash Index(AHI)는 InnoDB가 자주 조회되는 B-tree 경로를 관측해서 자동으로 만드는 해시 인덱스다. 사용자가 건드리는 게 아니고, 엔진이 런타임에 "이 패턴이 반복적이면 해시로 줄여주는 게 낫다"고 판단해 붙인다. 덕분에 B-tree 3~4단 내려가는 경로가 O(1) 탐색으로 바뀐다.

구조 제약도 있다. AHI는 같은 prefix의 같은 길이 조회가 반복될 때만 만들어진다. 즉 WHERE col=?처럼 동일 컬럼·동일 패턴 조회가 일관되게 들어오는 OLTP에 가장 잘 맞고, ad-hoc 분석 쿼리처럼 매번 다른 경로를 타는 워크로드에는 득이 없다.

함정은 글로벌 mutex 경합이다. 8.0에서 innodb_adaptive_hash_index_parts=8(기본)로 파티션이 쪼개지긴 했지만, 여전히 높은 동시성 OLTP에서 AHI latch가 병목으로 올라오는 경우가 있다. SHOW ENGINE INNODB STATUS의 SEMAPHORES 섹션에서 btr_search_latch 대기가 자주 보이면 innodb_adaptive_hash_index=OFF를 검토한다. "성능 가속기"가 "글로벌 병목"으로 뒤집히는 지점이다.

판정의 기준은 세 가지다 — (1) AHI hit rate (Hash searches/s vs Non-hash searches/s), (2) SEMAPHORES 섹션의 AHI 관련 대기, (3) OFF로 전환했을 때 응답 시간 p99의 변화. 운영 데이터 일부 구간에서 OFF로 바꿔 AB 테스트를 돌려 보면 성능 회귀가 있는지 없는지 금방 드러난다.

2-3) change buffer — non-unique secondary index 전용

change buffer는 secondary index에 대한 변경을 버퍼 풀에 없는 페이지에 대해서는 물리 페이지를 읽어오지 않고 미뤄 두는 장치다. 나중에 그 페이지가 다른 이유로 읽힐 때 한 번에 merge한다. 랜덤 디스크 IO를 줄이는 효과가 큰데, 두 가지 제약이 있다.

이 장치도 역사적 맥락에서 태어났다. 5.5 이전의 insert buffer가 INSERT만 처리하던 것을, 5.5부터 INSERT/UPDATE/DELETE 모두를 포괄하는 change buffer로 확장한 것이다. 이름이 남아 ibuf로 부르기도 한다.

첫째, unique secondary index에는 적용되지 않는다. unique constraint는 즉시 중복 검사가 필요하므로 미룰 수 없다. primary key에도 당연히 안 붙는다. 즉 non-unique secondary index만 혜택을 본다.

같은 이유로 full-text index, spatial index 등 특수 인덱스 유형도 change buffer 대상이 아니다. 결과적으로 혜택을 보는 구간은 "non-unique B-tree secondary index" 한 가지로 좁혀진다. 실제 인덱스 구성에서 이 조건을 만족하는 비율이 생각보다 크지 않은 경우가 많다.

둘째, SSD에서는 득실이 뒤집힌다. change buffer의 존재 이유는 "랜덤 IO가 비싼 HDD"를 전제로 한다. SSD·NVMe에서는 랜덤 IO가 순차 IO와 거의 같은 비용이고, 대신 merge 시점에 한꺼번에 쏟아지는 IO 스파이크가 p99 레이턴시를 망친다. 8.0 기본값은 innodb_change_buffer_max_size=25(버퍼 풀의 25%까지), innodb_change_buffering=all. SSD 환경에서는 innodb_change_buffering='none'을 진지하게 검토할 만하다. "쓰기가 빠르다"는 이득보다 "예측 가능한 쓰기"가 더 값질 수 있다.

관측은 SHOW ENGINE INNODB STATUS의 INSERT BUFFER AND ADAPTIVE HASH INDEX 섹션이다. ibuf: size N, free list len M, seg size K로 change buffer 사용량이 보이고, merged operations와 discarded operations 카운터로 merge 효율을 볼 수 있다. size가 꾸준히 커지는데 merge가 적게 일어나면 "빚이 쌓이고 있다"는 신호다.

2-4) instance 분할 — 1GB 임계와 mutex contention

여기서 틀리기 쉽다. "버퍼 풀을 크게 잡을수록 좋다"는 명제는 instance 분할 없이는 틀린다. 버퍼 풀은 단일 mutex로 보호되는 구조였고, 여러 스레드가 동시에 페이지 할당·eviction을 하면 이 mutex가 병목이 된다. 해결책이 innodb_buffer_pool_instances로 여러 풀로 쪼개는 것이다.

공식 문서의 규칙은 이렇다 — 버퍼 풀 총 크기가 1GB 이상이면 instance가 자동으로 8개로 분할된다. 1GB 미만은 instance 1개. 즉 256MB로 잡아 두고 "쪼개져 있겠지" 가정하면 틀린다. 하나의 mutex 위에서 전부 경합한다. 128GB 서버에 버퍼 풀 96GB를 잡는다면 innodb_buffer_pool_instances=16 혹은 32로 명시적으로 키우는 것이 표준이다. 각 instance 크기가 1GB 미만으로 떨어지지 않도록 하는 선에서 결정한다.

instance는 페이지의 해시 기반으로 분배된다. 즉 특정 테이블이 특정 instance에만 몰리지 않고 전 instance에 고르게 분산된다. 따라서 instance를 늘리면 mutex 경합은 줄지만, 특정 워크로드에서 특정 instance가 뜨거워지는 현상은 발생하지 않는다. instance별 사용률을 확인하고 싶다면 information_schema.innodb_buffer_pool_stats를 POOL_ID로 조회한다.

설정	권장	메모
버퍼 풀 크기	RAM 50~75%	O_DIRECT 전제
`innodb_buffer_pool_instances`	1GB 이상 자동 8	instance당 최소 1GB
`innodb_old_blocks_pct`	37 (기본)	full scan 내성 ↑ 시 낮춤
`innodb_old_blocks_time`	1000ms	배치 섞이면 5000ms 검토
`innodb_adaptive_hash_index`	ON (기본)	AHI latch 경합 시 OFF
`innodb_change_buffering`	`all`	SSD는 `none` 검토

2-5) flush list와 dirty ratio

버퍼 풀을 LRU로만 이해하면 쓰기 경로의 관측 지표를 놓친다. 버퍼 풀 내부에는 두 개의 리스트가 공존한다 — LRU list(hot/cold 관리)와 flush list(dirty 페이지를 LSN 오름차순으로 이어 둔 체인). 한 페이지가 변경되면 LRU에 있는 상태 그대로 flush list에도 끼워 넣어진다. page cleaner thread는 flush list의 꼬리(가장 오래된 LSN)부터 내려가면서 디스크에 써 내린다.

dirty 비율을 조절하는 두 다이얼이 있다.

innodb_max_dirty_pages_pct=90 (기본) — 버퍼 풀에서 dirty 페이지가 이 비율을 넘으면 aggressive flush가 들어간다.
innodb_max_dirty_pages_pct_lwm=10 — low water mark. 이 비율을 넘는 순간부터 preflush가 시작되어 조금씩 내려보낸다.

관측은 SHOW ENGINE INNODB STATUS의 BUFFER POOL AND MEMORY 섹션 Modified db pages 라인으로 본다. 이 값이 총 페이지 수의 10%를 넘어가는 타이밍이 preflush 시작점과 맞아떨어지는지 확인하면 디스크 서브시스템이 버텨내고 있는지 감이 잡힌다.

한 번 더 정리해 두면 — LRU list는 "메모리에 남겨 둘 페이지"를 고르고, flush list는 "디스크에 내려보낼 dirty 페이지"를 고른다. 두 리스트는 같은 페이지 집합을 다른 기준으로 정렬한 것이고, page cleaner thread는 flush list만 본다. 이 두 축을 분리해 이해해야 "dirty ratio가 높은데 왜 cache hit은 여전히 좋은가" 같은 질문이 자연스럽게 풀린다.

버퍼 풀 구조를 잡았으니 쓰기 경로의 첫 번째 로그로 간다.

3) redo log: group commit 1층과 flush 전략

InnoDB의 redo log는 "커밋된 트랜잭션이 crash 후에도 살아 있음"을 보장하는 첫 번째 축이다. PG의 WAL과 역할이 같다. 트랜잭션이 commit하면 redo 레코드가 디스크에 fsync되고, 데이터 페이지는 나중에 lazy하게 내려간다. PG WAL은 FPW로 partial write까지 방어하지만, InnoDB redo는 그 책임을 doublewrite에 넘긴다. 그래서 redo 자체는 논리 변경만 기록하는 얇은 로그다.

3-1) redo log 파일 — 8.0.30 이후 통합 파라미터

MySQL 8.0.30 이전에는 innodb_log_file_size × innodb_log_files_in_group으로 redo 총 용량을 계산했다. 8.0.30+부터 이 둘이 innodb_redo_log_capacity 하나로 통합되었고 이전 두 파라미터는 deprecated다. 기본값은 100MB. 운영에서는 거의 항상 올려야 하는 값이다. 쓰기 TPS가 높은 환경에선 1~8GB 수준으로 잡는다. redo가 작으면 checkpoint가 자주 강제되고, 자주 강제되면 dirty 페이지 flush 스파이크가 튄다.

8.0.30 이전 방식에서 올라오는 경우 주의할 점이 있다. innodb_log_file_size와 innodb_log_files_in_group을 설정한 채로 업그레이드하면 경고 로그가 남고 값이 무시된다. 마이그레이션 스크립트에서 이 두 파라미터를 걷어내고 innodb_redo_log_capacity로 교체해야 한다.

redo 파일은 디스크에서 ring buffer처럼 돈다. capacity를 다 쓰면 앞쪽으로 돌아가 덮어쓰고, 덮어쓰기 전에 해당 구간 LSN까지의 dirty 페이지가 반드시 디스크에 내려가 있어야 한다. 즉 redo 크기는 checkpoint 간격과 직결된다.

내부 구조는 32개의 redo 파일로 쪼개져 있다. 파일명은 #ib_redo0, #ib_redo1, ... 순이다. innodb_redo_log_capacity를 변경하면 파일 개수와 크기를 자동으로 재배치한다. 8.0.30 이전의 innodb_log_file_size 방식과 달리 재시작이 필요 없어 런타임에 사이징 조정이 가능해진 점이 실무 관점에서 가장 큰 개선이다.

3-2) `innodb_flush_log_at_trx_commit` — 0/1/2의 실제 의미

이 파라미터는 MySQL 튜닝 가이드에 가장 자주 등장하면서 가장 자주 오해받는다. 세 값의 동작이 완전히 다르다.

값	fsync 타이밍	mysqld crash 손실	OS crash 손실	권장 환경
`1` (기본, ACID)	매 커밋 write + fsync	0	0	금융·ACID 필수
`2`	매 커밋 write, 1초마다 fsync	0	최대 1초	일반 OLTP
`0`	master thread가 1초마다 write+fsync	최대 1초	최대 1초	로그성 데이터

핵심은 2의 의미다. =2는 "OS crash만 1초 손실"이다. 매 커밋마다 redo가 OS 페이지 캐시까지는 반드시 write되므로, mysqld 프로세스가 crash해도 데이터는 OS에 남아 있고 자동 복구된다. 1초 손실이 발생하는 경우는 오직 OS/커널/하드웨어 레벨 crash뿐이다. 전원 차단, 커널 panic, VM 강제 종료 같은 드문 이벤트다. 대부분의 일반 OLTP에서 2는 충분히 현실적인 선택이 된다.

반면 =0은 커밋 자체가 redo write를 하지 않고 백그라운드 스레드가 1초마다 묶어서 write+fsync한다. mysqld crash로도 1초가 날아간다. 정말 "로그 테이블" 류가 아니면 쓰지 않는다.

벤치마크 상의 차이는 스토리지와 동시성에 따라 크게 갈린다. 높은 동시성 OLTP에서 1과 2의 성능 차이는 group commit 덕분에 체감 미미할 수 있지만, 저동시성 단일 연결 커밋 루프에서는 2가 1의 3~5배 처리량을 보이는 경우도 있다. "무조건 1이 맞다"가 아니라 워크로드와 지속성 SLA를 함께 보고 결정한다.

3-3) group commit 1층 — redo log buffer 묶기

redo log buffer(innodb_log_buffer_size, 기본 16MB)는 여러 트랜잭션의 redo 레코드를 하나의 fsync에 묶어 내려보내는 구조다. 이게 "group commit 1층"이다. 동시 연결 N개가 거의 동시에 커밋하면, 리더 하나가 fsync를 호출하고 나머지는 그 fsync가 끝날 때까지 대기했다가 "이미 내가 쓴 LSN까지 내려갔으니 OK"로 반환받는다. 커밋 처리량이 동시성에 따라 선형 이상으로 올라가는 이유다.

다만 함정이 있다. group commit의 TPS 회복 효과는 동시 커밋이 충분히 있어야 성립한다. 직렬 배치처럼 한 스레드가 순차적으로 커밋하는 워크로드에서는 묶을 상대가 없으므로 매 커밋이 독립 fsync를 친다. "group commit 켜면 빨라진다"는 기대는 고동시 OLTP 조건부 명제다.

3-4) checkpoint와 flush 다이얼

redo 크기를 키우고 trx_commit을 조율하는 것만으로는 부족하다. dirty 페이지가 디스크로 내려가는 속도 자체를 조절하는 네 개의 다이얼이 있다. §3-2의 trx_commit 표와 역할이 겹치지 않는다 — 그쪽은 "커밋 시점 redo fsync"이고, 이쪽은 "page cleaner가 테이블 페이지를 디스크에 내려쓰는 속도"다.

파라미터	기본값	의미
`innodb_io_capacity`	200	초당 I/O 기준선 (HDD 기준)
`innodb_io_capacity_max`	2000	aggressive flush 시 상한
`innodb_flush_neighbors`	0 (SSD) / 1	인접 페이지 동시 flush, SSD는 0 권장
`innodb_lru_scan_depth`	1024	LRU tail에서 flush할 수 있는 깊이

io_capacity는 "page cleaner가 정상 상태에서 쓸 수 있는 IOPS"의 기준이다. 2020년 이후의 NVMe라면 기본 200은 턱없이 낮다. 2000~10000 범위에서 스토리지 스펙을 보고 잡는 것이 현실이다. io_capacity_max는 dirty ratio가 상한에 가까워지면 달려 들어가는 aggressive flush의 천장이다.

fuzzy checkpoint라는 이름을 붙여 두면 이해가 쉽다. Oracle이나 초창기 DB들이 주기적으로 전체 flush를 하던 방식과 달리, InnoDB는 page cleaner thread가 flush list 꼬리를 지속적으로 조금씩 내려보낸다. 한 번에 폭포처럼 쏟아지지 않으므로 IO 스파이크가 줄어든다.

PG와 대비하면 설계 철학 차이가 선명하다. PG는 checkpointer가 checkpoint_completion_target에 맞춰 spread write로 한 번의 checkpoint를 펼쳐 쓰는 방식이고, InnoDB는 page cleaner thread가 상시로 조금씩 내려 쓰는 방식이다. 둘 다 스파이크 회피라는 같은 목표에 도달했지만, 큐잉 모델이 다르다.

innodb_flush_neighbors는 HDD 시절의 유산 중 하나다. HDD에서는 인접 페이지를 함께 쓰면 seek 비용이 한 번으로 줄어들어 이득이지만, SSD에서는 오히려 write amplification을 만든다. 8.0 기본값은 스토리지 감지에 따라 자동 조정되지 않으므로, innodb_flush_neighbors=0을 SSD 환경에서는 명시적으로 설정하는 것이 안전하다. innodb_lru_scan_depth도 비슷한 맥락으로, 버퍼 풀 instance 수가 많아질수록 instance별 스캔 깊이가 곱해지므로 기본 1024를 절반으로 낮춰도 되는 환경이 있다.

3-5) redo capacity 사이징

innodb_redo_log_capacity는 단순히 "로그 파일 크기"가 아니라 checkpoint 간격의 지렛대다.

크게 올리면 checkpoint가 덜 자주 강제되고, dirty 페이지가 더 오래 메모리에 머문다. 같은 페이지의 여러 변경이 한 번의 디스크 쓰기로 합쳐지므로 쓰기 처리량이 올라간다.
대가는 crash recovery 시간이다. redo 재적용량이 비례해 늘어난다. 32GB redo를 full로 채운 상태에서 crash가 나면 복구에 수 분이 걸릴 수도 있다.

운영 권장은 워크로드에 따라 다르다. 일반 OLTP는 1~4GB, 쓰기 무거운 워크로드는 8~32GB 범위에서 결정한다. 8.0.30+의 핫 변경 덕분에 다시 시작 없이 조절할 수 있으므로 작게 시작해 관측하며 올리는 순서가 안전하다. SHOW ENGINE INNODB STATUS의 LOG 섹션 Log sequence number와 Last checkpoint at 차이가 capacity에 근접해 있다면 checkpoint가 빡빡하다는 신호다.

판단 흐름은 이런 순서가 된다. 먼저 Innodb_os_log_written의 증가 속도를 측정해서 1분당 redo 생성량을 계산한다. capacity가 그 값의 10~30배를 수용할 수 있는 크기면 충분하다. capacity가 너무 작아 checkpoint가 자주 강제되면 Innodb_buffer_pool_wait_free가 치솟으며 커밋 레이턴시가 요동친다. 이 지표가 0이 아닌 순간이 있다면 redo를 먼저 키우는 것이 거의 항상 답이다.

4) doublewrite buffer: partial page write 방어선

InnoDB가 OS를 믿지 않는 가장 직관적인 증거가 doublewrite buffer다. 설계 전제는 이것이다. "OS나 디스크가 16KB 페이지 쓰기 중간에 죽으면, 일부분만 쓰여서 페이지가 썩을 수 있다." 이게 partial page write(또는 torn page)다. redo log가 논리 변경만 담고 있기 때문에, 물리 페이지가 깨져 있으면 redo만으로 복구할 수 없다. 그래서 페이지를 실제 테이블스페이스에 쓰기 전에 먼저 doublewrite 영역에 순차 기록한다. crash 복구 시 doublewrite의 사본으로 테이블스페이스 페이지를 복원한 뒤 redo를 재생한다.

4-1) 8.0.20 이후 분리된 파일

8.0.20 이전에는 doublewrite 영역이 시스템 테이블스페이스(ibdata1) 안에 있었다. 8.0.20+부터는 별도 파일로 분리되었다 — #ib_16384_0.dblwr, #ib_16384_1.dblwr 같은 이름이다. 분리 덕분에 doublewrite IO를 별도 디스크로 배치할 수 있고, 파일 자체가 순차 쓰기만 하므로 IO 패턴이 단순하다.

관련 파라미터로 innodb_doublewrite_dir(파일 경로), innodb_doublewrite_files(파일 개수, 기본 buffer pool instance 수), innodb_doublewrite_pages(파일당 페이지 수, 기본 innodb_write_io_threads × 128)가 있다. 운영에서는 거의 건드리지 않지만, doublewrite IO를 전용 NVMe로 분리해 p99 레이턴시를 더 낮추고 싶은 경우 innodb_doublewrite_dir만 바꿔 마운트 포인트를 변경한다.

4-2) 오버헤드 — NVMe 5~10%, HDD 최대 30%

doublewrite는 공짜가 아니다. 같은 페이지를 두 번 쓴다. 이론상 쓰기량이 2배가 된다. 현실적인 오버헤드는 스토리지에 따라 크게 다르다. "2배"라는 숫자는 단순화된 표현이고, 실제로는 doublewrite 쓰기가 순차 패턴이라 절대 시간상 2배로 늘어나지는 않는다.

스토리지	오버헤드	메모
NVMe SSD	약 5~10%	순차 write 특성으로 저렴
SATA SSD	약 10~15%
HDD	최대 20~30%	랜덤 seek 비중에 민감
atomic write 지원 스토리지	꺼도 됨	`innodb_doublewrite=OFF` 수동

이 수치는 벤치마크마다 편차가 있다. write-heavy sysbench oltp_write_only에서 측정한 평균이고, 워크로드가 read-heavy면 오버헤드는 더 낮다 — 쓰기 자체가 드물기 때문. 반대로 대량 bulk insert 지배적이면 NVMe에서도 15% 내외까지 올라간다.

마지막 행이 중요하다. Fusion-io, ScaleFlux, 일부 엔터프라이즈 NVMe는 하드웨어 레벨에서 atomic write(16KB 단위)를 보장한다. 이 경우 partial write 자체가 발생하지 않으므로 doublewrite를 꺼도 안전하다. 단 기본값은 ON이고, 끄는 건 스토리지 펌웨어를 검증한 뒤 명시적으로 선택해야 한다. "SSD니까 꺼도 되지 않나"는 일반 소비자 SSD에는 적용되지 않는다.

4-3) 오해 정리 — doublewrite는 무결성 전능이 아니다

여기서 틀리기 쉽다. doublewrite는 partial page write만 방어한다. 비트 플립, 스토리지 펌웨어 버그, bit rot은 막지 못한다. 이 영역은 innodb_checksum_algorithm=crc32(기본)의 체크섬 검증, 그리고 스토리지 레이어의 ECC/ZFS/Btrfs 같은 파일시스템 체크섬이 담당한다. doublewrite는 "쓰는 도중 전원이 나가도 페이지가 반쪽짜리로 남지 않는다"는 매우 특정한 보장일 뿐이다.

4-4) atomic write 검증 체크리스트

"SSD니까 doublewrite 꺼도 되지 않나"는 검증 없이는 자살 행위다. atomic write를 신뢰하려면 네 레이어 모두가 16KB 단위 원자성을 명시해야 한다.

스토리지 펌웨어 — 제조사 문서에 "atomic write 16KB"가 명시되어 있는가. Fusion-io, ScaleFlux, 일부 엔터프라이즈 NVMe가 여기에 해당한다. 일반 소비자 SSD에는 명시가 없다.
파일시스템 alignment — xfs/ext4에서 4KB 또는 16KB block alignment가 InnoDB 페이지 경계와 맞아야 한다. mkfs 시 -b 4096·su=16384 같은 옵션 점검.
커널/드라이버 지원 — nvme-cli id-ns 출력에서 atomic write unit을 확인. 일부 드라이버는 atomic 보장을 그대로 노출하지 않는다.
MySQL 플래그 — innodb_use_fdatasync=ON(8.0.26+)과 innodb_flush_method=O_DIRECT의 조합이 의도대로 동작하는지 점검. 둘을 섞을 때 파일시스템 별로 동작이 다르다.

그리고 프로덕션 전에 반드시 두 시나리오를 테스트한다 — **kill -9 mysqld**와 전원 차단(ipmi power off). 둘 다 돌린 뒤 SELECT ... CHECK TABLE과 innochecksum으로 partial write가 하나도 없는지 검증하고 나서야 innodb_doublewrite=OFF를 논의할 자격이 생긴다. 반복 횟수도 중요하다 — 한두 번 돌려서 깨지지 않았다고 안심할 수 없고, 최소 수십 회의 강제 종료 하에서도 innochecksum 경고가 0이어야 한다.

doublewrite로 물리 페이지 무결성을 막았으니, 논리 레벨의 MVCC를 지탱하는 undo로 넘어간다.

5) undo tablespace와 purge thread

InnoDB의 MVCC는 PG와 같은 원리지만 구현이 다르다. PG가 heap에 dead tuple을 쌓고 VACUUM이 청소하듯, InnoDB는 undo에 이전 이미지를 쌓고 purge thread가 회수한다. 차이는 "어디에 쌓느냐"다. PG는 테이블 자체(heap)에 이전 버전과 새 버전을 나란히 두고, InnoDB는 테이블에는 최신 버전만 두고 undo log에 이전 이미지를 분리해 쌓는다. 그래서 InnoDB 테이블은 bloat가 덜 보이고, 대신 long-running transaction이 있으면 undo가 무한히 자란다.

이 분리 덕분에 InnoDB는 secondary index에 MVCC 포인터를 직접 심지 않아도 된다. secondary index는 PK만 가리키고, PK row에서 undo 체인을 따라가 올바른 버전을 찾는다. 대가는 secondary index로 조회할 때 한 번 더 lookup이 발생한다는 점이다. 이 비용이 쌓이면 "왜 PK 조회는 빠른데 secondary index 조회는 느린가"라는 질문의 답이 된다.

5-1) undo tablespace — 8.0부터 독립 파일

8.0부터 undo는 시스템 테이블스페이스에서 완전히 분리되어 undo_001, undo_002라는 독립 파일 두 개로 기본 제공된다. CREATE UNDO TABLESPACE로 추가도 가능하고, 별도 디스크에 배치할 수도 있다. rollback segment는 innodb_rollback_segments=128(기본)개로 쪼개져 있어 동시성 경합을 줄인다.

undo 전용 디스크를 분리하는 전략도 선택지다. 쓰기 지배적인 워크로드에서는 undo write가 redo와 함께 가장 무거운 IO 소비자다. ALTER TABLESPACE innodb_undo_001 SET INACTIVE로 비활성화한 뒤 별도 경로의 undo tablespace를 추가하면 IO 경합을 분산할 수 있다. 작업 중 undo가 모두 차단되지 않도록 최소 3개 이상의 undo tablespace를 유지하는 것이 안전하다.

5-2) purge thread — MVCC 가비지 수집

innodb_purge_threads=4(기본)가 undo에 쌓인 구 이미지 중 어떤 트랜잭션도 더 이상 보지 않는 것을 회수한다. "더 이상 보지 않는" 판정은 현재 살아 있는 가장 오래된 read view의 시작 시점을 기준으로 한다. 이게 핵심이다. 한 세션이 REPEATABLE READ 아래서 트랜잭션을 열고 몇 시간째 커밋도 롤백도 안 하면, purge는 그 세션의 read view 시작 시점 이후 생성된 모든 undo를 회수할 수 없다. undo가 끝없이 자라는 유명한 안티패턴이다.

READ COMMITTED 격리 수준에서는 read view가 매 문장마다 새로 잡힌다. 그래서 RC에서는 long-running transaction이 있어도 purge 차단이 RR보다 약하다. 이 점도 MySQL 8.0 기본 격리 수준이 RR이라는 사실과 맞물려, "왜 우리 시스템이 undo로 고생하는가"의 간접 답이 된다.

PG의 VACUUM이 오래된 트랜잭션에 막히면 dead tuple이 안 정리되는 것과 같은 구조다. 엔진은 달라도 MVCC 청소를 막는 원인은 동일하다 — 오래 살아 있는 트랜잭션.

purge thread 개수를 늘리는 것만으로는 근본 원인이 풀리지 않는다. innodb_purge_threads를 4에서 32로 올려도, purge가 회수할 수 없는 undo는 그대로다. purge thread는 오로지 "read view에 가려지지 않은" undo만 지울 수 있다. long-running transaction 하나가 read view를 잡고 있는 한, 그 이후 생성된 모든 undo는 스레드를 아무리 늘려도 못 지운다.

5-3) undo truncate — 8.0 기본 ON

8.0부터 innodb_undo_log_truncate=ON이 기본이다. innodb_max_undo_log_size=1GB(기본)를 넘은 undo tablespace가 감지되면, purge가 끝난 영역을 잘라내는 truncate 작업이 비동기로 돈다. 그 사이 해당 undo tablespace는 일시적으로 사용 중단된다. 그래서 기본 undo tablespace가 최소 2개인 것이다 — 하나가 truncate되는 동안 다른 하나가 계속 쓰기를 받는다.

truncate가 자주 발생하면 워크로드가 정상 purge 속도를 초과하는 쓰기 부하를 만들고 있다는 뜻이다. innodb_purge_threads를 기본 4에서 8~16으로 올리는 것이 1차 대응이지만, 더 중요한 진단은 "왜 undo가 자라는가"다. 장기 트랜잭션이 없는데도 undo가 자라면 단순 쓰기량이 문제이므로, 배치 작업의 청크 크기나 인덱스 갱신 패턴을 점검한다.

관측창은 SELECT * FROM INFORMATION_SCHEMA.INNODB_TABLESPACES WHERE NAME LIKE 'innodb_undo%'. undo 파일 크기가 의심스럽게 오래 크게 유지되면, information_schema.innodb_trx에서 trx_started가 오래된 트랜잭션을 찾는 것이 첫 수사다.

5-4) history list length 관측

undo가 자라는 현상을 수치로 잡는 가장 빠른 지표가 history list length다. purge가 아직 회수하지 못한 undo 레코드 개수를 직접 센다.

-- 방법 1: STATUS 텍스트
SHOW ENGINE INNODB STATUS;
-- TRANSACTIONS 섹션에서 "History list length 20" 라인

-- 방법 2: metrics 테이블
SELECT NAME, COUNT
  FROM information_schema.innodb_metrics
 WHERE NAME='trx_rseg_history_len';

임계치의 감은 이렇다. 평상시 수천~수만 수준은 정상이다. 10만 이상이면 purge가 따라오지 못하거나 long-running transaction이 의심되는 단계로, 모니터링 경보를 건다. 100만 이상이면 즉시 information_schema.innodb_trx에서 trx_started가 가장 오래된 세션을 찾아 끊어야 한다.

흔한 오해 하나 — "락이 없으면 undo도 쌓이지 않겠지"는 틀렸다. read view가 열린 동안에는 metadata lock이나 row lock이 없어도 undo가 purge되지 않는다. SELECT만 치고 커밋하지 않는 세션, BI 툴이 장시간 결과를 붙잡고 있는 세션이 그 주범이다. innodb_trx에 trx_state='RUNNING'인데 trx_rows_locked=0인 세션이 있다면 바로 이 패턴이다.

한 발 더 나간 수사가 필요하면 performance_schema.events_transactions_current와 events_statements_history를 조인해 "언제 어떤 쿼리로 시작된 트랜잭션인지"까지 역추적한다. 커넥션 풀의 idle 세션이 무심코 트랜잭션을 열어 둔 채 돌아오지 않는 경우가 가장 흔한 범인이고, 앱 레이어의 autocommit=false + 예외 처리 누락 조합이 원인일 때가 많다. DB 튜닝이 아니라 앱 코드를 고쳐야 해결되는 문제인 경우가 대부분이다.

6) binlog와 2PC: group commit 2층

binlog는 MySQL 서버 레이어의 로그다. 엔진 중립 포맷이라 복제·PITR(point-in-time recovery)·감사에 쓰인다. InnoDB redo가 엔진 내부 복구용이라면, binlog는 외부 소비자(replica, CDC, 백업)를 위한 공개 로그다. §1-3 binlog가 서버 레이어에 있는 이유에서 말한 대로 이 분리 때문에 2PC가 필요하다.

한 번 더 짚으면 — redo는 물리 로그에 가깝다. 어떤 페이지의 몇 바이트 오프셋에서 무엇이 바뀌었다는 기록이다. binlog는 논리 로그다. 어떤 테이블의 어떤 행이 어떤 값으로 바뀌었다는 기록이다. 물리 로그는 해당 엔진·해당 버전에서만 재생 가능하고, 논리 로그는 엔진과 버전을 넘어 재생 가능하다. 두 로그의 성질 차이가 2PC의 필요성을 만든다.

6-1) 2PC 순서 — prepare, binlog, commit

내부 2PC의 순서가 정해져 있다.

InnoDB prepare — redo에 prepare 레코드 write + fsync. 이 시점에 트랜잭션은 "커밋 가능" 상태.
binlog write + fsync — sync_binlog=1(기본)이면 여기서 fsync. binlog에 들어간 순간이 복제 순서의 기준.
InnoDB commit — redo에 commit 레코드 추가. 메모리 상태 전환. (이 단계는 별도 fsync 안 함)

recovery 시 판정 규칙은 이렇다. redo에 prepare는 있는데 commit은 없고 binlog에 있다면 → 커밋 재생. redo에 prepare는 있는데 binlog에 없다면 → 롤백. 이 판정 덕분에 redo와 binlog의 "같은 트랜잭션 집합"이 crash 이후에도 일치한다.

commit 레코드의 지속성 경로를 한 번 더 짚어 둔다. prepare 단계에서 이미 redo에 prepare 레코드가 기록되어 fsync까지 내려가 있고, commit 레코드는 다음 redo flush 주기에 같이 나간다. crash 시 binlog에 해당 트랜잭션이 있으면 redo commit을 재주입해 복구한다. 즉 3단계의 마지막 InnoDB commit이 별도 fsync를 치지 않아도 안전한 이유는, "prepare 레코드의 fsync + binlog의 fsync + 판정 규칙"이 지속성과 원자성을 이미 확보했기 때문이다.

이 순서를 거꾸로 놓고 "왜 binlog fsync가 redo commit fsync보다 먼저인가"를 묻는 사람이 있다. 답은 단순하다. binlog가 복제의 기준점이기 때문이다. binlog에 들어가지 않은 트랜잭션은 존재하지 않은 것과 같고, binlog에 들어간 트랜잭션은 반드시 primary와 replica 모두에서 커밋 상태로 수렴해야 한다. 그래서 binlog fsync가 진실의 기준이 되고, redo commit은 그 뒤를 따른다.

한 가지 더 — 이 2PC는 내부 XA다. 외부에서 XA START로 시작하는 분산 트랜잭션과는 별개이고, 서버가 클라이언트에게 노출하지 않는다. MySQL 내부에서 엔진 레이어와 서버 레이어(binlog)를 조율하는 용도로만 쓰이고, 복구 알고리즘도 내부용이다. 외부 XA는 별도의 오버헤드와 제약이 있으므로 혼동하지 말 것.

6-2) group commit 2층 — FLUSH/SYNC/COMMIT 단계

여기가 MySQL 복제 튜닝의 핵심이다. 2PC 안에서 binlog write는 3단계 파이프라인으로 돈다.

FLUSH stage — 커밋하려는 트랜잭션들을 큐에 모아 한 리더가 binlog 버퍼에 일괄 기록.
SYNC stage — 리더가 fsync 1회로 큐에 묶인 N개 트랜잭션의 binlog를 한꺼번에 디스크에 내린다.
COMMIT stage — 리더가 엔진 commit을 순서대로 호출.

이게 "group commit 2층"이다. 1층(redo)과 2층(binlog)이 각각 group commit을 돌려서 fsync 비용을 묶는다. sync_binlog=1 + innodb_flush_log_at_trx_commit=1(둘 다 기본값)이 "커밋마다 fsync 2번"처럼 보이지만 실제로는 고동시 OLTP에서 fsync당 트랜잭션 수가 수십~수백 개로 묶이므로, 평균 commit 레이턴시는 단일 fsync 수준에 머무른다.

묶음 크기는 두 변수로 조절한다 — binlog_group_commit_sync_delay(μs)와 binlog_group_commit_sync_no_delay_count. 전자는 "SYNC stage에 진입하기 전 몇 마이크로초를 기다려 더 모을까"를, 후자는 "이 개수를 채우면 delay를 기다리지 않고 즉시 묶어 낸다"를 의미한다. 둘 다 기본 0이고 대부분의 환경에서 기본 그대로가 낫다. 평균 커밋 레이턴시를 몇 μs 희생해서 fsync 횟수를 극단적으로 줄이고 싶은 쓰기 폭주 환경에서만 건드린다.

관측창은 performance_schema.events_stages_history_long에서 stage별 누적 시간을 보는 것이다. SYNC stage의 평균 시간이 1ms를 넘는다면 스토리지의 fsync 레이턴시 자체가 문제이거나, sync_binlog를 1보다 크게 잡아 여러 트랜잭션을 누적한 뒤 fsync하도록 전환하는 옵션이 있다 (sync_binlog=N은 N개 커밋마다 한 번만 fsync). 금융권 외에는 100이나 1000이 현실적인 선택이 된다.

다시 강조 — group commit의 효과는 동시성 조건부다. 직렬 배치 스크립트 하나가 5천만 행을 커밋별로 insert하는 경우에는 2층 모두에서 묶을 상대가 없고, 매 커밋이 fsync 2회를 그대로 친다. 이 패턴을 만나면 autocommit=0으로 묶어서 한 트랜잭션으로 commit 횟수를 줄이거나, innodb_flush_log_at_trx_commit=2/sync_binlog=0으로 내려가는 선택이 현실이다.

6-3) binlog 사이징과 rotation

binlog는 지워주지 않으면 디스크를 끊임없이 먹는다. 사이징과 rotation 정책을 기본값 그대로 두면 디스크 가득참 장애가 예정된 순서로 찾아온다.

파라미터	기본값	의미
`max_binlog_size`	1GB	파일 1개 최대 크기. 초과 시 새 파일로 rotate
`binlog_expire_logs_seconds`	2592000 (30일)	만료 시간. 지나면 자동 purge
`binlog_cache_size`	32KB	트랜잭션별 in-memory binlog 버퍼

rotation은 두 조건 중 먼저 도달하는 쪽에서 발생한다 — 크기 초과 또는 FLUSH BINARY LOGS 같은 명시 호출. 파일 하나가 가득 차면 번호가 붙은 다음 파일로 끊어진다 (mysql-bin.000123 → mysql-bin.000124).

binlog_cache_size는 트랜잭션이 커밋 전까지 binlog 이벤트를 들고 있는 메모리 버퍼다. 이 크기를 넘어서는 큰 트랜잭션은 tmpfs·디스크로 swap된다 (binlog_stmt_cache_disk_use 카운터로 관측). 대량 INSERT·대용량 DML이 자주 돌면 4MB~16MB로 키우는 것이 현실적이다.

만료 정책은 PITR(point-in-time recovery)의 소급 범위를 그대로 결정한다. 너무 짧게 잡으면 30일 전 장애를 되돌릴 수 없고, 너무 길게 잡으면 디스크를 과하게 차지한다. 조직의 RTO/RPO와 백업 주기에 맞춰 7일~30일 범위에서 정하는 것이 보통이다.

replica가 살아 있는지도 고려해야 한다. replica가 아직 읽지 않은 binlog 파일은 expire 대상에서 제외되지만, GTID 기반 복제에서 replica가 오랫동안 끊겨 있다가 다시 붙으려 할 때 필요한 binlog가 이미 만료되어 있으면 복제를 재구성해야 한다. 장애 복구 절차 설계 시 binlog_expire_logs_seconds와 replica의 최장 허용 중단 시간이 함께 고려되어야 한다.

운영 체크리스트 한 줄 — SHOW BINARY LOGS로 현재 파일 수와 총 크기를 주기적으로 관측하고, Binlog_cache_disk_use 카운터가 증가하는지 확인한다. 이 카운터가 꾸준히 오르면 binlog_cache_size가 작다는 직접 증거이므로 4MB~16MB 범위로 올린다.

6-4) binlog_format — ROW가 기본

binlog는 세 포맷이 있다. MySQL 5.7.7+ 기본이 ROW이고, 8.0.34+부터 binlog_format 변경 자체가 deprecated되었다. 사실상 ROW만 쓴다.

"Row-based logging is the default method."

— MySQL 8.0 Reference Manual §19.2.1 Replication Formats

포맷	기록 대상	장점	단점
ROW (기본)	변경된 행 이미지	비결정 함수 안전, 정확	binlog 크기 ↑
STATEMENT	실행된 SQL	binlog 작음	`NOW()`·AUTO_INCREMENT 등 비결정 문제
MIXED	상황에 따라 자동 선택	절충	8.0.34+ deprecated

비결정 함수 하나만 봐도 ROW의 선택이 정당해진다. UPDATE t SET ts = NOW() WHERE ...를 STATEMENT로 찍으면 replica가 재생할 때 NOW()가 다른 시각으로 평가되어 데이터가 어긋난다. ROW는 변경 후 행 이미지 자체를 기록하므로 재생이 결정적이다.

ROW의 트레이드오프는 binlog 용량이다. UPDATE 한 줄이 100만 행을 고치면 STATEMENT는 SQL 한 줄이지만 ROW는 100만 행의 before/after 이미지가 모두 들어간다. binlog_row_image=minimal(기본은 full)을 쓰면 before는 PK만, after는 변경 컬럼만 기록해 용량을 크게 줄일 수 있지만, CDC 소비자(Debezium 등)가 before full image를 요구하는 경우가 많아 운영에서는 full 또는 noblob 조합이 현실적이다.

압축 옵션도 있다. binlog_transaction_compression=ON(8.0.20+)을 켜면 트랜잭션 단위로 ZSTD 압축이 적용되어 binlog 크기가 체감 30~60% 줄어든다. 네트워크 복제 대역폭과 디스크 모두에서 이득을 보는데, 대신 replica 쪽 CPU가 압축 해제로 약간 올라간다. 일반 OLTP에서는 켜 두는 것이 거의 항상 이득이다.

6-5) 병렬 복제 — WRITESET + preserve_commit_order

binlog 이야기의 마지막 축은 replica의 병렬 적용이다. 기본 replica는 binlog를 단일 스레드로 재생한다. 병렬화 없이는 write-heavy primary를 replica가 못 쫓아간다. 8.0에서 두 다이얼이 궁합을 이룬다.

binlog_transaction_dependency_tracking=WRITESET — primary가 binlog에 각 트랜잭션이 건드린 행 키 해시를 함께 기록한다. replica는 WRITESET이 겹치지 않는 트랜잭션끼리 동시 재생한다.
replica_preserve_commit_order=ON — 동시 재생하더라도 커밋 순서는 원본과 동일하도록 강제한다. read-your-writes 보장의 전제.

둘을 같이 켜야 한다. WRITESET만 켜면 순서가 뒤틀릴 수 있고, preserve_commit_order만 켜면 병렬성이 안 나온다. replica_preserve_commit_order는 8.0.26까지 기본 OFF였고, 8.0.27부터 기본 ON으로 전환됐다. 구체 기본값은 운영 전 버전별로 확인해야 한다.

병렬 복제 적용 스레드 수는 replica_parallel_workers=4(기본)로 잡혀 있다. write-heavy primary를 쫓아가는 replica라면 8~32 범위로 올린다. 스레드를 늘린 만큼 비례해 성능이 오르지는 않고, WRITESET 충돌 빈도에 따라 체감 상승분이 갈린다. performance_schema.replication_applier_status_by_worker에서 각 worker의 처리량을 비교하면 병렬성이 실제로 살아 있는지 관측할 수 있다.

7) 실무에서 이렇게 읽고 쓴다

연결 수가 수천 단위라면 OSS MySQL 단독으로 버티려 하지 말자. Community는 pool-of-threads가 없다. ProxySQL이나 앱 레이어 커넥션 풀러를 앞단에 두고, 그게 안 되면 Percona/MariaDB로 전환하는 게 현실적이다.
버퍼 풀은 크기보다 instance 수를 먼저 확인한다. 총 크기가 1GB 이상이면 자동 8 분할이지만, 수십 GB 규모에서는 innodb_buffer_pool_instances=16이나 32를 명시한다. 각 instance가 1GB 미만이 되면 안 된다.
SSD/NVMe에 올라간 MySQL은 innodb_change_buffering='none'을 한번 검토한다. merge 시점의 p99 스파이크가 기본값에서 자주 잡히면 끄는 편이 체감 안정성이 높다. 단, 쓰기 IOPS는 늘어난다.
일반 OLTP에서 innodb_flush_log_at_trx_commit=2는 충분히 합리적인 선택이다. "OS crash만 1초 손실"이라는 의미를 조직이 이해하고 있다면. 금융·결제는 1 고정.
doublewrite는 일반적으로 끄지 않는다. 엔터프라이즈 NVMe의 atomic write를 펌웨어·드라이버·파일시스템 단에서 검증한 경우에 한해 innodb_doublewrite=OFF를 논의한다. "SSD니까 꺼도 되겠지"는 안 된다.
undo가 자란다면 먼저 long-running transaction을 찾는다. SELECT trx_started FROM information_schema.innodb_trx ORDER BY trx_started LIMIT 5 한 줄이 대부분의 범인을 잡는다. purge thread를 올리기 전에 원인 트랜잭션을 끊는 게 먼저다.
복제 지연이 심한데 CPU는 놀고 있다면 WRITESET 병렬 복제를 확인한다. binlog_transaction_dependency_tracking=WRITESET + replica_preserve_commit_order=ON 조합이 켜져 있는지 SHOW REPLICA STATUS와 변수로 검증.
group commit 효과는 동시성이 있을 때만 체감된다. 직렬 배치 성능이 나쁘다고 redo/binlog를 원망하기 전에, 트랜잭션 경계부터 다시 본다. 100만 건을 1만 행씩 묶는 것만으로 fsync 수가 100배 준다.
dirty ratio 알람은 Modified db pages / buffer pool pages로 계산해 innodb_max_dirty_pages_pct_lwm(기본 10%)를 넘는 시점에 경보를 건다. 그 위로 장시간 머무르면 page cleaner 대비 쓰기 부하가 과다하다는 의미다. innodb_io_capacity를 먼저 의심한다.
**redo capacity가 너무 작은 증상은 Innodb_buffer_pool_wait_free > 0**이다. 이 카운터가 0이 아닌 구간이 있다면 innodb_redo_log_capacity를 2배로 올리는 것이 거의 항상 즉효다. 8.0.30+는 런타임 변경이라 다운타임이 없다.
binlog 디스크 가득참 장애는 binlog_expire_logs_seconds를 먼저 본다. 기본 30일이 무난하지만, write-heavy 샤드에서 max_binlog_size=1GB × 30일이면 수백 GB가 깔린다. 백업·PITR 범위와 맞춰 단축하거나, binlog 파티션을 별도 디스크로 분리한다.
history list length 10만은 경보, 100만은 긴급이다. trx_rseg_history_len 메트릭을 모니터링에 걸고, 임계 돌파 시 information_schema.innodb_trx 덤프를 자동 수집해 둔다. 사후에 "누가 열어뒀냐"를 찾는 것보다 10배 빠르다.
ROW 기반 binlog에서 binlog_row_image를 minimal로 바꾸는 변경은 CDC 계약과 맞물린다. Debezium·Maxwell 같은 소비자가 full 이미지를 요구하면 minimal로 내리지 말 것. 용량 이슈는 binlog_rotate_immediate 등 다른 축으로 푼다.

8) 한 줄 정리

MySQL InnoDB는 서버 레이어와 스토리지 엔진을 handlerton 계약으로 나누고, 버퍼 풀 3층과 redo·undo·doublewrite·binlog 네 축으로 지속성을 만든다. 각 서브시스템은 독립적으로 튜닝되며 기본값은 안전 우선이다. group commit 2층과 2PC 덕분에 고동시 OLTP에서도 fsync 비용이 묶여 처리량이 유지된다.

다음 편: Oracle의 SGA·UNDO 구조로 넘어가 세 DB의 메모리 레이아웃을 머릿속에 완성한다.

태그: mysql, innodb, buffer-pool, redo-log, undo-log, binlog, mvcc, doublewrite, group-commit, handlerton

gRPC Deadline · Cancellation · Context Deep Dive — 5쌍의 레이어가 동시에 서야 한다

dding-shark — Wed, 15 Apr 2026 08:23:41 +0900

gRPC Deadline · Cancellation · Context Deep Dive — 5쌍의 레이어가 동시에 서야 한다

들어가며

"3초 SLA"라고 써놓고 실제 호출은 9초 뒤에 503으로 돌아온다. BANDER에서 이 현상을 처음 봤을 때, 타임아웃 설정을 잘못 읽은 줄 알고 application.yml을 뒤졌다. grpc.client.deadline: 5s가 멀쩡히 있었다. 스타트업 로그에도 deadline=PT5S가 찍혀 있었다. 그런데 서버 쪽 ServerInterceptor에서 꺼내본 호출의 Deadline은 null이었고, HTTP/2 HEADERS 프레임을 Wireshark로 덤프해보니 grpc-timeout 헤더 자체가 존재하지 않았다. 선언은 있는데 wire에는 아무것도 나가지 않은 상태, 전형적인 dead config였다.

원인을 추적해보니 한 줄짜리 누락이었다. 채널을 조립하는 GrpcChannelFactory 코드가 properties.getDeadline()을 한 번도 읽지 않았다. ManagedChannelBuilder에 intercept(...)를 건 적도 없었다. Duration 필드만 스프링 프로퍼티에 선언해 두면 알아서 gRPC 호출에 붙을 거라는 암묵적 가정이 틀렸다. gRPC-Java는 그런 자동 배선을 전혀 해주지 않는다. 인터셉터를 직접 등록해야 비로소 CallOptions에 Deadline이 얹히고, 그제야 wire에 grpc-timeout 헤더가 실린다. 이 한 줄이 빠져 있으면 그 뒤에 있는 모든 정책 — retry, hedging, 서킷 브레이커, 분산 트레이싱 — 이 전부 같은 시각을 공유하지 못한다.

이 글은 그 사고를 해부한다. Deadline은 단일 설정 값이 아니라 다섯 개의 레이어가 동시에 서야 동작하는 협업이다. 인터셉터 등록이 1번, 서버 로직의 isCancelled() 폴링이 2번, 비동기 경계에서의 Context.wrap()이 3번, retry 예산의 남은 시간 재산정이 4번, 서킷 브레이커와 Deadline의 시간 축 정합이 5번이다. 하나라도 빠지면 나머지 넷이 얼마나 정교하게 서 있어도 SLA는 깨진다. 이 글은 다섯 레이어를 한 장에 모은 뒤, 각 레이어를 한 섹션씩 확대해서 왜 · 구조 · 동작 · 함정 · 실무 순으로 풀어낸다.

이 시리즈 4편을 읽다가 거의 다 같은 지점에서 막힌다.

Deadline은 Duration 선언만으로는 전파되지 않는다 — ClientInterceptor가 짝으로 등록돼야 grpc-timeout 헤더가 wire에 실린다
헤더가 전달돼도 서버는 자동으로 멈추지 않는다 — Context.current().isCancelled()를 직접 폴링하거나 addListener로 훅을 걸어야 한다
CompletableFuture.supplyAsync()에 gRPC 호출을 넘기면 Context가 증발한다 — 디폴트 ForkJoinPool 스레드에서 Context.current()는 ROOT로 돌아온다
DEADLINE_EXCEEDED를 retryable로 두면 예산이 배수로 늘어난다 — retry budget을 안 쓰면 장애가 전파 증폭된다
Hedging은 이중 호출이다 — 백엔드 부하를 2~3배로 밀어넣는다는 계산을 안 하면 retry만으로 서비스가 죽는다

이 글은 불변식 5쌍 → Deadline vs Timeout → 전달 ≠ 강제 → Context → 비동기 경계 → 서버 체크 → 시계 비대칭 → Retry/Hedging → 3-hop 전파 → 실무 순으로 정리한다.

0) 불변식 5쌍 지도: Deadline이 서려면 동시에 서야 하는 것들
1) Deadline vs Timeout: 절대 시각과 상대 시간의 차이
2) 헤더 전달은 강제가 아니다: BANDER dead config 실증
3) io.grpc.Context: parent-child와 attach/detach
4) 비동기 경계 3종: Context가 증발하는 지점
5) 서버는 자동으로 멈추지 않는다: isCancelled와 listener
6) 분산 시계 비대칭: DEADLINE_EXCEEDED vs CANCELLED
7) Retry·Hedging·Circuit Breaker의 정합성
8) 3-hop 예산 전파 시퀀스: Client → Gateway → Service A → Service B
9) 실무에서 이렇게 읽고 쓴다
10) 한 줄 정리
부록 A) 운영 체크리스트

0) 불변식 5쌍 지도: Deadline이 서려면 동시에 서야 하는 것들

Deadline 하나가 SLA를 지킨다는 말은 반은 맞고 반은 틀리다. 정확히는 다섯 개의 독립된 레이어가 같은 시각을 공유해야 한다. 하나라도 다른 시각을 보고 있거나 아예 시각 자체가 비어 있으면, 전체 호출은 선언한 Deadline 안에 끊기지 않는다. BANDER 사고가 정확히 그 상태였다 — 1번 레이어가 비어 있었고, 2~5번이 아무리 잘 짜여 있어도 1번이 없으니 전부 의미를 잃었다. 이 글의 나머지 섹션은 이 표의 한 행씩을 확대한 것이다. 읽다가 맥락을 놓치면 이 표로 돌아오면 된다.

레이어	무엇을 하는가	빠지면 생기는 증상	상세 섹션
1. 인터셉터 등록	`ClientInterceptor`로 `grpc-timeout` 헤더를 wire에 붙인다	선언된 Deadline이 wire에 실리지 않음 → 호출이 끊기지 않고 흐름	§2
2. 서버 isCancelled 폴링	서버 로직이 주기적으로 취소 신호를 감지한다	클라가 끊어도 서버는 쿼리를 끝까지 실행 → DB·메모리 리소스 누수	§5
3. Context.wrap	비동기 스레드로 작업을 넘길 때 Context를 같이 싸서 넘긴다	하위 gRPC 호출이 ROOT Context로 흘러 Deadline 상속 실패	§4
4. Retry budget 재산정	남은 시간을 기준으로 재시도 횟수·backoff를 결정한다	`DEADLINE_EXCEEDED`를 다시 시도해 예산이 배수로 증폭	§7
5. Circuit breaker 정합	브레이커 상태와 Deadline이 동일한 시간 축을 본다	Open 구간에서도 Deadline이 깎여 Half-open 시점에 새 호출이 즉시 만료	§7

이 다섯 레이어에는 순서가 있다. 1번이 서 있지 않으면 나머지는 논의할 필요가 없다. 2~5번은 1번이 동작한다는 가정 위에서만 의미를 가진다. 장애 분석을 이 순서대로 — "1번부터 확인, 서 있으면 2번, 그 다음 3번" — 내려가는 게 가장 빠르다. 5쌍이 한 번에 다 무너진 상황은 거의 없다. 대부분의 사고는 정확히 한 레이어가 비어 있고, 나머지는 잘 서 있지만 그 한 레이어 때문에 전부가 움직이지 않는 구조다. 이 글을 "불변식 지도 + 각 레이어별 해부"로 읽으면 된다.

1) Deadline vs Timeout: 절대 시각과 상대 시간의 차이

1-1) 왜 gRPC는 Timeout이 아니라 Deadline이라는 단어를 쓰는가

이름이 다른 건 개념이 다르기 때문이다. HTTP 클라이언트는 대부분 "읽기 타임아웃 5초"처럼 상대 시간을 쓴다. 호출이 시작된 시각 + 5초가 각 호출마다 새로 계산된다. 한 호출에서만 보면 무해하지만, RPC 체인에 들어가면 이 모델이 시간을 몇 배로 늘린다. 서비스 A가 B를 5초 타임아웃으로 호출하고, B가 다시 C를 5초 타임아웃으로 호출하면, 홉마다 타임아웃이 재시작되어 전체 최악 지연이 홉 수만큼 곱해진다. 3-hop 체인이면 최악 15초, 4-hop이면 20초다. 사용자 관점의 SLA는 "5초"라고 생각했는데 실제 최악은 4배가 넘는 식이다.

gRPC는 이 문제를 **절대 시각(Deadline)**으로 푼다. "2026-04-15T12:34:56.123Z까지 끝나야 한다"는 단일 시점을 체인 전체가 공유한다. 클라이언트가 최초 호출 시점에 withDeadlineAfter(3, TimeUnit.SECONDS)를 부르면, gRPC-Java는 그 시각 + 3초를 절대 타임스탬프로 고정해서 CallOptions에 심는다. 호출이 네트워크로 나갈 때 이 절대 시각은 "현재 시각 대비 남은 밀리초"로 환산돼 HTTP/2 HEADERS 프레임의 grpc-timeout 헤더에 실린다. 수신 서버는 자신의 시계로 "이제부터 남은 N ms"를 더해 새 절대 시각을 자기 Context에 다시 심는다. 이렇게 각 홉은 "한 번 더 당겨진 공통 마감"을 공유하게 되고, 최악 지연은 홉 수에 곱해지지 않고 초기 Deadline에 수렴한다.

이 차이가 실무에서 느껴지는 지점은 두 곳이다. 첫째, 사용자 체감 SLA와 내부 호출 체인 예산이 동일한 단위로 측정된다. 3초라고 써놓으면 정말로 3초다. 둘째, 한 홉이 느려지면 그 만큼 뒤 홉 예산이 줄어든다. 앞 홉이 2초를 써버리면 뒤 홉은 1초 안에 끝내야 한다. 이게 처음에는 불편해 보이지만, "전체 예산을 공유한다"는 계약이 있어야 체인 끝단이 과부하에 걸렸을 때도 클라이언트가 약속된 시각에 결과를 받는다.

1-2) grpc-timeout 헤더 BNF와 8자리 제약

grpc-timeout 헤더의 문법은 gRPC wire 스펙에 BNF로 정의돼 있다. 짧지만 두 가지 함정이 들어 있다.

Timeout          -> "grpc-timeout" TimeoutValue TimeoutUnit
TimeoutValue     -> {positive integer as ASCII string of at most 8 digits}
TimeoutUnit      -> Hour / Minute / Second / Millisecond / Microsecond / Nanosecond
Hour             -> "H"
Minute           -> "M"
Second           -> "S"
Millisecond      -> "m"
Microsecond      -> "u"
Nanosecond       -> "n"

첫 번째 함정은 값이 최대 8자리라는 제한이다. 99,999,999까지만 실을 수 있다. 단위가 초(S)면 약 3.17년까지 가능하므로 실무에서는 문제 될 일이 없지만, 나노(n)나 마이크로(u) 단위로 큰 Deadline을 실으려고 하면 값이 잘린다. gRPC-Java 스택은 내부적으로 단위를 자동 선택해 8자리 안에 들어오는 가장 정밀한 단위로 직렬화한다. 3초는 3S가 아니라 보통 3000000u(마이크로초)나 3000m(밀리초)로 나간다. 이 동작은 구현 최적화지 스펙 위반이 아니다.

두 번째 함정은 단위가 대소문자에 민감하다는 것이다. S는 초, m은 밀리초, M은 분이다. 수작업으로 헤더를 만드는 일은 거의 없지만, 프록시 레이어에서 문자열로 파싱하고 재조립할 때 대소문자를 섞으면 Deadline이 60배로 늘거나 1000배로 줄어든다. Envoy나 nginx에서 grpc-timeout을 건드리는 설정을 쓸 일이 있으면 이 지점을 반드시 테스트해야 한다. 공식 정의는 gRPC PROTOCOL-HTTP2 Requests 섹션에 있다.

1-3) 3-hop REST vs 3-hop gRPC 최악 지연

비교가 가장 선명한 지점은 표 하나다. 상대 타임아웃과 절대 Deadline이 체인에서 어떻게 다르게 누적되는지를 한 장에 보여준다.

구조	각 홉 설정	최악 지연	이유
REST 3-hop, 상대 타임아웃	3s / 3s / 3s	최대 9s	홉마다 타임아웃이 재시작
gRPC 3-hop, Deadline 전파	초기 3s, 체인 공유	최대 3s	공통 절대 시각, 체인 전체가 한 번에 만료
REST 4-hop, 상대 타임아웃	2s × 4	최대 8s	3-hop과 같은 메커니즘
gRPC 4-hop, Deadline 전파	초기 2s, 체인 공유	최대 2s	홉 수와 무관

이 한 줄이 Deadline이라는 개념의 존재 이유다. 공유 시계가 있으면 체인 전체가 하나의 SLA 안에 들어간다. 없으면 홉 수만큼 곱해진다. 특히 4번째 열의 "홉 수와 무관"이 중요하다. 서비스 메쉬가 커지면서 체인이 4-hop, 5-hop으로 길어져도, Deadline 모델은 초기 시각을 바꾸지 않는 한 최악 지연이 늘어나지 않는다. 상대 타임아웃 모델은 체인이 길어질수록 비례해서 악화된다. 실제 시퀀스는 §8에서 다이어그램으로 본다.

2) 헤더 전달은 강제가 아니다: BANDER dead config 실증

이 섹션이 이 글에서 가장 두껍다. 설정 값이 분명히 선언돼 있는데 동작은 전혀 하지 않는 상태가 어떻게 만들어지는지, BANDER 저장소의 실제 세 파일을 증거로 풀어낸다. 읽으면서 "내 프로젝트도 이렇지 않을까"라고 의심하는 지점을 코드로 열어서 확인하게 만드는 게 이 섹션의 목적이다.

2-1) BANDER가 실제로 틀렸던 지점: 선언은 멀쩡한데 조립이 비어 있다

먼저 설정 빈이다. GrpcClientProperties는 Deadline을 정직하게 선언한다.

// libraries/grpc/client-common/.../GrpcClientProperties.java
package com.example.grpc.client;

import java.time.Duration;

public class GrpcClientProperties {

    private String host = "localhost";
    private int port = 9090;
    private Duration deadline = Duration.ofSeconds(5);
    private boolean plaintextEnabled = true;

    public Duration getDeadline() {
        return deadline;
    }

    public void setDeadline(Duration deadline) {
        this.deadline = deadline;
    }
    // host/port/plaintextEnabled의 getter·setter 생략
}

application.yml에서 grpc.client.deadline: 3s로 덮어쓸 수 있고, 기본값은 5초다. 스프링 바인딩이 걸려 있다면 기동 로그에도 "deadline=PT5S"가 찍힌다. 여기까지는 완벽하다. 선언 자체는 문제가 없다. 문제는 이 값을 실제로 채널에 연결하는 다음 파일이다.

// libraries/grpc/client-common/.../GrpcChannelFactory.java
package com.example.grpc.client;

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class GrpcChannelFactory {

    public ManagedChannel createChannel(GrpcClientProperties properties) {
        ManagedChannelBuilder<?> builder = ManagedChannelBuilder.forAddress(
                properties.getHost(), properties.getPort());
        if (properties.isPlaintextEnabled()) {
            builder.usePlaintext();
        }
        return builder.build();
    }
}

properties.getDeadline()을 호출하는 코드가 어디에도 없다. host, port, plaintextEnabled는 정확히 참조되지만 deadline은 한 번도 읽히지 않는다. intercept(...) 호출도 없다. 채널이 조립되는 이 단일 지점에서 Deadline은 완전히 무시된다. 오토컨피그도 상황이 같다.

// libraries/grpc/client-common/.../config/GrpcClientAutoConfiguration.java
package com.example.grpc.client.config;

import com.example.grpc.client.GrpcChannelFactory;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
public class GrpcClientAutoConfiguration {

    @Bean
    public GrpcChannelFactory grpcChannelFactory() {
        return new GrpcChannelFactory();
    }
}

이 파일에는 GrpcClientProperties를 빈으로 등록하는 로직조차 없다. @EnableConfigurationProperties(GrpcClientProperties.class)도 없고, 클래스에 @ConfigurationProperties도 붙어 있지 않다. 이 말은 application.yml에 grpc.client.deadline: 3s를 아무리 써도 그 값이 빈으로 바인딩되지도 않는다는 뜻이다. 파일만 멀쩡히 있고, 기동 시점에 아무 일도 안 일어난다. 이 상태를 나는 3중 dead config라고 부른다 — 프로퍼티 바인딩 없음, Factory가 값을 읽지 않음, interceptor 등록 없음. 세 줄이 전부 동시에 비어 있다.

이 상태에서 실제 wire는 어떻게 나가는가. 결과는 분명하다. HTTP/2 HEADERS 프레임에 grpc-timeout 헤더가 존재하지 않는다. 서버는 Deadline이 없는 것으로 간주하고 요청을 무한히 처리하려 한다. 프런트엔드가 5초를 기다리다가 LB 타임아웃에 걸려 끊기고, 사용자는 503을 본다. 서버 로그에는 8.9초짜리 "정상 완료" 쿼리가 남는다. 양쪽이 서로 다른 말을 하는 전형적 장애다.

2-2) 어떻게 찾아냈는가: 세 가지 증거

이 dead config를 찾아낸 방법은 셋이다. 첫째, Wireshark로 HTTP/2 HEADERS 프레임을 덤프했다. :method=POST, :path=/..., content-type=application/grpc는 다 있는데 grpc-timeout만 없었다. 이게 가장 확실한 증거다. gRPC-Java가 Deadline을 CallOptions에 가지고 있었다면 반드시 이 헤더가 나간다. 나가지 않았다는 건 CallOptions에도 없다는 뜻이다.

둘째, 서버 쪽에 간단한 ServerInterceptor를 걸어 수신된 호출의 Deadline을 로그로 찍었다. Context.current().getDeadline()을 꺼내보니 null이었다. 서버가 Deadline을 못 받았다는 직접 증거다. 셋째, 부하 테스트에서 p99 응답 시간이 9초를 넘어가는 걸 발견했다. 평균은 500ms인데 p99만 9초 근처에 붙어 있었다. 이건 LB 타임아웃(보통 10초 내외)에 걸려 끊긴 요청들의 흔적이다. 정상 Deadline이 3초로 걸려 있으면 p99가 3초 언저리에서 잘려야 하는데, 잘리지 않고 9초까지 갔다는 건 Deadline이 실제로 동작하지 않는다는 뜻이다.

이 셋 중 하나만 봐도 충분하지만, 장애 복기 문서에는 셋 다 적어두는 게 좋다. Wireshark 덤프가 없어도 서버 인터셉터와 p99 그래프만으로도 원인이 좁혀진다. 셋을 병렬로 돌려보고 각자가 같은 결론(헤더 없음)을 가리키는지 확인하는 과정 자체가 "아, 이건 설정의 문제가 아니라 코드의 문제구나"를 팀에게 납득시키는 수단이기도 하다.

2-3) 고치는 방법: DefaultDeadlineInterceptor

표준 해법은 gRPC-Java 코어에 내장돼 있지 않다. 커뮤니티에서는 Salesforce가 공개한 DefaultDeadlineInterceptor 패턴이 사실상 de facto다. 핵심은 "이미 호출자가 Deadline을 지정했으면 건드리지 말고, 없을 때만 기본값을 얹는다"는 한 가지 규칙이다.

import io.grpc.CallOptions;
import io.grpc.Channel;
import io.grpc.ClientCall;
import io.grpc.ClientInterceptor;
import io.grpc.MethodDescriptor;

import java.time.Duration;
import java.util.concurrent.TimeUnit;

public class DefaultDeadlineInterceptor implements ClientInterceptor {

    private final long defaultDeadlineMillis;

    public DefaultDeadlineInterceptor(Duration defaultDeadline) {
        this.defaultDeadlineMillis = defaultDeadline.toMillis();
    }

    @Override
    public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
            MethodDescriptor<ReqT, RespT> method,
            CallOptions callOptions,
            Channel next) {
        // 호출자가 이미 Deadline을 지정했으면 건드리지 않는다
        if (callOptions.getDeadline() == null) {
            callOptions = callOptions.withDeadlineAfter(
                    defaultDeadlineMillis, TimeUnit.MILLISECONDS);
        }
        return next.newCall(method, callOptions);
    }
}

원리가 단순하다는 게 중요하다. CallOptions에 Deadline이 없으면 기본값을 얹고, 있으면 그대로 둔다. 호출자가 stub.withDeadlineAfter(1, SECONDS)로 더 짧게 지정한 경우를 덮어쓰지 않는 게 핵심이다. 만약 덮어쓰면 "이 호출만 1초 Deadline"이라는 의도가 기본값 5초로 되살아나 버린다. 이 실수를 피하려면 null 체크 한 줄이 반드시 있어야 한다.

이제 Factory에 이 인터셉터를 등록한다.

public ManagedChannel createChannel(GrpcClientProperties properties) {
    ManagedChannelBuilder<?> builder = ManagedChannelBuilder
            .forAddress(properties.getHost(), properties.getPort())
            .intercept(new DefaultDeadlineInterceptor(properties.getDeadline()));
    if (properties.isPlaintextEnabled()) {
        builder.usePlaintext();
    }
    return builder.build();
}

.intercept(...) 한 줄. 이 한 줄이 추가되면 비로소 Deadline이 wire에 실린다. Duration을 빈에 선언하는 것과 실제로 그 값이 RPC에 동작하는 것 사이에 이 한 줄이 있다. 그리고 오토컨피그도 같이 고쳐서 Properties를 빈으로 올리고, Factory가 그 Properties를 주입받도록 체인을 완성한다.

@AutoConfiguration
@EnableConfigurationProperties(GrpcClientProperties.class)
public class GrpcClientAutoConfiguration {

    @Bean
    public GrpcChannelFactory grpcChannelFactory() {
        return new GrpcChannelFactory();
    }
}

세 파일이 동시에 수정되어야 dead config가 살아난다. 한 군데만 고치면 다른 지점이 여전히 비어 있어서 증상은 그대로다. 이 세 지점을 한 PR로 묶어서 올리는 게 실무 원칙이다. 나눠서 머지하면 중간 상태에서 "바인딩은 되는데 Factory가 안 읽는다" 같은 이상한 절반 상태가 생긴다.

2-4) LIFO 순서 함정: Deadline은 가장 먼저 등록

인터셉터는 여러 개를 등록할 수 있고 실행 순서가 정해져 있다. 여기서 두 번째 함정이 나온다. ManagedChannelBuilder.intercept(...)는 여러 번 호출하거나 한 번에 varargs로 여러 개를 넘길 수 있는데, 실행 순서는 **LIFO(Last-In-First-Out)**다. 나중에 등록한 인터셉터가 바깥쪽을 감싸고, 먼저 등록한 인터셉터가 가장 안쪽, 즉 실제 네트워크 호출에 가장 가까운 위치에 선다.

구체 예시로 트레이싱(OpenTelemetry) 인터셉터와 Deadline 인터셉터를 같이 쓰는 경우를 보자.

// 피하기: Deadline이 트레이싱보다 바깥에 있음
builder
    .intercept(tracingInterceptor)    // 먼저 등록 → 가장 안쪽
    .intercept(deadlineInterceptor);  // 나중 등록 → 바깥쪽

// 선호: Deadline이 가장 안쪽
builder
    .intercept(deadlineInterceptor)   // 먼저 등록 → 가장 안쪽
    .intercept(tracingInterceptor);   // 나중 등록 → 바깥쪽

왜 Deadline을 가장 안쪽에 두는가. 트레이싱 인터셉터는 span을 생성하면서 "이 호출의 Deadline은 얼마였다"는 메타데이터를 span attribute로 찍는다. 이 값을 정확히 찍으려면 트레이싱이 newCall로 체인을 넘기기 전에 이미 Deadline이 CallOptions에 심어져 있어야 한다. Deadline을 바깥에 두면 트레이싱 span이 먼저 시작되고, 그 span이 끝나기 직전에야 Deadline이 얹어진다. 그 사이 수십 밀리초의 공백이 span attribute에 기록되지 않아 디버깅이 어려워진다. p99 튜닝 단계에 가면 이게 실제로 드러난다.

정리하면, Deadline 인터셉터는 가장 먼저 등록한다. 코드 리뷰 체크리스트에 이 한 줄을 넣어두면 다른 인터셉터가 추가돼도 자연스럽게 유지된다. 트레이싱, 메트릭, 인증, 로깅 인터셉터가 뒤에 계속 쌓여도 Deadline은 항상 안쪽에 남는다.

3) io.grpc.Context: parent-child와 attach/detach

3-1) Context는 ThreadLocal 기반이지만 ThreadLocal이 아니다

io.grpc.Context는 현재 호출에 걸린 Deadline, 취소 토큰, 그리고 커스텀 key-value 쌍을 담는 불변 객체다. 겉보기는 ThreadLocal처럼 동작하지만, 불변 · fork 기반 · 스코프 명시라는 세 가지가 ThreadLocal과 다르다. 가장 핵심은 "불변"이라는 점이다. 한 번 만들어진 Context는 수정되지 않는다. withValue(key, value)나 withDeadlineAfter(...)를 부르면 새로운 자식 Context가 돌아온다. 부모는 그대로 남아 있다.

Context parent = Context.current();
Context child = parent.withDeadlineAfter(3, TimeUnit.SECONDS, scheduler);

// parent는 여전히 Deadline이 없다. child만 있다.
// 두 객체는 다른 노드이고, parent는 child의 존재를 알지 못한다.

이 parent-child 관계가 취소 전파의 뼈대다. 부모 Context가 취소되면 자식 Context도 자동으로 취소된다. 반대 방향은 성립하지 않는다 — 자식이 취소돼도 부모는 영향받지 않는다. 이 방향성이 중요하다. 상위 요청이 끊어지면 그 안에서 파생된 모든 하위 호출이 동시에 CANCELLED로 터진다. "상위 요청은 이미 끝났는데 서버는 내부 쿼리를 계속 돌리는" 낭비를 이 전파가 막는다.

또 하나 기억할 지점은 Context가 fork된다는 것이다. 같은 parent에서 두 개의 자식이 독립적으로 만들어질 수 있다. 각자 다른 Deadline을 가질 수도 있고, 각자 다른 값을 덮어쓸 수도 있다. 둘은 서로 간섭하지 않는다. 이 fork 모델이 여러 스레드가 동시에 같은 부모 맥락에서 작업할 때 정합성을 보장한다. ThreadLocal은 이 모델이 없다 — 한 스레드가 값을 바꾸면 그게 그 스레드의 유일한 상태가 되고, 다른 스레드는 완전히 독립된 별도 값을 가진다. gRPC Context는 "부모를 공유하고 자식만 다르게 fork되는" 트리 구조라서 여러 자식이 공통 부모의 Deadline을 동시에 상속할 수 있다.

3-2) attach/detach의 try-finally와 Context.run

Context를 "현재 스레드의 기본값으로 설정"하려면 attach()를 부른다. 이 메서드는 이전 Context를 리턴하고, 작업이 끝나면 반드시 detach(previous)를 불러 원래 상태로 복원해야 한다. 패턴은 고정돼 있다.

Context previous = newContext.attach();
try {
    // 이 블록 안에서는 Context.current()가 newContext를 리턴한다
    doWork();
} finally {
    newContext.detach(previous);
}

try-finally를 빼먹으면 예외 경로에서 detach가 호출되지 않고, 스레드가 풀로 반환될 때 엉뚱한 Context가 남아 다음 작업으로 흘러간다. 이 누수는 디버깅이 극악하다. 현상은 "왜 이 요청에 있지도 않은 Deadline이 걸려 있지?" 같은 식이고, 원인은 이전 요청이 남긴 Context다. 자원 풀 기반 아키텍처(스레드풀·executor)에서는 이게 치명적이다.

더 안전한 방법은 Context.run(Runnable)이나 Context.call(Callable)을 쓰는 것이다. 내부에서 attach/detach를 자동으로 try-finally로 감싸준다.

newContext.run(() -> doWork());

// 값을 리턴받으려면:
String result = newContext.call(() -> doWorkReturning());

실무에서는 run/call을 우선 쓴다. 직접 attach/detach를 부르는 건 스레드 경계를 수동으로 넘기는 인터셉터 내부나 Context-aware executor 래퍼 같은 저수준 코드에서만이다. 비즈니스 로직에 직접 쓰지 않는 게 원칙이다.

3-3) CancellableContext — 명시적 취소 핸들

Deadline이 아니라 "명시적 취소 신호"를 주고받고 싶을 때가 있다. 예를 들어 사용자가 "이 조회 작업을 취소" 버튼을 눌렀을 때, 그 신호를 서버의 Context에 연결해 진행 중인 쿼리를 중단시키는 구조다. 이럴 때는 Context.withCancellation()이 **CancellableContext**라는 자식을 돌려주는데, 이 자식에는 cancel(Throwable) 메서드가 달려 있다.

Context.CancellableContext cancellable = Context.current().withCancellation();
// 어디선가 취소 트리거 발생
cancellable.cancel(new RuntimeException("user aborted"));
// 그 순간 cancellable 하위의 모든 작업이 취소 신호를 받는다

CancellableContext는 명시적으로 close() 또는 cancel()을 호출해 정리해야 한다. 안 하면 리스너가 GC되지 않고 남을 수 있다. Deadline 기반 Context는 만료 시점에 자동으로 취소되지만, CancellableContext는 수동 제어 핸들이라 누군가 반드시 닫아줘야 한다. 이 차이가 withDeadlineAfter와 withCancellation의 운영 차이다. 실무에서는 Deadline을 기본으로 쓰고, 명시적 사용자 취소가 필요한 드문 케이스에만 CancellableContext를 추가로 얹는다.

4) 비동기 경계 3종: Context가 증발하는 지점

여기서 진짜 함정이 시작된다. 스레드 경계를 넘는 순간 Context.current()가 ROOT로 돌아가는 경계가 실무에 세 종류 있다. 셋 다 겉보기에는 Context가 자동으로 따라갈 것처럼 보이는데, 실제로는 따라가지 않는다. 이 섹션이 가장 자주 사고가 나는 지점이다.

4-1) CompletableFuture: supplyAsync의 기본 풀은 ForkJoinPool.commonPool

CompletableFuture.supplyAsync(() -> stub.call(req))는 기본적으로 ForkJoinPool.commonPool의 스레드에서 람다를 실행한다. 이 풀의 스레드는 애플리케이션 수명 동안 공유되고, 이전에 어떤 작업이 끝났든 상관없이 Context.current()는 그 시점의 ROOT를 가리킨다. 부모 스레드에 Deadline이 있어도 자동으로 상속되지 않는다. gRPC-Java는 이 상속을 자동으로 해주는 메커니즘을 두지 않았다. 명시적이어야 한다는 철학이다.

// 피하기: Context가 새 스레드로 따라가지 않는다
CompletableFuture.supplyAsync(() -> stub.getStudio(req))
        .thenAccept(this::handle);

이 코드에서 stub.getStudio(req)가 실행되는 스레드의 Context.current()는 ROOT다. 부모가 5초 Deadline 안에서 돌고 있어도, 이 호출은 Deadline 없이 나간다. 증상은 "대시보드에서는 3초 SLA를 맞추고 있는데 특정 비동기 경로만 9초까지 튀는" 형태다. 고치려면 Context.current().wrap(...)으로 람다를 감싼다.

// 선호: Context.current().wrap(...)으로 싸서 넘긴다
Context ctx = Context.current();
CompletableFuture.supplyAsync(ctx.wrap(() -> stub.getStudio(req)))
        .thenAccept(this::handle);

ctx.wrap(Supplier)는 람다 실행 직전에 ctx를 attach하고, 끝나면 detach하는 래퍼를 리턴한다. 이 한 줄이 Deadline 상속의 전부다. 빼먹으면 비동기 경계 뒤의 호출은 SLA 계약에서 조용히 탈락한다. Runnable/Callable/Supplier 모두 wrap 오버로드가 있다. 같은 원리로 executor.submit(...)에 직접 람다를 넘기면 안 된다. ctx.wrap(runnable)로 감싸거나, 아예 Context-aware executor를 써서 경계 자체를 자동화한다.

ExecutorService wrapped = Context.currentContextExecutor(executor);
wrapped.submit(() -> stub.getStudio(req));
// wrapped는 제출되는 모든 작업에 현재 Context를 자동 attach한다

이 executor 래핑은 스프링 빈 정의 지점에 한 번만 해두면 되므로 실무에서는 이 쪽을 선호한다. @Async 메서드가 쓰는 TaskExecutor를 이 방식으로 감싸두면 비동기 서비스 계층이 자동으로 Context를 이어받는다. 람다마다 ctx.wrap을 붙이는 건 사람 실수가 너무 잘 나는 지점이라, executor 자체를 감싸는 게 훨씬 안전하다.

4-2) Reactor: Schedulers 경계와 ContextView의 분리

Reactor의 Mono/Flux는 assembly time과 subscription time이 분리돼 있어서 스레드 경계가 더 미묘하다. publishOn(Schedulers.boundedElastic())을 타는 순간 실행 스레드가 바뀌고, 그 스레드에서는 Context.current()가 ROOT로 돌아온다. Reactor에는 자체적인 ContextView가 있는데, 이건 gRPC의 io.grpc.Context와는 완전히 별개의 객체다. 둘은 자동으로 연동되지 않는다. 구조가 비슷하지만 서로 존재를 모른다.

해법은 두 갈래다. 첫째, 스케줄러를 Context.currentContextExecutor(...)로 감싼 executor로 생성한다. 이렇게 하면 Reactor가 작업을 옮길 때마다 gRPC Context가 같이 따라간다. 둘째, Micrometer의 Context Propagation 라이브러리를 써서 gRPC Context와 Reactor ContextView 사이에 자동 매핑을 건다. Reactor 2023년 이후 버전은 이 라이브러리를 공식 지원하고, 한 번 등록하면 ThreadLocal 기반 Context들이 Reactor 체인을 따라가도록 배선된다. 운영 코드베이스가 크면 두 번째 방식이 훨씬 낫다. 경계가 하나만 빠져 있어도 사고가 나는데, 그 경계를 사람이 일일이 찾아내는 건 비용이 감당 안 된다.

간단한 원칙 하나는 — Reactor를 쓰면서 gRPC 호출을 flatMap 안에 넣는다면, 그 flatMap이 타는 스케줄러에서 Context가 보장되는지 반드시 점검한다. 보장되지 않으면 deferContextual을 써서 스레드 위의 Context.current()를 매번 재조합하거나, Context Propagation을 걸거나, 둘 중 하나여야 한다. 자동 상속을 믿고 넘어가면 안 된다. 특히 subscribeOn과 publishOn이 같은 체인에 섞여 있으면 어느 시점에 스레드가 바뀌는지 사람이 추적하기 어려워지므로, Context Propagation을 거는 쪽이 현실적이다.

4-3) Virtual Thread: JDK 21+의 ThreadLocal 상속 차이

JDK 21의 가상 스레드는 ThreadLocal을 부모로부터 상속하지 않는다. 캐리어 스레드가 바뀌어도 가상 스레드 자신은 ThreadLocal을 유지하지만, 새 가상 스레드를 Thread.ofVirtual().start(runnable)로 만들면 부모 스레드의 ThreadLocal이 새 가상 스레드로 복사되지 않는다. io.grpc.Context가 내부적으로 ThreadLocal을 쓰므로 같은 문제를 그대로 안는다.

// 피하기: 새 가상 스레드에 Context가 따라가지 않는다
Thread.ofVirtual().start(() -> stub.getStudio(req));

// 선호: wrap으로 감싼다
Context ctx = Context.current();
Thread.ofVirtual().start(ctx.wrap(() -> stub.getStudio(req)));

Executor 형태로 쓴다면 Executors.newVirtualThreadPerTaskExecutor()를 Context.currentContextExecutor로 감싸는 게 같은 효과다. 가상 스레드가 "blocking을 마음 편히 해도 되는 곳"이라는 장점을 주지만, Context 상속은 명시적으로 처리해야 한다는 점은 동일하다. 가상 스레드로 옮긴 뒤 Deadline이 사라졌다는 사고가 JDK 21 도입 첫 달에 가장 흔하다. "플랫폼 스레드에서 잘 되던 게 왜 갑자기?"라는 질문이 바로 이 상속 차이 때문이다.

4-4) 세 경계를 한 장에

세 경계가 공통으로 공유하는 원인을 다이어그램으로 본다.

세 경계 모두 공통 원인이 하나다. Context는 스레드에 붙은 게 아니라 attach된 실행 프레임에 붙은 객체다. 새 스레드·새 프레임이 시작하는 순간 그 프레임에는 attach가 일어난 적이 없고, 따라서 Context.current()는 ROOT다. wrap을 붙이는 순간 새 프레임 시작 지점에 attach가 명시적으로 박혀서, 상속이 복원된다. "자동으로 따라간다"는 문장은 이 모델에서 성립할 수 없다. gRPC-Java는 자동을 보장하지 않기로 결정한 스택이다. 명시적 wrap이 유일한 안전 장치다.

5) 서버는 자동으로 멈추지 않는다: isCancelled와 listener

클라이언트가 DEADLINE_EXCEEDED로 호출을 끊어도, 서버 쪽 로직이 자동으로 멈추는 건 아니다. 서버는 Context.current()에 취소 신호를 받지만, 그 신호를 주기적으로 체크하는 책임은 서버 코드에 있다. 안 체크하면 무거운 쿼리는 끝까지 돌아가고, DB 커넥션과 메모리는 그 시간 동안 잡혀 있는다. 이게 "취소 전파는 했는데 리소스는 안 돌아왔다"는 전형적 좀비 호출의 구조다.

5-1) polling: isCancelled()로 체크 지점 심기

가장 단순한 패턴은 루프 안에서 Context.current().isCancelled()를 주기적으로 확인하는 것이다.

public StudioListResponse listStudios(StudioListRequest req) {
    List<Studio> result = new ArrayList<>();
    for (long id : req.getIdsList()) {
        if (Context.current().isCancelled()) {
            // 클라가 이미 끊었다. 더 할 필요가 없다.
            throw Status.CANCELLED
                    .withDescription("client cancelled")
                    .asRuntimeException();
        }
        result.add(studioRepository.findById(id));
    }
    return StudioListResponse.newBuilder().addAllStudios(result).build();
}

루프 안 polling은 배치 처리와 스트리밍 응답에 특히 중요하다. 한 번에 1000건을 돌리는 리포팅 쿼리가 1초에 끝날 수도 있고 10초가 걸릴 수도 있다. 클라이언트가 3초에 끊었으면, 서버도 그 시점에 일을 멈춰 DB·메모리 리소스를 회수해야 한다. 안 하면 "클라는 이미 끊겼는데 서버는 계속 일하는" 좀비 호출이 쌓이고, 부하가 몰리면 커넥션 풀이 동난다. 이 상태는 애플리케이션 로그만으로는 잘 안 드러난다 — 서버 입장에서는 "정상 처리 완료"로 끝난 요청이기 때문이다.

5-2) listener: addListener로 blocking I/O 탈출

장시간 blocking I/O(예: Kafka consumer poll, JDBC 쿼리, 외부 HTTP 호출)를 타는 경우는 루프 안에서 isCancelled를 부를 기회가 없다. 스레드가 I/O에서 block돼 있으므로 polling이 불가능하다. 이때는 취소 시점에 비동기 콜백을 받는 addListener를 쓴다.

Context.current().addListener(ctx -> {
    // 취소된 순간 이 콜백이 실행된다
    cancelJdbcStatement();  // 예: stmt.cancel()
}, MoreExecutors.directExecutor());

리스너는 보통 directExecutor로 등록한다. 취소 이벤트는 가볍고, 별도 스레드에 넘기면 오히려 지연이 생긴다. JDBC의 경우 Statement.cancel()은 드라이버가 지원하면 진행 중인 쿼리를 DB 서버 쪽에서 중단시킨다. PostgreSQL과 MySQL 모두 지원한다. 이렇게 리소스별 취소 훅을 등록해 두는 게 좀비 호출을 막는 유일한 방법이다. Kafka consumer 같은 경우는 consumer.wakeup()을 리스너에서 호출하면 blocking poll()이 즉시 깨어난다. 외부 HTTP 호출은 HttpClient의 CompletableFuture<Response>를 취소시키는 훅을 건다.

주의할 지점 하나는 리스너가 여러 번 호출되지 않는다는 것이다. Context가 한 번 취소되면 리스너는 정확히 한 번만 실행된다. 이미 취소된 Context에 addListener를 뒤늦게 걸면 즉시 호출된다. 이 규칙 덕분에 "늦게 등록된 리스너가 실행되지 않아 리소스가 안 풀리는" 경우가 생기지 않는다. 반대로 같은 리스너를 여러 번 호출되길 기대하면 안 된다. 재실행이 필요하면 리스너를 다시 등록해야 한다.

5-3) 어디에 체크 지점을 두는가: 롤백 가능성 기준

체크 지점의 배치 기준은 한 줄이다. "이 지점을 지나면 롤백이 어려운가?" 롤백이 어려운 지점 직전에 isCancelled를 체크한다. DB write 직전, 외부 결제 API 호출 직전, 대용량 파일 쓰기 직전, 이메일 발송 직전이 대표적이다. 이런 지점에서 한 번 더 확인하면 "클라는 이미 끊겼는데 사이드 이펙트는 실행된" 상태를 막을 수 있다.

읽기 전용 루프는 체크 간격을 10~100건에 한 번 정도로 둬도 충분하다. 매 iteration마다 isCancelled를 호출하면 오버헤드가 보이기 시작한다. isCancelled는 volatile read 수준이라 비싸지는 않지만, 1000만 번 반복하는 루프에서는 누적된다. 실무에서는 batch size 기준으로 "매 배치 경계"에서만 체크하는 경우가 많다. 체크 지점이 너무 촘촘해도 성능이 떨어지고, 너무 드물어도 취소가 반영되는 데 시간이 걸린다. 배치 단위가 가장 합리적인 중간 지점이다.

6) 분산 시계 비대칭: DEADLINE_EXCEEDED vs CANCELLED

취소 이벤트를 받았을 때 gRPC는 두 개의 status code를 구분한다. **DEADLINE_EXCEEDED(4)**는 Deadline이 자연 만료된 경우고, **CANCELLED(1)**는 명시적 취소 — 클라가 stub.cancel()을 부르거나, 부모 Context가 취소됐거나, 스트림이 중간에 끊겼을 때 — 다. 둘을 구분해야 하는 이유는 원인 분석과 재시도 전략이 서로 다르기 때문이다. 특히 분산 시계가 완전히 동기화되지 않은 환경에서는 같은 이벤트가 양쪽에 다른 상태로 기록되는 비대칭이 생긴다.

상황	클라 관점	서버 관점	재시도 가능성
클라 시계 기준 Deadline 만료	`DEADLINE_EXCEEDED`	`CANCELLED` (상위 Context 취소 신호)	원칙상 금지
서버 시계 기준 Deadline 만료	`DEADLINE_EXCEEDED`	`DEADLINE_EXCEEDED`	원칙상 금지
클라 명시 취소 (사용자가 창 닫음)	`CANCELLED`	`CANCELLED`	불가
부모 요청 취소의 연쇄 전파	`CANCELLED`	`CANCELLED`	불가

여기서 미묘한 지점은 첫 번째 행이다. 같은 호출을 놓고 클라는 DEADLINE_EXCEEDED로, 서버는 CANCELLED로 기록할 수 있다. 이유는 Deadline 체크가 각자의 시계를 기준으로 이뤄지기 때문이다. 클라 쪽에서 먼저 Deadline이 지나가 호출을 끊으면, 네트워크로는 "클라가 스트림을 RST했다"는 신호만 전달된다. 서버는 "위에서 누가 끊었네"라는 사실만 알고, 이유를 모르므로 CANCELLED로 로깅한다. 장애 추적 시 양쪽 로그를 trace_id로 조인할 때 이 비대칭을 고려하지 않으면 "같은 요청인데 한쪽은 DE, 다른 쪽은 C"를 보고 혼란에 빠진다.

실무 가이드는 세 줄이다. 첫째, NTP를 신뢰하되 1초 이내 드리프트는 일상으로 간주한다. 데이터센터 안이면 보통 수 밀리초지만, 클라우드 가상 머신과 컨테이너 환경에서는 NTP가 동기화되기 전 부팅 직후에 수 초까지 벌어질 수 있다. 절대 시각 기반이므로 이 드리프트가 그대로 체감된다. 둘째, 대시보드에서 DEADLINE_EXCEEDED와 CANCELLED는 합쳐서 SLO 카운트를 잡는다. 분리해서 원인을 가르는 건 좋지만, SLO 위반 여부는 둘 다 "예산 내 응답 실패"이므로 묶어서 봐야 한다. 셋째, 양쪽 로그를 조인할 때는 trace_id 기준으로 매칭하고, 상태 코드 자체는 판단 기준에서 빼야 한다. 조인된 후에 양쪽의 실제 시각을 비교해 드리프트 크기를 별도 지표로 뽑아두면 장애 분석이 훨씬 쉬워진다.

7) Retry·Hedging·Circuit Breaker의 정합성

Retry를 잘못 걸면 Deadline보다 더 큰 장애를 만든다. 이 섹션이 5쌍 중 4번과 5번을 동시에 다룬다.

7-1) DEADLINE_EXCEEDED는 retryable이 아니다

가장 자주 틀리는 지점이다. gRPC-Java의 RetryPolicy는 serviceConfig.json 형식으로 retryable status를 지정할 수 있다. 처음 쓰는 팀은 "타임아웃은 당연히 재시도 대상"이라고 생각해 DEADLINE_EXCEEDED를 리스트에 집어넣는다. 이게 장애를 배수로 증폭시킨다.

이유는 단순하다. Deadline은 절대 시각이다. 첫 호출이 만료돼 DEADLINE_EXCEEDED가 돌아왔다는 건 이미 마감 시각이 지났다는 뜻이다. 재시도를 해도 남은 시간이 0이거나 음수다. gRPC-Java는 이 경우 재시도 자체를 하지 않고 즉시 에러를 돌려주지만, 몇몇 구현이나 외부 retry 레이어(스프링의 @Retryable, Resilience4j 등)가 이 규칙을 모르고 재시도하면 이미 끝난 호출을 서버에 다시 보내는 낭비가 생긴다. 서버 입장에서는 동일 호출이 두 번 들어와 부하만 두 배가 된다. 백엔드가 이미 과부하라 Deadline이 터졌을 텐데, 그 상태에 재시도가 더해지면 피드백 루프가 형성돼 장애가 확산된다.

retryable로 두는 건 일시적 인프라 장애를 나타내는 상태여야 한다. 구체적으로 UNAVAILABLE(14)만 기본 후보다. 드물게 RESOURCE_EXHAUSTED(8)도 포함할 수 있지만, 이건 서버가 "지금은 과부하"라고 명시적으로 말한 것이므로 재시도보다 backoff가 먼저다. 다른 상태는 각자 의미가 있으므로 재시도의 정당성이 없다. NOT_FOUND(5)는 재시도해도 여전히 없을 것이고, INVALID_ARGUMENT(3)는 재시도가 해결하지 않는 결함이다.

{
  "methodConfig": [{
    "name": [{"service": "bander.studio.v1.StudioService"}],
    "retryPolicy": {
      "maxAttempts": 3,
      "initialBackoff": "0.1s",
      "maxBackoff": "1s",
      "backoffMultiplier": 2,
      "retryableStatusCodes": ["UNAVAILABLE"]
    }
  }]
}

7-2) Retry budget을 남은 시간으로 재산정

maxAttempts: 3이라고 써놨어도, 남은 Deadline이 100ms면 세 번 시도할 수 없다. gRPC-Java의 재시도 구현은 각 시도 전에 남은 시간을 재계산한다. 남은 시간이 현재 backoff 값보다 작으면 더 시도하지 않고 즉시 마지막 에러를 리턴한다. 이 동작은 버그가 아니라 의도된 스펙이다. 대시보드에서 "maxAttempts=3인데 실제 시도 횟수는 1번만"인 현상을 버그로 오해하면 안 된다. 버그가 아니라 예산 소진이다.

추가로 고려할 건 전역 retry budget API다. 분당 허용되는 재시도 비율을 전역 예산으로 두고, 그 예산을 넘으면 신규 재시도를 일괄 차단한다. 예를 들어 "전체 요청의 10%까지만 재시도 허용"이라는 규칙이면, 분당 600 요청이 나갈 때 재시도 예산은 60회다. 이걸 넘으면 UNAVAILABLE이 와도 재시도하지 않고 클라이언트에 바로 올려 보낸다. 이 상한선은 백엔드 과부하 → 재시도 폭증 → 더 심한 과부하의 피드백 루프를 끊는 유일한 안전 장치다. Netflix, Google, Square 모두 운영 gRPC 스택에 이 상한을 명시적으로 건다.

숫자 잡기 예시: BANDER처럼 특정 서비스로 분당 600 요청이 나가는 환경에서 budget을 10%로 두면 60회/분이다. 백엔드가 일시적으로 5%의 UNAVAILABLE을 돌려주면 30회/분 정도의 재시도로 수렴한다. 여유 예산이 50% 남는 안전 구간이다. 백엔드가 20% 이상의 UNAVAILABLE을 돌려주기 시작하면 예산이 포화되고, 그 시점부터는 추가 재시도가 차단되면서 "재시도가 장애를 키우는" 구간으로 넘어가기 전에 차단된다. 10%라는 숫자는 Google SRE book의 기본 권고값이기도 하다.

7-3) Hedging은 이중 호출이다: 부하 배가

Hedging은 retry와 다른 개념이다. 첫 응답이 오기 전에 동일 요청을 병렬로 한 번 더 쏘고, 먼저 도착하는 쪽을 받는다. p99 지연을 줄이는 데 효과적이지만, 대가가 있다 — 백엔드 호출 수가 즉시 2배로 뛴다. 3번 hedge로 두면 3배다. 이게 계산에 없으면 "p99는 좋아졌는데 전체 부하가 2배가 됐다"는 상황이 나온다.

{
  "hedgingPolicy": {
    "maxAttempts": 2,
    "hedgingDelay": "0.3s",
    "nonFatalStatusCodes": []
  }
}

적용 기준은 엄격하다. 첫째, idempotent한 호출만 대상이다. 결제·예약·포인트 차감 같은 non-idempotent 호출에 hedging을 걸면 중복 과금·중복 예약이 난다. 이게 실제 사고로 나오는 경우가 꽤 많다. 둘째, 백엔드 용량에 여유가 있는 경우에만 적용한다. 부하가 90%를 넘은 서비스에 hedging을 걸면 즉시 100%를 넘겨 장애가 난다. 셋째, hedgingDelay를 p50보다 약간 길게 둬서 대부분의 호출은 첫 시도에서 끝나도록 설계한다. 구체적으로는 p50 × 1.5 정도가 일반적이다. 모든 호출에 동시에 두 번 쏘면 그건 hedging이 아니라 그냥 부하 테스트다.

7-4) Jitter와 Circuit Breaker의 시간 축 정합

재시도 backoff에는 반드시 jitter가 있어야 한다. 고정 backoff는 다수 클라이언트가 같은 순간 재시도해 Thundering Herd를 만든다. 100 대의 클라이언트가 모두 정확히 500ms 뒤에 재시도하면, 백엔드는 그 순간 100배의 부하 스파이크를 받는다. ±20% jitter가 일반적이다 — actualDelay = initialBackoff × random(0.8, 1.2). 이 무작위화 덕분에 재시도가 시간적으로 분산되어 스파이크가 완만해진다.

Circuit breaker와 Deadline의 정합성은 한 줄로 요약된다 — Open 상태에서도 Deadline은 같은 속도로 감소한다. 브레이커가 열려 호출이 즉시 fail-fast로 떨어지면 100ms도 안 걸려 리턴되지만, 그 100ms 동안에도 Context의 Deadline은 깎인다. 그리고 브레이커가 Half-open으로 바뀐 뒤 실제 호출이 나갈 때 "남은 시간이 이미 충분히 짧은" 상태라면, 그 호출은 거의 확실히 DEADLINE_EXCEEDED로 돌아온다. 이건 브레이커 관점에서 "실패한 호출"이 하나 더 생긴 것으로 집계돼 브레이커가 다시 Open으로 넘어간다. 영원히 Half-open → Open → Half-open을 반복하는 진동 상태에 빠지는 장애가 가끔 나온다.

해결은 Half-open 시점에 "남은 시간이 최소 임계값 이하면 그냥 fail-fast"로 두는 규칙을 브레이커에 심는 것이다. Resilience4j는 이 훅을 CallNotPermittedException 직전에 걸 수 있고, Hystrix는 historic하게 fallback에서 처리한다. 어느 구현을 쓰든 브레이커와 Deadline이 같은 시간 축을 본다는 원칙 하나는 유지해야 한다. 이 정합이 빠지면 retry 예산과 hedging 설정이 다 정교해도 브레이커 근처에서 SLA가 무너진다. 이게 §0의 5번 레이어가 별도 행으로 서 있는 이유다.

8) 3-hop 예산 전파 시퀀스: Client → Gateway → Service A → Service B

이 섹션이 §1 표의 "3초 공유"가 실제 wire에서 어떻게 흐르는지를 시퀀스로 보여준다. 각 홉에서 grpc-timeout 헤더의 값이 어떻게 깎여 나가는지, 그리고 체인 어딘가에서 Deadline이 끊어지면 어떻게 전파되는지를 본다.

8-1) 각 홉에서 grpc-timeout 값의 변화

초기 3000ms Deadline을 건 호출이 게이트웨이 → Service A → Service B 순으로 전파된다고 하자. 각 홉은 자신이 요청을 받은 시각과 내보낼 시각의 차이를 빼고, 남은 시간을 다시 헤더에 실어 보낸다.

홉	수신 시 남은 시간	자체 처리	다음 홉으로 보낼 grpc-timeout
Client → Gateway	3000 ms	20 ms (auth, routing)	`2980m`
Gateway → Service A	2980 ms	150 ms (비즈 로직)	`2830m`
Service A → Service B	2830 ms	50 ms (조립, fanout)	`2780m`
Service B 처리	2780 ms	2700 ms (DB 쿼리)	(응답 생성)

이 흐름에서 핵심은 각 홉이 남은 시간을 자체 시계로 측정한다는 것이다. wire에는 "남은 밀리초"가 실리고, 수신 서버는 자신의 시계로 "이제부터 N ms 안에 끝내야 한다"는 새 절대 시각을 다시 계산한다. 홉 간 시계가 ±50ms 드리프트면 전체 예산에서 150ms 정도가 불확실 구간이다. 3초 SLA에서 150ms는 받아들일 만한 오차다. 더 길어지면 Deadline이 실제보다 빡빡해지거나 느슨해져 체인 끝단에서 갑자기 터지는 경우가 생긴다.

실무에서는 각 홉이 자기 처리 시간을 로깅하는 것이 중요하다. 홉별 p50, p99를 대시보드에 찍어두면, 어느 홉이 예산의 얼마를 쓰고 있는지 한눈에 보인다. 위 예시에서 Gateway가 20ms, Service A가 150ms, Service B가 2750ms(DB 2700ms 포함)를 쓴다. 예산의 92%를 B가 쓰는 구조다. 이 비율이 정상 운영 기준이고, 여기서 B가 갑자기 2900ms를 쓰면 Deadline이 터진다. 대시보드가 "B의 쿼리가 느려졌다"를 먼저 알려줘야 한다.

8-2) 시퀀스 다이어그램

이 시퀀스에서 만약 Service B의 DB 쿼리가 5초 걸린다고 하자. B는 자신의 Context가 2830ms 지점에서 만료되는 걸 감지하고 DEADLINE_EXCEEDED를 A로 올린다. A는 자신의 Context도 이미 만료됐으므로 같은 상태 그대로 Gateway에, Gateway는 Client로 전파한다. 체인 전체가 약 3초 근처에 한꺼번에 끝난다. 이게 상대 타임아웃 모델과의 본질적 차이다. 상대 타임아웃이면 각 홉이 5초씩 기다려 최악 15초가 나왔을 것이다.

8-3) 여기서 틀리기 쉽다: 체인의 진입점

Gateway가 외부(HTTP) → 내부(gRPC) 변환 지점에 있으면 함정이 하나 더 있다. HTTP 요청에는 grpc-timeout 헤더가 없다. Gateway가 그 요청을 gRPC로 변환할 때 명시적으로 withDeadlineAfter를 호출해야 한다. 안 부르면 gRPC 체인 전체가 Deadline 없는 호출로 굴러가고, 위에서 짠 모든 전파 로직이 무의미해진다. 이 한 지점이 실무 사고의 단골이다.

더 나아가 "HTTP 요청의 X-Request-Timeout 같은 커스텀 헤더를 Gateway가 읽어서 Deadline으로 변환"하는 구조를 쓰는 팀도 있다. 이 경우 값이 없을 때의 기본값을 반드시 Gateway에 설정해야 한다. 없으면 Deadline 누락이 자동으로 생긴다. 체인의 출발점에서 Deadline을 반드시 심어야 한다는 원칙이 이 진입점에서 제일 중요하다. 나머지 모든 홉은 "받은 값을 그대로 계산"하지만, 진입점만은 값을 생성하는 책임을 진다.

9) 실무에서 이렇게 읽고 쓴다

채널 조립 코드를 열고 intercept(...) 라인을 찾는다. 없으면 Deadline은 동작하지 않는다. Duration 선언만 있는 건 dead config다. BANDER의 GrpcChannelFactory가 정확히 이 상태였다.
인터셉터 등록 순서를 확인한다. Deadline 인터셉터가 가장 먼저(가장 안쪽)에 와야 한다. 트레이싱·메트릭·인증 인터셉터는 바깥쪽에 둔다.
비동기 경계마다 Context.current().wrap(...)을 건다. CompletableFuture, Reactor publishOn, 가상 스레드 셋 다 해당된다. 자동 상속을 믿으면 안 된다. 가능하면 Context.currentContextExecutor로 executor 자체를 감싸는 쪽이 낫다.
서버 로직의 무거운 루프에 isCancelled() 폴링을 넣는다. 배치 쿼리·스트리밍 응답·외부 API 호출 직전에 체크 지점을 둔다. blocking I/O에는 addListener로 취소 훅을 건다.
RetryPolicy에서 DEADLINE_EXCEEDED를 제거한다. UNAVAILABLE만 기본 후보다. Hedging은 idempotent 호출에만, 백엔드 용량 여유가 있을 때만, hedgingDelay >= p50*1.5로 건다.
전역 retry budget을 분당 호출량의 10% 이내로 걸어둔다. Thundering Herd는 backoff ±20% jitter로 막는다.
Circuit breaker Half-open 시점에 남은 Deadline을 체크해서 임계값 이하면 fail-fast로 넘긴다. 진동 상태를 막는 유일한 방법이다.
대시보드에 DEADLINE_EXCEEDED와 CANCELLED를 같이 그린다. 분리하지 말고 합친 SLO로 본다. 원인 분리는 trace_id 조인 뒤에 한다.
장애 진단은 §0의 5쌍 표를 위에서부터 내려가며 본다. 1번이 서 있는지 먼저 확인하는 게 가장 빠르다.
NTP 드리프트 1초는 일상이다. Deadline 기반 로그 조인 시 양쪽 시계 차이를 전제로 둔다. 드리프트 자체를 별도 지표로 뽑는다.
Gateway 진입점에서 Deadline을 반드시 심는다. HTTP → gRPC 변환 지점이 체인의 출발점이고, 여기서 값을 생성하지 않으면 모든 하위 홉이 Deadline 없이 흐른다.

10) 한 줄 정리

Deadline은 설정 값이 아니라 다섯 레이어가 동시에 서야 동작하는 협업이다. 인터셉터 등록·서버 취소 감지·Context 전파·Retry 예산·브레이커 정합 중 하나만 빠져도 3초 SLA가 9초가 된다. 가장 먼저 확인할 지점은 채널 빌더에 intercept(...)가 붙어 있는지 — 이게 전부의 출발점이다.

부록 A) 운영 체크리스트

확인 항목	통과 기준
`ClientInterceptor`로 Deadline 주입	채널 빌더에 `intercept(deadlineInterceptor)` 한 줄 존재
인터셉터 등록 순서	Deadline이 가장 안쪽(가장 먼저 등록)
Wire 확인	HTTP/2 HEADERS 프레임에 `grpc-timeout` 헤더 존재 (Wireshark 또는 서버 인터셉터 로그)
서버 취소 감지	무거운 루프에 `isCancelled()` 폴링 또는 `addListener` 훅
비동기 경계 wrap	`CompletableFuture` / Reactor / 가상 스레드 경계에 `Context.wrap` 또는 context-aware executor
RetryPolicy 대상 상태	`UNAVAILABLE`만 포함, `DEADLINE_EXCEEDED` 제외
전역 retry budget	분당 전체 요청의 10% 이내
Backoff jitter	±20% 이상
Hedging 적용 기준	idempotent + 백엔드 여유 + `hedgingDelay >= p50*1.5`
Circuit breaker Half-open	남은 Deadline이 임계값 이하면 fail-fast
시계 동기화	NTP 운영, 드리프트 ±1s 알람
Gateway 진입점	HTTP → gRPC 변환 시 `withDeadlineAfter` 명시 호출
대시보드	DE + C 합산 SLO, 홉별 p99, 드리프트 별도 지표

태그: gRPC, Deadline, Cancellation, io.grpc.Context, ClientInterceptor, Retry, Hedging, CircuitBreaker, HTTP/2, Spring

gRPC Streaming Deep Dive — 4가지 모드는 왜 프로토콜이 하나인가

dding-shark — Wed, 15 Apr 2026 08:23:09 +0900

gRPC Streaming Deep Dive — 4가지 모드는 왜 프로토콜이 하나인가

들어가며

gRPC 입문서를 펼치면 거의 예외 없이 같은 네 줄이 등장한다. Unary, Server-streaming, Client-streaming, Bidirectional. 네 가지 "모드"라는 표현 때문에 처음 보는 개발자는 이걸 네 개의 다른 프로토콜 내지는 네 종류의 다른 커넥션처럼 읽는다. 한 줄로 바로잡자면, 네 모드는 한 HTTP/2 stream 위에서 "요청 메시지가 1개냐 N개냐" × "응답 메시지가 1개냐 N개냐"의 2×2 매트릭스일 뿐이다. 프로토콜은 하나고, wire 포맷도 동일하고, HEADERS·DATA·trailer HEADERS라는 프레임 흐름의 대골격도 같다. 달라지는 건 .proto의 stream 키워드 위치와 — 그 위치가 강제하는 Java stub의 종류, StreamObserver의 라이프사이클, 그리고 flow control을 누가 책임지는가 — 이 세 가지다.

BANDER의 grpc-contracts를 열어보면 이 지점이 곧바로 체감된다. media_service.proto의 서비스 정의에는 rpc 선언이 두 개 들어 있는데, 어느 쪽에도 stream 키워드가 없다.

rpc CreateUploadGrant(CreateUploadGrantRequest) returns (CreateUploadGrantResponse);
rpc ValidateOwnership(ValidateOwnershipRequest) returns (google.protobuf.Empty);

studio_service.proto도 같다. CreateStudio, UpdateStudioBasicInfo, GetStudioDetail, AssertStudioOwnership 전부 Unary다. 즉 BANDER의 현재 grpc-contracts에는 스트리밍 메서드가 한 개도 없다. 이게 이상한 구성이 아니라 오히려 전형적이다. 서비스 간 호출 대부분은 요청 한 건에 응답 한 건으로 충분하고, 스트리밍이 구조적으로 필요한 순간은 생각보다 좁다. 이 글은 그 좁음의 이유를 먼저 프로토콜 레벨에서 설명하고, 스트리밍이 꼭 필요해지는 지점에서 어떤 함정이 기다리는지를 모드별로 한 층씩 뜯는다.

이 글을 읽기 전에 막히기 쉬운 지점을 먼저 깔아두자. 네 모드를 처음 구현할 때 거의 모두가 같은 다섯 개를 밟는다.

네 모드는 서로 다른 프로토콜이 아니다 — 같은 HTTP/2 stream 위에서 메시지 카운트 계약만 달라진 네 가지 형태이고, 그래서 wire 포맷과 trailer grpc-status 규약도 모두 동일하다
BlockingStub으로 Client-streaming·Bidi 메서드를 호출할 수 없다 — 호출이 런타임에 터지는 게 아니라 stub에 해당 메서드가 아예 생성되지 않기 때문에 컴파일부터 막힌다
Server-streaming Iterator.hasNext()는 마지막 메시지 뒤에서 무한 블록된다 — Deadline 없이 쓰면 네트워크가 조용히 끊긴 케이스에서 호출 스레드가 영영 돌아오지 않는다
Client-streaming에서 requestObserver.onCompleted()를 빼먹으면 서버가 영원히 기다린다 — half-open stream이 누적되면서 파일 디스크립터와 힙 메모리가 조용히 샌다
Bidi에서 isReady()를 보지 않고 onNext()를 계속 부르면 outbound 버퍼가 힙에 쌓인다 — HTTP/2 flow control 창을 넘는 순간부터 gRPC는 메시지를 JVM 힙에 적재하기 때문에 결국 OOM으로 간다

이 글은 프로토콜 계약 → stub 매트릭스 → 4 모드 개별 해부 → 적용 경계 → 운영 checklist 순으로 간다. 시리즈 1편("HTTP/2 위에서 RPC는 왜 다시 태어났는가")과 2편("Deadline과 Interceptor")을 전제로 하므로, 아직 안 읽었다면 같이 보는 게 좋다.

1) HTTP/2 stream 위 메시지 수 계약
2) Java stub 매트릭스: 세 stub × 네 모드
3) Unary — 기본값이 기본인 구조적 이유
4) Server-streaming — Iterator vs StreamObserver
5) Client-streaming — AsyncStub와 StreamObserver 라이프사이클
6) Bidirectional — 독립 타이밍과 flow control
7) 적용 경계 — grpc-web과 HTTP/2 프록시
8) 운영 checklist 종합
9) 실무에서 이렇게 읽고 쓴다
10) 마치며 — 한 줄 정리

1) HTTP/2 stream 위 메시지 수 계약

gRPC 네 모드가 "사실 같은 프로토콜"이라는 말을 이해하려면 HTTP/2의 stream과 gRPC의 논리 메시지가 서로 다른 레이어라는 점부터 분리해야 한다. HTTP/2 stream은 한 번의 요청-응답 쌍을 담는 논리 채널이고, 한 TCP 커넥션 위에 수백 개가 동시에 멀티플렉싱되어 흐를 수 있다. stream은 클라이언트의 HEADERS 프레임으로 열리고, 양쪽 방향에 END_STREAM 플래그가 붙을 때까지 살아 있다. 그 안에서 DATA 프레임이 몇 개가 흐르든, 그리고 그 DATA 프레임들이 담고 있는 "논리 메시지"가 몇 개든, 둘은 1:1로 매칭될 필요가 없다.

gRPC는 이 DATA 프레임 안에 한 겹 더 framing을 씌운다. 1편에서 본 5바이트 length-prefixed framing — [압축 플래그 1B][메시지 길이 4B 빅엔디안][Protobuf 페이로드 N B] — 이다. 이 framing 덕분에 한 stream 위에 논리 메시지를 몇 개든 순서대로 흘려보낼 수 있고, 수신측은 TCP 세그먼트 경계와 무관하게 메시지 경계를 식별한다. 그리고 HTTP/2 stream이 양방향 독립 half-close를 허용하므로, 한 쪽이 END_STREAM을 올려 자기 방향을 닫아도 반대 방향은 계속 흐를 수 있다.

이 두 성질만 있으면 네 모드는 저절로 나온다. "요청 메시지 1 vs N"과 "응답 메시지 1 vs N"의 조합이 정확히 네 칸이고, 그 네 칸이 네 모드에 일대일로 대응한다. 다섯 번째 모드가 없는 건 이론적 한계 때문이 아니라 이 매트릭스가 이미 닫혀 있기 때문이다.

모드	요청 메시지 수	응답 메시지 수	half-close 타이밍	전형적 사용처
Unary	1	1	요청·응답 직후 양방향 동시	조회·명령 대부분
Server-streaming	1	N	클라가 요청 직후 먼저 half-close	실시간 피드, 구독
Client-streaming	N	1	클라가 마지막 요청 후 half-close	로그 일괄 업로드
Bidirectional	N	N	양쪽 독립 타이밍	채팅, IoT 제어 루프

이 표에서 주의해서 볼 건 마지막 컬럼이 아니라 half-close 타이밍 컬럼이다. 네 모드의 실제 동작 차이는 "메시지 수"보다 "양쪽이 언제 자기 방향을 닫는가"에서 온다. Unary는 양쪽이 거의 동시에 닫는 특수 케이스이고, Server-streaming은 클라이언트가 요청을 보내자마자 먼저 자기 방향을 닫는다. Client-streaming은 클라이언트가 요청을 다 보내고 half-close하면 그제야 서버가 응답 한 건을 돌려주는 순서 계약이 있다. Bidi는 이 순서 계약이 없고, 양쪽이 완전히 독립적으로 자기 방향을 닫는다.

이 시퀀스에서 꼭 두 가지를 확인해야 한다. 첫째, 네 모드 모두 HEADERS → DATA* → trailer HEADERS(END_STREAM) 라는 대골격이 완전히 동일하다는 점이다. 응답 종료 시점에 trailer HEADERS 프레임으로 grpc-status를 돌려주는 규약도 같다. 스트리밍이라고 해서 별도의 프레임 타입이나 별도의 상태 전달 채널이 생기는 게 아니라, 단지 DATA 프레임이 여러 개로 늘어날 뿐이다. 둘째, Bidi의 진짜 특징은 "양방향"이 아니라 타이밍 독립성이다. Req_1이 나간 직후에 Resp_1이 돌아올 수 있고, Req_2는 Resp_1과 무관하게 다음에 보낼 수 있다. 이 독립성이 Bidi 설계의 모든 어려움의 출발점이고, 나머지 세 모드는 이 독립성의 일부를 포기한 특수 케이스로 읽을 수 있다. 자세한 wire 스펙은 gRPC PROTOCOL-HTTP2에 정리돼 있다.

2) Java stub 매트릭스: 세 stub × 네 모드

.proto를 protoc으로 Java 코드 생성하면 서비스당 정확히 세 개의 stub 클래스가 나온다. BlockingStub, Stub(Async), FutureStub이다. 이 세 stub은 지원하는 모드가 겹치지 않고, 특정 모드에서는 해당 stub에 메서드 자체가 생성되지 않는다. 이게 gRPC의 컴파일 타임 안전망이면서, 동시에 처음 오는 개발자가 "내 IDE가 왜 이 메서드를 못 찾지?"로 막히는 지점이기도 하다. 이 매트릭스를 외워두지 않으면 Client-streaming·Bidi 설계 단계에서 stub 선택을 잘못하고, 그 대가를 코드 리팩토링으로 치르게 된다.

Stub	Unary	Server-streaming	Client-streaming	Bidirectional
`BlockingStub`	O (동기 반환)	O (`Iterator<Resp>` 반환)	X (생성 안 됨)	X (생성 안 됨)
`Stub` (Async)	O (`StreamObserver` 콜백)	O (`StreamObserver` 콜백)	O (`StreamObserver<Req>` 반환)	O (`StreamObserver<Req>` 반환)
`FutureStub`	O (`ListenableFuture`)	X (생성 안 됨)	X (생성 안 됨)	X (생성 안 됨)

선택 원칙은 생각보다 단순하다. Unary만 쓰는 서비스면 셋 다 가능한데, 블로킹 호출이 자연스러우면 BlockingStub, CompletableFuture와 합성해야 하면 FutureStub을 고른다. Server-streaming이 섞인다면 BlockingStub(Iterator)로도 쓸 수는 있지만, 실전에서는 Async Stub이 제어가 훨씬 쉽다 — 뒤에 나오는 무한 블록 함정 때문이다. Client-streaming이나 Bidi가 메서드 목록에 하나라도 있으면, 클라이언트는 Stub(Async)로 통일한다. 다른 선택지가 없기 때문이다.

이 매트릭스가 왜 이렇게 짜였는지는 JVM 스레드 모델을 조금만 생각해보면 자명하다. Client-streaming과 Bidi는 같은 stream 위에 요청을 여러 번 나눠 보내는 동안 응답이 독립적으로 돌아올 수 있어야 하는데, 그러려면 한 메서드가 "요청을 보낸 뒤 블록하고 응답을 기다린다"는 동기 API로는 설계가 불가능하다. BlockingStub이 "보내는 동안 응답이 함께 올 수 있다"는 동작을 표현할 방법이 없기 때문이다. 그래서 protoc은 이 두 모드를 BlockingStub·FutureStub에 아예 생성하지 않는다. 문서로 "이건 Async stub을 쓰세요"라고 권고하는 수준이 아니라, 컴파일러가 그걸 강제한다. 컴파일 에러가 가장 좋은 문서라는 원칙이 여기서도 관철된다.

이 비대칭의 또 다른 결과는, Bidi를 쓰는 순간 클라이언트 코드베이스 전체가 Async 스타일로 기울어진다는 점이다. Async Stub은 반환값 대신 StreamObserver 콜백으로 결과를 받기 때문에, 호출부가 "다음 줄에서 결과를 쓴다"는 동기 코드 흐름을 유지할 수 없다. 그래서 Bidi 하나 때문에 서비스 전반의 호출 스타일이 async로 바뀌고, 에러 처리도 try/catch가 아닌 onError 콜백으로 옮겨간다. 이 전환 비용이 작지 않기 때문에, 설계 단계에서 "정말 Bidi가 필요한가"를 한 번 더 검토해야 한다. 대부분의 경우는 Unary + repeated 필드로 충분하다.

3) Unary — 기본값이 기본인 구조적 이유

Unary는 네 모드 중 가장 평범하고, 동시에 가장 많이 쓰인다. BANDER가 전 서비스 Unary만 쓰는 것도 이 "평범함"이 실전에서 거의 항상 충분하기 때문이고, 그 평범함을 이해하면 나머지 세 모드로 넘어갈 때의 비용이 명확해진다. 이 섹션은 Unary의 구조적 이유, BANDER의 실제 구성, Unary의 한계가 시작되는 지점, 그리고 Unary를 떠나기 전에 먼저 고려해야 하는 repeated 대체 범위까지 네 층으로 정리한다.

3-1) 구조적 이유 — stream 1개 = 요청 1 + 응답 1

Unary의 wire 레벨 동작은 1편에서 한 번 다뤘다. 클라이언트가 HEADERS 프레임 하나와 DATA 프레임 하나를 END_STREAM 플래그와 함께 보내고, 서버가 HEADERS + DATA + trailer HEADERS의 세 프레임으로 응답한다. HTTP/2 stream 하나가 이 교환에 정확히 맞춰 열렸다 닫힌다. 여기서 흔히 오해되는 지점은 "Unary는 블로킹이니까 HTTP/2 멀티플렉싱의 이득을 못 받는다"는 쪽인데, 정확히 반대다. 한 ManagedChannel이 한 HTTP/2 커넥션 위에서 동시에 수백 개의 Unary stream을 병렬로 띄운다. 블로킹되는 건 호출 스레드이지 채널이 아니다. 그래서 Unary가 "순수한 1요청-1응답이라서 느리다"는 감각은 틀렸고, 성능 관점에서 Unary가 스트리밍 모드보다 본질적으로 느릴 이유가 없다.

Unary가 단순한 또 다른 이유는 에러 전달 경로가 정확히 한 번 일어난다는 점이다. 서버가 중간에 예외를 던지면 trailer HEADERS에 grpc-status=13(INTERNAL)이 실려서 한 번 돌아오고, 그걸로 끝이다. 스트리밍 모드는 응답 메시지를 여러 개 보낸 뒤 50번째에서 에러가 나는 상황을 다뤄야 하는데, Unary는 그 상황 자체가 없다. 에러 처리 코드가 try/catch 한 블록으로 끝나는 이 단순함이 Unary의 운영상 가장 큰 장점이다.

3-2) BANDER 전 서비스 Unary 실사례

BANDER의 grpc-contracts에서 실제 .proto를 그대로 꺼내 보자. media_service.proto의 서비스 블록은 두 줄이 전부다.

rpc CreateUploadGrant(CreateUploadGrantRequest) returns (CreateUploadGrantResponse);
rpc ValidateOwnership(ValidateOwnershipRequest) returns (google.protobuf.Empty);

요청에도 응답에도 stream 키워드가 없다. studio_service.proto 역시 CreateStudio, UpdateStudioBasicInfo, GetStudioDetail, AssertStudioOwnership 네 개의 RPC가 전부 Unary다. BANDER의 현재 grpc-contracts에는 스트리밍 RPC가 단 한 개도 없다. 이게 "아직 스트리밍 쓸 줄 모르는 초기 조직"의 징후가 아니라, 역으로 스트리밍이 구조적으로 필요한 요구가 아직 없다는 정직한 상태 표시다. 업로드는 요청 한 건(= URL grant를 받고 실제 바이트는 S3로 직송)으로 끝나고, 검증은 요청 한 건에 Empty 응답 한 건으로 끝난다. 여기서 스트리밍을 끼워 넣을 자리가 없다.

이 단순함은 클라이언트 쪽 구성에도 그대로 반영된다. GrpcChannelFactory를 보면 딱 필요한 만큼만 써 있다.

public class GrpcChannelFactory {

    public ManagedChannel createChannel(GrpcClientProperties properties) {
        ManagedChannelBuilder<?> builder = ManagedChannelBuilder.forAddress(
                properties.getHost(), properties.getPort());
        if (properties.isPlaintextEnabled()) {
            builder.usePlaintext();
        }
        return builder.build();
    }
}

Interceptor 체인도, keepalive 튜닝도, flow control 설정도 없다. Unary 전용이므로 필요가 없기 때문이다. 그리고 GrpcClientProperties의 기본 Deadline이 5초다.

private String host = "localhost";
private int port = 9090;
private Duration deadline = Duration.ofSeconds(5);
private boolean plaintextEnabled = true;

여기서 "5초"라는 숫자가 Unary라서 가능한 값이라는 점을 반드시 짚어야 한다. Unary는 호출당 응답이 정확히 한 번 돌아오니까 "5초 안에 끝나야 한다"는 계약이 자연스럽다. 뒤에 나올 Server-streaming·Bidi는 이 5초를 그대로 쓸 수 없다 — 스트림 전체가 살아 있을 예상 시간은 응답 한 건 처리 시간과는 다른 차원의 숫자이기 때문이다. BANDER가 이 5초를 불편 없이 쓸 수 있는 이유는 전 서비스 Unary라는 전제 덕이다. 스트리밍 RPC가 한 개라도 추가되는 순간, Deadline 설계는 모드별로 분리해야 한다.

3-3) 한계와 전환 기준

Unary로 표현이 안 되는 순간은 의외로 명확하다. 세 가지 중 하나에 해당하면 Unary를 떠나야 한다.

첫째, 응답이 구조적으로 여러 개이고 실시간성이 있는 경우다. 실시간 이벤트 피드, 업로드 진행률 푸시, 실시간 가격 스트림처럼 "지금 생긴 값을 지금 받아야" 하는 흐름은 Unary로는 표현이 어렵다. 폴링으로 흉내 내는 건 가능하지만, 폴링 주기보다 짧은 이벤트는 놓치고 주기보다 긴 이벤트는 지연된다. 둘째, 요청이 구조적으로 여러 개이고 전체가 메모리에 한 번에 안 올라오는 경우다. 수 GB 로그 일괄 업로드, 대용량 파일 chunked upload 같은 흐름이 여기에 속한다. 한 요청 메시지에 전부 담으면 Protobuf 파싱 시점에 힙이 터진다. 셋째, 양방향 독립 대화가 필요한 경우다. 채팅, IoT 센서와 제어 루프 사이의 대화, 실시간 협업 편집(OT/CRDT)처럼 양쪽이 자유 타이밍으로 메시지를 주고받아야 하는 흐름은 Bidi가 아니면 표현 자체가 불가능하다.

이 셋 중 어느 것도 해당되지 않으면 Unary가 정답이다. 그리고 "응답이 여러 개이긴 한데 실시간성은 없다"는 중간 영역이 가장 흔한데, 여기서 곧바로 Server-streaming으로 가는 건 성급한 결정이다. 그 중간은 대부분 repeated 필드로 풀린다.

3-4) `repeated`로 풀 수 있는 범위

Protobuf repeated는 배열 필드이고, 한 메시지 안에 같은 타입의 요소를 여러 개 담을 수 있다. "결과가 100개"를 Server-streaming으로 풀지, 아니면 repeated Item items가 담긴 Unary 응답 한 건으로 풀지는 결과 집합의 크기가 경계를 가지는가, 실시간성이 있는가, 클라가 일부만 받고 중단할 수 있어야 하는가, 이 세 조건으로 갈린다.

// 선호: 결과 크기가 경계를 가지고 실시간성이 없을 때 — Unary + repeated + pagination
rpc ListStudios(ListStudiosRequest) returns (ListStudiosResponse);

message ListStudiosRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListStudiosResponse {
  repeated Studio studios = 1;
  string next_page_token = 2;
}

// 피하기: 실시간성 없고 결과 크기도 경계 있는데 Server-streaming으로 간다
rpc ListStudios(ListStudiosRequest) returns (stream Studio);

Server-streaming이 정당화되는 지점은 두 가지다. 첫째, 결과가 실시간 이벤트여서 "모아서 한 번에"라는 전략이 의미가 없을 때. 예를 들어 스튜디오 상태 변경 구독(SubscribeStudioEvents)은 언제 이벤트가 올지 모르니 Unary로 묶을 단위가 없다. 둘째, 전체 결과 크기가 메모리 한계를 넘고, 동시에 클라이언트가 일부만 받고 cancel할 수 있어야 할 때. 이 조건이 아니면 pagination이 달린 Unary가 훨씬 단순하고, 디버깅하기 쉽고, 에러 전파 경로가 한 번뿐이어서 운영이 편하다. BANDER가 이 선을 지키고 있는 것도 같은 이유에서다 — 스튜디오 목록이나 미디어 목록을 반환해야 하는 요구가 생기면, 일단 repeated + pagination으로 푼다. 스트리밍은 그 뒤의 선택지다.

4) Server-streaming — Iterator vs StreamObserver

요청 한 건에 응답 N건을 받는 모드다. 대표적인 사용처는 실시간 이벤트 구독, 서버가 자기 내부 상태 변화를 클라이언트에 밀어주는 구독형 API, 그리고 결과 집합이 수만~수십만 건이고 순차적으로 소비해야 하는 대용량 목록 조회 정도다. Server-streaming을 Java에서 쓸 때는 두 가지 스타일이 있는데, BlockingStub의 Iterator와 Stub(Async)의 StreamObserver 콜백이다. 둘은 같은 wire 동작을 API 레벨에서 다르게 노출할 뿐이지만, 함정의 모양은 완전히 다르다.

4-1) BlockingStub의 Iterator 반환

BlockingStub은 Server-streaming RPC를 Iterator<Resp>로 반환한다. 코드 모양이 동기적이라 읽기 편하고, for-each 루프와 자연스럽게 어울린다.

StudioServiceGrpc.StudioServiceBlockingStub blocking =
    StudioServiceGrpc.newBlockingStub(channel)
        .withDeadlineAfter(10, TimeUnit.MINUTES);

Iterator<StudioEvent> it = blocking.subscribeStudioEvents(req);
while (it.hasNext()) {
    StudioEvent event = it.next();
    handle(event);
}

hasNext()는 다음 메시지가 도착할 때까지 현재 스레드를 블록한다. 새 메시지가 도착하면 next()로 꺼낸다. 서버가 trailer HEADERS로 grpc-status=0을 보내 스트림을 정상 종료하면 hasNext()가 false로 떨어지고 루프가 끝난다. 서버가 grpc-status=4(DEADLINE_EXCEEDED)나 13(INTERNAL) 같은 에러로 종료하면, hasNext() 또는 next()가 StatusRuntimeException을 던지며 루프가 깨진다.

4-2) 여기서 틀리기 쉽다 — 무한 블록 함정

문제는 서버가 종료 trailer를 안 보내는 상황이다. 구독형 API에서 "이벤트가 없으면 다음 이벤트가 올 때까지 기다린다"가 정상 동작이면, hasNext()는 다음 이벤트가 도착할 때까지 영원히 블록된다. 여기까지는 설계가 의도한 동작이니 문제가 아니다. 진짜 문제는 네트워크가 조용히 끊겼거나 서버가 죽어서 더 이상 어떤 메시지도 오지 않는 상황이다. TCP keepalive가 이걸 검출하는 데는 OS 기본 설정 기준 수 분~수십 분이 걸리고, 그동안 호출 스레드는 hasNext()에서 움직이지 않는다. 스레드 풀 크기가 제한된 서비스에서는 이게 곧 가용 스레드 고갈로 이어진다.

// 피하기: Deadline 없이 Server-streaming BlockingStub
Iterator<Event> it = blocking.subscribe(req);
while (it.hasNext()) {                         // 네트워크 끊기면 영영 안 끝남
    handle(it.next());
}

// 선호: Deadline을 스트림 전체 생애주기로 명시
Iterator<Event> it = blocking
    .withDeadlineAfter(10, TimeUnit.MINUTES)
    .subscribe(req);
while (it.hasNext()) {
    handle(it.next());
}

여기서 꼭 짚어야 하는 게 있다. Server-streaming에서 Deadline은 스트림 전체가 살아 있을 최대 시간으로 해석해야 한다. Unary에서의 "응답 하나 받는 데 걸리는 시간"이 아니다. BANDER의 GrpcClientProperties 기본값인 5초를 Server-streaming에 그대로 쓰면, 정상적으로 이벤트를 주고받는 스트림도 5초 뒤에 DEADLINE_EXCEEDED로 끊긴다. 스트리밍 API를 추가하는 시점에 GrpcClientProperties의 Deadline 필드를 "모드별로 구분"하거나, 호출부에서 명시적으로 withDeadlineAfter를 다시 지정해야 한다. 이 숫자는 구독 API의 기대 세션 길이에 맞춰 설계 결정해야 하는 값이지, 기본값을 그대로 빌려 쓸 값이 아니다.

두 번째로, gRPC keepalive와 HTTP/2 PING을 켜 두는 게 무한 블록 함정의 두 번째 방어선이다. keepAliveTime을 짧게(30초 정도) 걸어두면 TCP가 조용히 끊긴 경우에도 gRPC 레벨에서 PING 타임아웃으로 감지해 UNAVAILABLE 에러를 던져준다. 이건 1편에서 다룬 keepalive 설정이 Server-streaming에서 특히 중요해지는 이유다.

4-3) Async Stub — StreamObserver 콜백

Stub(Async)를 쓰면 Iterator 대신 StreamObserver로 메시지가 콜백으로 들어온다. 호출 스레드를 블록하지 않으므로 스레드 고갈 위험이 없고, onError와 onCompleted를 명시적으로 처리하도록 API가 강제한다.

StudioServiceGrpc.StudioServiceStub async =
    StudioServiceGrpc.newStub(channel);

async.withDeadlineAfter(10, TimeUnit.MINUTES)
     .subscribeStudioEvents(req, new StreamObserver<StudioEvent>() {
    @Override public void onNext(StudioEvent event) {
        handle(event);                          // gRPC 워커 스레드에서 호출
    }
    @Override public void onError(Throwable t) {
        // DEADLINE_EXCEEDED, UNAVAILABLE, 서버 INTERNAL 등이 여기로
        log.error("stream failed", t);
    }
    @Override public void onCompleted() {
        log.info("stream closed normally");
    }
});

onNext는 gRPC 워커 스레드 풀에서 호출된다. 여기서 DB 호출이나 다른 블로킹 I/O를 하면 같은 풀을 공유하는 다른 stream의 진행을 막는다. 무거운 처리는 별도 실행기로 오프로드해야 하고, 그때 순서 보존이 필요하면 단일 스레드 실행기에 넣어야 한다. 그리고 onError와 onCompleted는 정확히 하나만 호출된다는 계약을 기억해야 한다 — 둘 다 오거나, 둘 다 안 오는 경우는 없다. 이 계약을 어기는 gRPC 구현은 버그다.

5) Client-streaming — AsyncStub와 StreamObserver 라이프사이클

요청 N건을 보내고 응답 1건을 받는 모드다. 대용량 파일/로그 일괄 업로드, 센서 데이터 누적 전송, 클라이언트가 배치로 모은 변경사항을 한 번에 커밋하는 흐름에 쓴다. BlockingStub에는 Client-streaming 메서드가 생성되지 않는다. 이유는 앞서 설명한 대로다 — 요청을 여러 번 나눠 보내는 동안 동기적으로 블록할 수 없기 때문이다. 그래서 Client-streaming을 쓰는 순간 해당 서비스의 클라이언트는 Async Stub으로 고정된다.

5-1) 호출 패턴 — 방향이 반대인 두 observer

Client-streaming의 호출 코드는 처음 보면 두 개의 StreamObserver가 등장해서 헷갈린다. 하나는 "서버가 보내는 응답을 받기 위해 클라가 만든" observer이고, 다른 하나는 "클라가 서버로 요청을 보내기 위해 gRPC가 돌려준" observer다. 방향이 반대여서, 이름을 헷갈리면 한참 막힌다.

// .proto: rpc UploadLogs(stream LogEntry) returns (UploadResponse);

// (1) 서버 응답을 받는 observer — 클라이언트가 구현
StreamObserver<UploadResponse> responseObserver = new StreamObserver<>() {
    @Override public void onNext(UploadResponse resp) {
        log.info("upload ack: count={}", resp.getCount());
    }
    @Override public void onError(Throwable t) {
        log.error("upload failed", t);
        latch.countDown();
    }
    @Override public void onCompleted() {
        latch.countDown();
    }
};

// (2) 클라가 요청을 보내는 observer — gRPC가 반환
StreamObserver<LogEntry> requestObserver =
    async.withDeadlineAfter(2, TimeUnit.MINUTES)
         .uploadLogs(responseObserver);

try {
    for (LogEntry entry : entries) {
        requestObserver.onNext(entry);          // 요청을 N번 푸시
    }
    requestObserver.onCompleted();              // half-close
} catch (RuntimeException e) {
    requestObserver.onError(
        Status.INTERNAL.withDescription("client failed: " + e.getMessage()).asException()
    );
    throw e;
}
latch.await();

async.uploadLogs(responseObserver) 한 호출로 stream이 열리고, gRPC가 StreamObserver<LogEntry>를 반환한다. 이 반환값에 대고 onNext(entry)를 N번 부른 뒤 onCompleted()를 부르면 클라→서버 방향이 닫히고, 그제야 서버가 응답 한 건을 responseObserver.onNext(resp)로 돌려준다. 그 직후 서버가 자기 쪽 onCompleted()를 부르면서 stream이 완전히 종료된다. 이 순서 계약은 Bidi와 다르다 — Bidi는 양방향 독립이지만 Client-streaming은 "클라가 먼저 다 보내고, 서버가 그다음에 응답"이라는 순서가 강제된다.

5-2) StreamObserver 라이프사이클 — `onNext*` `(onError | onCompleted)`

gRPC StreamObserver의 메서드 호출 계약은 정규식 한 줄로 요약된다.

onNext* (onError | onCompleted)

즉 onNext가 0회 이상 호출되고, 그 뒤에 onError 또는 onCompleted가 정확히 하나 호출되며, 그 이후에는 어떤 메서드도 호출되지 않는다. 이 계약은 gRPC 공식 문서에도 그대로 명시돼 있고, 구현이 이걸 어기는 건 버그로 취급된다. 문제는 클라이언트 쪽 애플리케이션 코드가 자기 requestObserver를 다룰 때 이 계약을 자주 깬다는 점이다. 두 가지가 가장 흔하다.

첫째, requestObserver.onCompleted()를 빼먹는다. 루프를 다 돌고 빠져나오면서 종료 호출을 잊으면, 서버는 "요청이 더 올지도 모른다"고 판단해 Deadline이 만료될 때까지 기다린다. Deadline을 안 걸었다면 영원히 기다린다. half-open stream이 서버 쪽에 쌓이면서 파일 디스크립터와 힙이 조용히 샌다. 이걸 방지하는 가장 안전한 방법은 try/finally로 onCompleted()를 감싸는 게 아니라, try/catch로 감싸서 정상 경로에서는 onCompleted()를, 예외 경로에서는 onError()를 각각 호출하도록 분기하는 것이다. try/finally 안에 onCompleted()를 넣으면 예외가 나도 onCompleted가 불려서 에러 상태가 서버에 전달되지 않는다.

둘째, onNext() 도중 예외가 터졌는데 onError()를 안 부른다. 루프 안에서 파일 읽기 예외가 나면 그 순간 RuntimeException이 올라오는데, 이걸 catch하지 않고 그대로 호출부로 전파하면 stream은 여전히 열려 있는 상태다. 서버는 여전히 다음 메시지를 기다리고, 클라는 stack unwind로 빠져나가면서 requestObserver 참조를 잃어버린다. 이게 가장 흔한 half-open 누수 패턴이다.

5-3) `Status.asException`으로 명시적 에러 래핑

서버 쪽이든 클라이언트 쪽이든, StreamObserver에 Throwable을 넘길 때는 Status 객체로 한 번 래핑하는 게 안전하다. 그래야 grpc-status가 정확한 값으로 찍히고, description도 살아서 상대방에 전달된다.

// 피하기: 일반 RuntimeException을 그대로 onError에 넘김
requestObserver.onError(new RuntimeException("invalid entry"));
// 수신측에서는 grpc-status=2 UNKNOWN으로 오고 이유를 알 수 없음

// 선호: Status.X.withDescription(...).asException()으로 래핑
requestObserver.onError(
    Status.INVALID_ARGUMENT
          .withDescription("entry payload exceeds 1MB")
          .asException()
);
// 수신측에서는 grpc-status=3 INVALID_ARGUMENT + description이 함께 옴

일반 예외를 그대로 onError로 넘기면 gRPC는 이걸 Status.UNKNOWN(코드 2)으로 래핑하고 description도 대부분 누락된다. 운영 로그에서 UNKNOWN이 잔뜩 찍히는 시스템은 거의 예외 없이 이 래핑을 안 하고 있다. 최소한 Status.INTERNAL.withCause(e).withDescription(e.getMessage()).asException() 정도는 쓰는 게 옳다. 그리고 Status.asException과 Status.asRuntimeException이 따로 있는데, Client-streaming 호출부에서는 checked 예외를 던질 수 없으니 asRuntimeException이 편하고, 서버 핸들러에서는 어느 쪽이든 상관없다.

6) Bidirectional — 독립 타이밍과 flow control

요청 N건, 응답 N건, 그리고 둘의 타이밍이 완전히 독립적인 모드다. 채팅, IoT 센서와 제어 서버 사이의 양방향 루프, 실시간 협업 편집 같은 곳에 쓴다. 네 모드 중 설계 난이도가 압도적으로 높다. "가장 유연하다"는 말은 실전에서 "실수할 공간이 가장 넓다"와 같은 뜻이기 때문이다. 이 섹션은 Bidi 특유의 다섯 가지 함정을 한 층씩 뜯는다.

6-1) 독립 타이밍 — 요청과 응답은 짝이 아니다

Client-streaming은 "요청을 다 보낸 뒤 서버가 응답 한 건을 돌려준다"는 순서 계약이 있었다. Bidi는 그게 없다. 서버는 첫 요청이 도착하기도 전에 응답을 먼저 보낼 수 있고(예: 초기 핸드셰이크), 클라가 요청을 다 보내고 half-close한 뒤에도 서버 응답은 계속 돌아올 수 있다. 이 독립성이 Bidi의 본질이다.

// .proto: rpc Chat(stream ChatMessage) returns (stream ChatMessage);

StreamObserver<ChatMessage> responseObserver = new StreamObserver<>() {
    @Override public void onNext(ChatMessage msg) {
        ui.display(msg);                        // 워커 스레드에서 콜백
    }
    @Override public void onError(Throwable t) { ui.markError(t); }
    @Override public void onCompleted() { ui.markChatEnded(); }
};

StreamObserver<ChatMessage> requestObserver = async.chat(responseObserver);

// 사용자 입력이 생길 때마다 호출
requestObserver.onNext(ChatMessage.newBuilder().setText("hi").build());

중요한 건 requestObserver.onNext(msg)를 호출하는 스레드와 responseObserver.onNext(msg)가 호출되는 스레드가 완전히 다르다는 점이다. 요청 쪽은 애플리케이션 스레드(UI 이벤트 스레드 등)이고, 응답 쪽은 gRPC 워커 스레드다. 둘 사이에 공유되는 상태(예: UI 버퍼, 메시지 카운터, 세션 플래그)는 애플리케이션이 직접 동기화해야 한다. gRPC는 이걸 대신 해주지 않는다. 이 지점에서 흔히 터지는 버그가 "테스트에서는 재현이 안 되고 운영에서만 가끔 터지는 race condition"이다.

6-2) half-close는 양방향 독립적이다

HTTP/2 stream은 양방향으로 독립적인 half-close를 허용한다. 클라이언트가 requestObserver.onCompleted()를 부르면 클라→서버 방향만 닫히고, 서버→클라 방향은 그대로 살아 있다. 서버가 자기 쪽에서 responseObserver.onCompleted()를 부를 때 비로소 stream이 완전히 닫힌다. Unary나 Server-streaming에 익숙한 사람이 Bidi를 처음 만지면 여기서 두 가지 흔한 실수를 낸다.

첫째, 클라가 onCompleted()를 부르자마자 Channel을 닫는다. 아직 서버가 응답을 내보내는 중인데 stream이 RST로 끊기고, 이미 도착한 메시지도 애플리케이션까지 전달되지 못한다. 정석은 responseObserver.onCompleted() 또는 onError()가 호출될 때까지 CountDownLatch 같은 걸로 기다리는 것이다. Channel 종료는 그 뒤에 해야 한다. 둘째, 서버가 응답을 다 보냈는데 onCompleted()를 안 부른다. 이건 Server-streaming에서 본 것과 같은 함정인데, Bidi에서는 더 흔하다 — 서버 핸들러가 무한 루프 안에서 "더 보낼 거 없으면 그냥 return하면 되겠지"라고 짜는 경우가 많기 때문이다. 그냥 return하면 stream이 닫히지 않고, 클라는 onCompleted 콜백을 영원히 못 받는다. 서버 핸들러는 종료 시점에 반드시 responseObserver.onCompleted()를 명시적으로 호출해야 한다.

6-3) `isReady` / `setOnReadyHandler` — outbound flow control

Bidi에서 가장 치명적인 함정이 이 지점이다. HTTP/2는 WINDOW_UPDATE 프레임을 통해 수신측이 받을 수 있는 용량을 송신측에 알리고, 송신측은 그 창(window) 안에서만 DATA 프레임을 보내도록 제한된다. 이게 HTTP/2의 flow control이다. 문제는 gRPC의 기본 StreamObserver API가 이 HTTP/2 flow control을 자동으로 존중하지 않는다는 것이다. 정확히 말하면, onNext(msg)를 호출해도 창이 가득 찬 경우 예외를 던지거나 블록하는 게 아니라, 메시지를 JVM 힙의 송신 버퍼에 그냥 쌓는다. 수신측이 느리거나 네트워크가 느리면 이 버퍼가 무제한으로 커지고, 결국 OOM으로 간다.

이 함정을 피하는 정석 패턴은 isReady() 체크와 setOnReadyHandler() 콜백의 조합이다. ClientCallStreamObserver로 캐스팅하면 이 두 API에 접근할 수 있다.

// 선호: manualFlowControl — isReady + setOnReadyHandler로 backpressure
ClientCallStreamObserver<ChatMessage> requestObserver =
    (ClientCallStreamObserver<ChatMessage>) async.chat(responseObserver);

Iterator<ChatMessage> source = messageSource.iterator();

requestObserver.setOnReadyHandler(() -> {
    // 창에 여유가 생기면 gRPC가 이 콜백을 부른다
    while (requestObserver.isReady() && source.hasNext()) {
        requestObserver.onNext(source.next());
    }
    if (!source.hasNext()) {
        requestObserver.onCompleted();
    }
});

setOnReadyHandler는 "송신 버퍼에 여유가 생겼을 때 불러주겠다"는 콜백이다. 그 안에서 isReady()가 true인 동안만 onNext를 밀어넣고, false가 되면 즉시 빠져나온다. 다음에 여유가 생기면 gRPC가 다시 콜백해준다. 이게 애플리케이션 레벨 backpressure다. 이 패턴을 쓰지 않고 그냥 while (source.hasNext()) requestObserver.onNext(...) 루프로 짜면, 수신측이 느린 순간 힙이 폭발한다. 로컬 테스트에서는 문제가 안 보이고 (수신측이 같은 JVM 안에 있으니 빠르다), 운영에서 원격 수신측이 느려지는 순간 터진다.

6-4) manualFlowControl deadlock

양쪽이 모두 manualFlowControl을 켠 상태에서, 양쪽이 상대가 먼저 데이터를 보내야 내 window를 열어줄 수 있는 패턴으로 짜면 교착 상태가 발생한다. 구체적으로 이런 상황이다 — 서버 핸들러가 "클라 요청을 onNext로 받아야 응답 window를 연다"고 구현했고, 클라 쪽도 "서버 응답을 onNext로 받아야 다음 요청을 보낸다"고 구현했다. 첫 메시지 이후 양쪽 모두 isReady=false 상태로 멈추고, 서로 상대방이 먼저 window를 열어주기를 기다린다. 이 시점에 네트워크에서는 WINDOW_UPDATE가 전혀 흐르지 않고, 둘 다 조용히 멈춘 채로 Deadline이 만료될 때까지 기다린다.

이걸 피하는 원칙은 한 줄로 요약된다. 한 쪽은 반드시 무조건 밀어내는 쪽(initiator)이어야 한다. 보통 클라이언트가 그 역할을 맡고, 초기 요청들을 현재 window가 허용하는 만큼 일단 선제적으로 밀어넣는다. 서버는 그에 응답하면서 자연스럽게 자기 쪽 window를 열어준다. 양쪽이 동시에 "상대가 먼저"라고 기다리는 구조를 만들면 안 된다. 이걸 코드 리뷰 체크포인트로 고정해두지 않으면, Bidi 핸들러가 생길 때마다 재발한다.

6-5) `isCancelled` polling — 서버 쪽 취소 감지

서버 쪽에서 Bidi 핸들러가 무거운 응답을 만들고 있는 동안, 클라가 Deadline을 초과하거나 cancel()을 호출하면 서버는 계속 작업을 붙잡고 있을 필요가 없다. 이때 서버 핸들러가 조기 종료하려면 ServerCallStreamObserver.isCancelled()를 주기적으로 폴링해야 한다. gRPC는 cancel이 왔다는 사실을 예외로 던져주지 않고, 다음 onNext 호출이 실패할 때 비로소 StatusRuntimeException(CANCELLED)이 올라온다. 그 "다음 onNext"가 몇 초 뒤의 무거운 DB 쿼리 뒤라면, 그 쿼리는 낭비된다.

// 서버 쪽 Bidi 핸들러 — isCancelled 폴링
@Override
public StreamObserver<ChatMessage> chat(StreamObserver<ChatMessage> responseObserver) {
    ServerCallStreamObserver<ChatMessage> server =
        (ServerCallStreamObserver<ChatMessage>) responseObserver;

    return new StreamObserver<ChatMessage>() {
        @Override public void onNext(ChatMessage msg) {
            if (server.isCancelled()) {
                // 클라가 끊었거나 Deadline 초과 — 조기 종료
                return;
            }
            ChatMessage reply = process(msg);   // 여기서 DB 호출 등 무거운 작업
            if (server.isReady()) {
                server.onNext(reply);
            }
        }
        @Override public void onError(Throwable t) { cleanup(); }
        @Override public void onCompleted() {
            server.onCompleted();
        }
    };
}

isCancelled() 체크는 onNext 초입뿐 아니라 무거운 루프 안 반복마다 한 번씩 넣어두는 게 안전하다. 예를 들어 DB에서 페이지 단위로 결과를 읽으며 server.onNext(row)를 부르는 루프가 있다면, 각 페이지 직후에 isCancelled()를 확인해서 조기 빠져나온다. 그리고 cancel 시점에 cleanup 로직을 태우고 싶으면, server.setOnCancelHandler(() -> cleanup())로 콜백을 등록할 수 있다. 이 콜백은 cancel이 감지되는 즉시 gRPC가 한 번 호출한다.

7) 적용 경계 — grpc-web과 HTTP/2 프록시

네 모드를 전부 알고 나면 그다음 질문은 "어디까지 쓸 수 있는가"다. 여기서 가장 자주 걸리는 경계가 브라우저이고, 그다음으로 걸리는 게 중간 프록시의 HTTP/2 스트리밍 처리다.

7-1) grpc-web은 Unary와 Server-streaming만

브라우저에서 gRPC를 직접 호출할 수 없다는 건 1편에서 이미 다뤘다. 브라우저 fetch API가 HTTP/2 trailer를 노출하지 않기 때문에 grpc-status를 읽을 방법이 없고, 그래서 grpc-web + 프록시(Envoy, nginx grpc_web 모듈) 조합을 끼워 넣어야 한다. 한 층 더 들어가면 grpc-web이 지원하는 모드는 Unary와 Server-streaming 둘뿐이다.

모드	gRPC 백엔드	grpc-web 브라우저
Unary	O	O
Server-streaming	O	O
Client-streaming	O	X
Bidirectional	O	X

이유는 브라우저 fetch API가 request body의 streaming write를 안정적으로 지원하지 않는다는 점이다. 요청 바디를 만들기 시작한 뒤에 JS에서 추가로 바이트를 밀어넣는 표준 방법은 최근 Chrome의 ReadableStream 기반 fetch에서 비로소 정착됐지만, 크로스 브라우저 호환성이 2026년 기준으로도 완전하지 않다. WebSocket으로 우회하는 grpc-web-websocket 같은 스펙이 있지만 표준 경로가 아니고, 실전에서는 관리 비용만 더 크다. 실무 결론은 한 줄이다 — 브라우저가 통신 대상이면 Client-streaming과 Bidi를 .proto 설계에서 아예 배제한다. 나중에 한 메서드라도 Bidi로 바꾸면 grpc-web 호출부 전체가 영향을 받고, 설계를 뒤집는 비용이 훨씬 크다.

7-2) L4 vs L7 프록시의 스트리밍 pass-through

스트리밍을 쓰는 순간 중간 프록시의 행동이 중요해진다. L4 TCP 패스스루(AWS NLB, HAProxy tcp 모드)는 HTTP/2 프레임을 해석하지 않고 바이트를 그대로 넘기므로 스트리밍이 그대로 흐른다. 문제는 L7 프록시 중 일부가 응답을 버퍼링한다는 점이다. nginx는 기본값 proxy_buffering on이 HTTP/2 백엔드에도 일부 경우 영향을 주어 Server-streaming 응답을 모았다가 한꺼번에 넘기는 현상이 관찰된다. Envoy는 HTTP/2 aware라서 기본적으로 pass-through에 가깝지만, per_request_buffer_limit_bytes 같은 옵션이 큰 값으로 설정되어 있으면 비슷한 증상이 날 수 있다. AWS ALB는 HTTP/2를 프런트엔드에서 받지만 백엔드로는 HTTP/1.1로 다운그레이드하는 기본 구성이 있어서, 이 구성에서는 스트리밍 자체가 동작하지 않는다.

실제로 Bidi나 Server-streaming을 쓰는 서비스에서는 중간의 모든 프록시 홉이 HTTP/2 스트리밍을 pass-through한다는 걸 e2e 테스트로 확인해두는 게 유일하게 안전한 방법이다. 로컬 개발에서는 프록시가 없으니 잘 동작하고, 운영에서만 "왜 실시간 푸시가 1초쯤 밀리지"가 관찰되는 상황이 여기서 나온다. 중간 홉 하나라도 버퍼링을 끼워넣으면 실시간성은 망가지고, 디버깅은 tcpdump로 프레임을 직접 뜨기 전까지 원인이 안 잡힌다.

8) 운영 checklist 종합

이 글과 시리즈 1·2편의 함정을 합치면, 스트리밍이 섞인 gRPC 서비스를 운영에 올릴 때 점검해야 하는 항목이 자연스럽게 추려진다. BANDER처럼 전 서비스 Unary인 조직에 스트리밍 RPC가 처음 추가될 때는 특히 이 체크리스트를 한 번 훑고 가는 게 좋다.

8-1) stub 선택과 호출 스타일 통일

메서드 목록 중 Client-streaming이나 Bidi가 하나라도 있으면, 해당 서비스의 클라이언트는 Async Stub으로 통일한다. BlockingStub과 섞어 쓰면 호출 스타일이 이원화되고, try/catch와 onError 콜백이 코드베이스에 공존하면서 에러 처리 흐름이 갈라진다. Unary 전용 서비스는 BlockingStub으로 단순화하는 게 좋고, BANDER의 현재 구성이 정확히 이 경우다. GrpcChannelFactory가 Interceptor 체인 없이 단순한 이유도 여기에 있다 — Unary만 있으니 flow control과 backpressure를 신경 쓸 필요가 없기 때문이다.

8-2) Deadline 설계는 모드별로 분리

Unary의 Deadline은 "응답 한 건을 받는 데 걸리는 시간"이고, BANDER의 기본값 5초가 여기에 해당한다. Server-streaming의 Deadline은 "스트림 전체 생애주기" 기준이고, 구독 API라면 세션 예상 길이(수 분~수십 분)로 잡는다. Client-streaming은 "업로드 예상 시간 + 여유 버퍼"가 기준이다. Bidi는 호출 자체의 예상 세션 길이인데, 채팅처럼 무기한 세션은 Deadline을 아예 걸지 않고 keepalive로 살리는 편이 맞다. GrpcClientProperties의 기본 Deadline 하나로 모든 모드를 커버하려 하면, Unary 외의 모드는 정상 동작 중에 끊긴다.

8-3) StreamObserver 계약을 코드 리뷰 체크포인트로 고정

onNext* (onError | onCompleted) 규약을 팀 코드 리뷰 가이드에 박아두는 게 가장 안전하다. onCompleted() 누락을 방지하려면 try/finally로 무조건 호출하는 게 아니라, 정상 경로에서만 onCompleted, 예외 경로에서는 onError를 분기해야 한다. 예외를 raw Throwable이 아닌 Status.X.withDescription(...).asException()으로 래핑하는 것도 리뷰 체크포인트로 고정한다. 이 둘만 지켜도 half-open stream 누수와 UNKNOWN 로그 홍수는 거의 사라진다.

8-4) Bidi·Client-streaming의 flow control

outbound가 고처리량인 Bidi나 Client-streaming은 반드시 isReady() + setOnReadyHandler() 패턴으로 짠다. while (source.hasNext()) onNext(...) 루프는 OOM 예약이다. 서버 쪽 Bidi 핸들러에 무거운 처리 루프가 있으면 isCancelled() 폴링과 setOnCancelHandler() 콜백을 같이 건다. manualFlowControl을 양쪽에서 켠 경우, 한 쪽은 반드시 "무조건 밀어내는 initiator"여야 한다는 원칙도 같이 지켜야 deadlock이 안 난다.

8-5) 프록시와 브라우저 경계를 설계 단계에서 확인

브라우저가 통신 대상이면 Client-streaming·Bidi는 설계 단계에서 제거한다. grpc-web이 지원하지 않기 때문이고, 나중에 바꾸는 비용이 크기 때문이다. 중간 프록시가 있으면 HTTP/2 스트리밍 pass-through 여부를 e2e로 확인한다. nginx는 proxy_buffering을 끄거나 Envoy로 바꾼다. AWS ALB 뒤에 gRPC 백엔드를 두려면 백엔드 프로토콜도 HTTP/2로 설정돼 있는지 확인한다 — 기본값은 HTTP/1.1 다운그레이드인 경우가 많다.

8-6) 트레이싱과 `grpc-status` 로깅

스트리밍 에러는 단일 응답 에러보다 원인을 특정하기 어렵다. "50번째 메시지에서 터진 INTERNAL"과 "첫 메시지에서 터진 INTERNAL"은 디버깅 경로가 다른데, 단순 grpc-status 로깅만으로는 구분이 안 된다. 스트리밍 핸들러의 로깅은 현재까지 처리한 메시지 인덱스와 함께 grpc-status를 남기도록 해야 한다. 분산 트레이싱도 마찬가지다 — OpenTelemetry gRPC instrumentation은 기본적으로 stream 단위로 span 하나를 만드는데, 이게 메시지 수준 지연을 드러내지 못하므로, 필요하면 커스텀 span을 메시지 단위로 추가 생성해야 한다.

9) 실무에서 이렇게 읽고 쓴다

.proto를 처음 받으면 stream 키워드를 먼저 세어본다. 한 개도 없으면 그 서비스는 Unary 전용이고 BlockingStub으로 충분하다 (BANDER의 media_service.proto·studio_service.proto가 이 경우다). 하나라도 있으면 클라이언트는 Async Stub으로 통일한다.
스트리밍이 진짜 필요한지 repeated로 먼저 확인한다. "결과가 여러 개"는 Server-streaming의 근거가 아니다. 실시간성이 없고 결과 크기가 경계를 가진다면 repeated 필드 + pagination이 정답이고, 디버깅이 훨씬 쉽다.
스트리밍 코드의 첫 번째 리뷰 포인트는 onCompleted()·onError() 누락이다. StreamObserver 계약 onNext* (onError | onCompleted)을 머리에 박아두고, try/catch로 정상·예외 경로를 분기한다. try/finally에 onCompleted()를 넣으면 예외 상황에서도 정상 종료가 전송되어 잘못된 상태가 서버에 전달된다.
Bidi는 isReady() 없이 쓰지 않는다. 저처리량이면 그냥 돌아가지만, 고처리량이면 manual flow control이 필수다. 이걸 생략한 Bidi 코드는 로컬 테스트를 통과하고 운영에서 OOM으로 터진다.
Deadline 단위가 모드마다 다르다는 걸 잊지 않는다. BANDER의 5초 기본값은 "Unary 전용이니까" 성립하는 값이다. 스트리밍 RPC를 추가하는 순간 GrpcClientProperties를 모드별로 분리하거나 호출부에서 명시적으로 withDeadlineAfter를 다시 지정해야 한다.
grpc-web 뒤에 브라우저 클라이언트가 있으면 Client-streaming·Bidi를 .proto에서 아예 배제한다. "나중에 되겠지"로 넘겼다가 설계를 뒤집는 비용이 훨씬 크다.

10) 마치며 — 한 줄 정리

gRPC의 네 모드는 HTTP/2 stream 하나 위의 "요청 수 × 응답 수" 2×2 매트릭스이지, 네 개의 프로토콜이 아니다. 그래서 wire 포맷은 동일하고, 달라지는 건 .proto의 stream 키워드 위치와 — 그게 강제하는 stub 선택·StreamObserver 라이프사이클·flow control 책임이다. 스트리밍이 꼭 필요한 순간은 생각보다 좁고, BANDER의 전 서비스 Unary 구성처럼 Unary + repeated 조합이 현실적으로 가장 안전한 출발점이다.

태그: grpc, streaming, http2, bidirectional, stream-observer, flow-control, backpressure, protobuf, bander, deadline

PostgreSQL 아키텍처 해부 — Postmaster·백엔드·공유 메모리·WAL writer

dding-shark — Wed, 15 Apr 2026 08:20:49 +0900

PostgreSQL 아키텍처 해부 — Postmaster·백엔드·공유 메모리·WAL writer

들어가며

튜닝 가이드를 따라 shared_buffers를 올렸는데 buffers_backend가 줄지 않는다면, 건드린 건 증상이지 구조가 아니다. PostgreSQL의 파라미터는 전부 어떤 프로세스·어떤 공유 메모리 영역·어떤 백그라운드 루프에 붙는지 정해져 있고, 그 지도가 머릿속에 없으면 값만 바꿔가며 헤매게 된다. 반대로 지도가 잡혀 있으면 대부분의 파라미터는 "아, 이 루프의 주기를 줄이라는 뜻이구나"로 금방 해석된다.

이 글은 PostgreSQL 16/17 기준으로 프로세스 토폴로지 → 연결 시퀀스 → 공유 메모리 → 쓰기 경로 3인 1조 → autovacuum → 확장 포인트 순서로, 그 지도를 한 번 그려 둔다. 0편에서 말한 "학술 전통의 프로세스 per connection" 모델이 실제 바이너리 레이어에서 어떻게 구현되었는지 확인하는 편이다. 이후 편에서 WAL 포맷·MVCC·락 구조를 파고들 때 이 지도가 계속 기준이 된다.

프로세스 격리 = 안정성이라는 도식은 절반만 맞다 — work_mem은 연결당이 아니라 플랜 노드당 곱해진다
shared_buffers만 올리고 effective_cache_size를 방치하면 플래너가 옛날 세계관으로 돈다 — 전자는 할당, 후자는 힌트다
full_page_writes를 integrity 보험으로만 읽지 말자 — 체크포인트 직후 WAL 폭증이 복제 지연으로 돌아온다
autovacuum이 자동이라고 방치하면 안 된다 — anti-wraparound VACUUM은 cost_delay를 무시하고 IO를 통째로 가져간다
max_worker_processes는 하나의 슬롯 풀이다 — 병렬 쿼리·확장·논리 복제가 같은 우물에서 물을 뜬다

이 글은 왜 → 구조 → 동작 → 주의 → 실무 순으로 정리한다.

1) 프로세스 토폴로지: postmaster와 상주 6종
2) 클라이언트 연결 시퀀스: fork부터 ReadyForQuery까지
3) 인증·파라미터 협상의 함정
4) 공유 메모리 레이아웃: 다섯 영역의 지도
5) WAL writer·bgwriter·checkpointer — 쓰기 경로 3인 1조
6) autovacuum launcher와 worker
- 6-5) wraparound와 anti-wraparound
7) 확장의 자리: background worker와 shared_preload_libraries
8) 실무에서 이렇게 읽고 쓴다
9) 한 줄 정리

1) 프로세스 토폴로지: postmaster와 상주 6종

PostgreSQL을 기동하면 가장 먼저 올라오는 단일 프로세스가 postmaster다. 이 녀석의 임무는 두 가지다. 포트를 열어 클라이언트 연결을 accept()하고, 연결이 들어오면 fork(2)로 백엔드를 찍어낸다. 그리고 기동 시점에 몇 개의 상주 백그라운드 프로세스를 미리 띄운다. 연결 수와 무관하게 항상 떠 있는 녀석들이다. 0편에서 "프로세스 per connection"이라고 표현한 그 모델의 실제 얼굴이 여기 있다.

공식 문서는 이 구조를 한 문장으로 요약한다.

"PostgreSQL uses a 'process per user' client/server model."

— PostgreSQL 17 §50.2 Architectural Fundamentals

PG 16/17 기준으로 postmaster가 직접 띄우는 상주 프로세스는 여섯 종이다.

프로세스	역할	등장/변화
`postmaster`	리스너, fork 모체, 자식 리핑	supervisor
`checkpointer`	체크포인트 실행, dirty 버퍼 디스크 동기화	9.2에서 bgwriter에서 분리
`bgwriter`	LRU 꼬리의 dirty 버퍼를 선제적으로 flush	8.0~
`walwriter`	WAL buffer → WAL 파일 쓰기 전담	8.3~
`autovacuum launcher`	naptime마다 DB 스캔, 필요 DB에 worker 스폰	8.1~
`logical replication launcher`	논리 복제 구독자 worker 관리	10~

여기에 선택적으로 archiver(WAL archive 모드), wal_receiver/wal_sender(스트리밍 복제), stats collector가 붙는다. 다만 stats collector는 PG 15에서 제거되었다. 15부터는 누적 통계를 별도 프로세스가 UDP로 수집하는 대신 공유 메모리에 직접 누적한다. 15 이전 블로그를 읽을 때는 이 차이를 감안해야 한다.

여기서 틀리기 쉽다. "프로세스 격리니까 안정적이다" 는 서술은 절반만 맞다. 한 백엔드가 SIGSEGV로 죽으면 postmaster는 모든 백엔드를 강제 종료하고 crash recovery로 들어간다. 공유 메모리가 오염되었을 가능성을 배제할 수 없기 때문이다. 즉 격리되는 건 "정상 동작하는 클라이언트 세션 사이의 메모리"지, "장애 폭발 반경"이 아니다.

1-3) 격리의 진짜 의미 — work_mem은 플랜 노드당이다

한 백엔드가 work_mem 기반 플랜 노드를 여러 개 가진 쿼리를 돌리면 그 백엔드 하나가 work_mem × 노드 수만큼 RSS를 찢어간다. work_mem은 연결당이 아니라 실행 계획 노드당 할당된다는 사실이 여기서 발목을 잡는다. 문서적인 설명보다 EXPLAIN 한 번이 빠르다.

EXPLAIN (ANALYZE, BUFFERS)
SELECT *
FROM orders o
JOIN customers c ON o.customer_id = c.id
ORDER BY o.created_at DESC
LIMIT 100;
-- Sort 노드 + Hash Join 노드가 각각 work_mem 만큼 할당 가능
-- 한 쿼리가 work_mem × (Sort + Hash + Merge) 소비 가능
-- 동시 연결 200 × 3 노드 × 4MB = 2.4GB 이론 상한

결론은 간단하다. fork 격리는 "crash 격리"일 뿐, 메모리 예산 격리가 아니다. 격리는 메모리 소비의 방어막이 아니라 메모리 소비의 청구서를 프로세스별로 분리해 주는 것뿐이다. 이 6종이 떠 있는 상태에서 클라이언트가 새 연결을 던지면 어떻게 되는지를 다음 절에서 따라간다.

2) 클라이언트 연결 시퀀스: fork부터 ReadyForQuery까지

클라이언트가 psql이든 JDBC든 간에, 연결 하나가 만들어지는 동안 내부에서 일어나는 일은 같다. TCP를 열고, postmaster가 fork()로 백엔드를 낳고, 그 백엔드가 자기 자신을 초기화한 뒤 인증·파라미터 협상을 거쳐 ReadyForQuery를 돌려준다. 여기서 핵심은 fork 비용이 인증보다 앞선다는 점이다. 인증에 실패해도 자식 프로세스는 이미 만들어진 상태다. 커넥션 풀러가 왜 필수 인프라가 되는지 한 줄로 이해되는 지점이다.

2-1) SSLRequest의 1바이트 규칙

PostgreSQL 프론트엔드 프로토콜은 TLS 협상을 시작할 때 정확히 1바이트를 읽고 나서 핸드셰이크를 시작해야 한다. 공식 문서가 이렇게 규정한다.

"The frontend should read exactly one byte before initiating the SSL handshake to prevent buffer-stuffing attacks."

— PostgreSQL 17 §53.2 Message Flow

버퍼 스터핑 공격(CVE-2021-23222)을 막기 위한 규칙이다. 서버가 S 한 바이트를 보내기 전에 추가 바이트가 같이 딸려 오면, 이후 TLS 핸드셰이크가 평문 데이터를 오해할 수 있다. 그래서 JDBC·libpq 등 드라이버들이 전부 1바이트만 먼저 소비하도록 구현되어 있다. 직접 드라이버를 짤 일이 아니어도, 평문/암호문 경계가 이 한 바이트에 걸려 있다는 사실은 보안 리뷰 때 한 번 짚어 둘 가치가 있다.

2-2) BackendKeyData — 취소의 근거

AuthenticationOk 직후 서버가 보내는 BackendKeyData는 두 개의 정수, 즉 PID와 secret key를 담는다. 이 둘이 있어야 나중에 쿼리 취소(CancelRequest) 를 보낼 수 있다. CancelRequest는 기존 연결을 재사용하지 않고 새 TCP 연결을 열어 "이 PID에 시그널을 보내라"고 postmaster에 요청하는 방식이다. 즉 cancel은 백엔드와 직접 말하지 않고 postmaster를 경유한다. JDBC의 Statement.cancel()이 타임아웃 후에도 살아 있는 이유가 여기 있다.

2-3) ParameterStatus 폭포

인증이 끝나면 백엔드는 server_version, client_encoding, DateStyle, TimeZone, integer_datetimes, standard_conforming_strings 같은 ParameterStatus 메시지를 연달아 쏟아낸다. 드라이버는 이걸 로컬 상태에 저장했다가 나중에 SQL 파싱·결과 해석에 쓴다. 여기서 특정 파라미터가 바뀔 때마다(SET TIMEZONE) 백엔드는 ParameterStatus를 또 보낸다. 즉 GUC 변경은 단순한 세션 상태가 아니라 프로토콜 이벤트다. 이 사실은 커넥션 풀러가 세션 상태를 초기화할 때 왜 그렇게 예민해지는지 설명해 준다.

2-4) fork 비용과 PgBouncer — 왜 풀러가 기본 인프라인가

"fork가 느리니까 풀러를 쓴다"는 설명은 정확하지 않다. Linux x86-64 기준 fork() 시스템콜 자체는 일반적으로 sub-ms 수준이다. 문제는 그 다음이다. PostgreSQL 백엔드는 fork 직후 공유 메모리 세그먼트에 attach하고, 시스템 카탈로그 캐시를 초기화하고, pg_hba.conf를 파싱하고, 인증 왕복을 완료하고, ParameterStatus를 쏟아낸 뒤에야 비로소 ReadyForQuery를 돌려준다. 이 전 과정을 합치면 실측 수 ms에서 수십 ms 영역으로 올라간다.

OLTP처럼 short-lived 연결이 초당 수천 번 만들어지는 워크로드에서는 이 비용이 그대로 쓰로틀이 된다. PgBouncer의 transaction pooling이 PostgreSQL 스택의 사실상 기본 인프라가 된 이유도 여기다. 정확히는 "fork 자체가 느려서"가 아니라 "backend 초기화까지가 비싸서" 다. 풀러는 fork를 한 번만 하고 이미 초기화된 백엔드를 재사용한다.

3) 인증·파라미터 협상의 함정

연결이 실패하면 에러 메시지만 보고 pg_hba를 의심하는 경우가 많은데, 실제 원인은 네 군데로 나뉜다. 한 번 표로 정리해 두면 장애 대응이 빨라진다.

에러 메시지	원인	조치
`FATAL: sorry, too many clients already`	`max_connections` 초과	풀러 도입 or 값 상향(재시작 필요)
`FATAL: too many connections for role "x"`	역할별 `CONNECTION LIMIT` 초과	`ALTER ROLE x CONNECTION LIMIT`
`FATAL: no pg_hba.conf entry for host ...`	pg_hba.conf 룰이 거부	룰 추가 후 `SELECT pg_reload_conf()`
`FATAL: password authentication failed for user "x"`	비밀번호/메서드 불일치	SCRAM-SHA-256 설정 확인

max_connections와 역할 CONNECTION LIMIT는 별개의 카운터다. 전자에 여유가 있어도 후자에서 막힐 수 있고, 반대도 마찬가지다. 그리고 max_connections는 재시작이 필요한 파라미터다. 공유 메모리의 proc array 크기를 고정된 값으로 할당하기 때문이다. reload로 바뀐다고 착각하고 운영 중에 바꾸려다가 당황하는 패턴이 제법 흔하다.

여기서 한 가지 더 — PG 14부터 기본 인증 메서드가 scram-sha-256이다. 이전엔 md5였다. 오래된 드라이버(예: JDBC 9.x 이하)는 이걸 이해하지 못해 "password authentication failed"로 떨어진다. 서버가 MD5로 폴백하게 하는 대신 드라이버를 올리는 게 정답이다.

인증을 통과한 백엔드들이 한 덩어리의 메모리에서 어떻게 만나는지가 다음 주제다.

4) 공유 메모리 레이아웃: 다섯 영역의 지도

fork()로 만들어진 백엔드들이 어떻게 서로 협력할까. 답은 공유 메모리 세그먼트 한 덩어리다. postmaster가 기동 시 shmget/mmap으로 커다란 세그먼트 하나를 잡고, 그 안에 논리적으로 여러 영역을 레이아웃한다. 자식 백엔드는 fork()로 이 포인터를 물려받는다. 운영자가 외울 가치가 있는 건 다섯 영역이다.

영역	기본값/공식	관측 뷰
shared_buffers	128MB (권장 RAM 25%) / 페이지 8KB	`pg_buffercache` 확장
wal_buffers	`-1` → `shared_buffers/32`, 64KB~16MB	`pg_stat_wal`
proc array	`max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes`	`pg_stat_activity`
lock table	`max_locks_per_transaction × (max_connections + max_prepared_transactions)`	`pg_locks`
CLOG (`pg_xact`)	트랜잭션당 2비트, SLRU	`pg_stat_slru`, PG 17 `transaction_buffers`

4-1) shared_buffers — 할당이고, 버퍼 풀이다

shared_buffers는 PostgreSQL이 직접 할당해서 들고 있는 버퍼 풀이다. 8KB 페이지 단위로 관리되며, 읽기·쓰기가 일차적으로 여기에서 일어난다. 기본값 128MB는 사실상 "돌기는 한다" 수준의 최소치이고, 실무에서는 RAM의 25% 정도를 권장값으로 시작한다. 다만 25%는 상한이 아니라 출발점이다. 워크로드와 OS page cache의 관계에 따라 이 값을 조정하게 된다.

여기서 틀리기 쉽다. shared_buffers와 effective_cache_size를 같은 레이어로 보면 안 된다. 전자는 PG가 직접 잡는 메모리이고, 후자는 플래너에게 "이 정도 캐시 히트율을 가정해라"고 귀띔하는 힌트다. PG는 effective_cache_size에 1바이트도 할당하지 않는다. 이 값이 작으면 플래너는 디스크 IO를 비싸게 잡아 sequential scan 쪽으로 기울고, 이 값이 크면 index scan 쪽으로 기운다. 보통 RAM의 50~75% 정도로 두는데, 정답이 있는 게 아니라 플래너 편향의 조정 다이얼이라는 뜻이다.

한 가지 더 주의할 게 double buffering이다. shared_buffers가 잡은 페이지는 대부분 OS page cache에도 그대로 존재한다. 즉 같은 8KB가 커널 공간과 PG 공간에 이중으로 캐시된다. 이게 shared_buffers를 RAM의 50% 이상으로 밀어붙이지 않는 경험칙의 근거다. OS page cache가 사라지면 PG의 read-ahead와 effective_io_concurrency가 기대하는 패턴도 함께 깨진다. 구체적으로 effective_io_concurrency는 OS 레벨 readahead/posix_fadvise를 몇 개까지 동시에 띄울지 플래너에게 알리는 값인데, 이 값이 의미를 가지려면 그 readahead가 실제로 살아 있어야 한다.

어느 릴레이션이 shared_buffers 안에 얼마나 들어 있는지는 pg_buffercache 확장으로 직접 본다.

CREATE EXTENSION IF NOT EXISTS pg_buffercache;
SELECT c.relname,
       count(*) AS buffers,
       pg_size_pretty(count(*) * 8192) AS bytes
FROM pg_buffercache b
JOIN pg_class c ON b.relfilenode = pg_relation_filenode(c.oid)
GROUP BY c.relname
ORDER BY 2 DESC
LIMIT 10;

"핫 테이블이 정말 버퍼 풀에 상주하는가"에 대한 직접 관측 창이다. 예상과 다른 릴레이션이 상위에 올라와 있다면 인덱스 설계나 쿼리 패턴을 다시 봐야 한다.

4-2) wal_buffers — shared_buffers의 1/32 규칙

WAL을 디스크에 쓰기 전에 잠시 쌓아 두는 작은 영역이다. 기본값이 특이하게 -1인데, 문서가 정확히 적어 둔다.

"The default setting of -1 selects a size equal to 1/32nd (about 3%) of shared_buffers, but not less than 64kB nor more than the size of one WAL segment, typically 16MB."

— PostgreSQL 17 §19.5 wal_buffers

즉 shared_buffers를 건드리면 wal_buffers도 따라 움직인다. 다만 상한이 WAL 세그먼트 하나 크기(보통 16MB)로 걸린다. 대용량 쓰기가 잦은 워크로드는 이 값을 명시적으로 16MB로 박아 두는 편이 낫다. 그래야 commit 시 XLogFlush 대기가 줄어든다.

wal_buffers가 정말 부족한지 확인하는 창은 pg_stat_wal이다.

SELECT wal_records, wal_bytes,
       wal_write_time, wal_sync_time,
       wal_buffers_full
FROM pg_stat_wal;

핵심은 wal_buffers_full이다. 이 값은 "backend가 WAL 레코드를 쓰려다가 wal_buffers가 꽉 차서 강제로 flush한 횟수"를 누적한다. 평시에는 0에 가까워야 정상이고, 꾸준히 올라간다면 wal_buffers가 부족하다는 신호다. 이럴 땐 16MB로 고정 박아 두는 것이 답이다.

4-3) proc array — 왜 재시작이 필요한가

proc array는 현재 살아 있는 백엔드의 상태를 담는 고정 크기 배열이다. 크기 공식이 중요하다 — max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes. 네 항이 왜 각각 필요한지 한 줄씩 풀면 다음과 같다.

max_connections — 일반 클라이언트 백엔드 슬롯. 앱 서버가 직접 fork되는 자리.
autovacuum_max_workers — autovacuum launcher가 스폰하는 청소 worker 슬롯. 일반 연결과 경쟁하면 안 되니 따로 잡는다.
max_wal_senders — 스트리밍 복제 송신자. replica가 붙으려면 여기에 자리가 있어야 한다.
max_worker_processes — 병렬 쿼리·확장·논리 복제 worker가 공유하는 풀. §7-2에서 자세히.

변경 시 재시작이 필요한 이유는 단순하다 — postmaster가 기동할 때 이 네 값의 합만큼 공유 메모리 세그먼트 안에 slot 배열을 calloc으로 한 번에 잡는다. 런타임에 배열 크기를 늘리는 코드 경로가 없다. reload로 끝내려다가 무시당한다.

pg_stat_activity가 보여주는 행 하나가 proc array의 슬롯 하나에 대응한다. "idle in transaction" 세션을 잡을 때 이 뷰가 첫 관측창이 된다.

4-4) lock table — MVCC가 필요로 하는 작은 유한 공간

PG의 락 테이블도 공유 메모리에 고정 크기로 잡힌다. 크기 공식은 max_locks_per_transaction × (max_connections + max_prepared_transactions). 기본값 64가 곱해진다. 한 트랜잭션이 이보다 많은 오브젝트에 락을 걸어야 하면 out of shared memory 에러가 난다. 파티션 테이블을 많이 쓰는 스키마에서 이 에러가 종종 나오는 이유 — 파티션 프루닝이 안 되어 모든 자식 테이블에 락을 거는 순간 64개를 금방 넘긴다. 이 경우 max_locks_per_transaction을 128/256으로 올린다.

재현 시나리오 하나를 구체적으로 그려 두면 이해가 빠르다. 월별 파티션 1000개짜리 events 테이블에서 WHERE event_time > now() - interval '7 days' 같은 조건이 들어간다. 상식적으로는 최근 파티션 1~2개만 스캔해야 하지만, partition key 타입이 now() 함수의 반환 타입과 맞지 않거나 immutable이 아닌 함수가 끼면 플래너가 프루닝을 포기하고 1000개 파티션 전부를 실행 계획에 넣는다. 그 순간 한 트랜잭션이 1000개의 AccessShareLock을 걸게 되고, max_locks_per_transaction=64면 즉시 out of shared memory 에러가 튄다. 이 시점에서는 max_locks_per_transaction을 먼저 키워 장애를 막고, 원인인 프루닝 실패를 EXPLAIN으로 추적하는 순서가 현실적이다.

현재 락 분포를 관측하는 가장 빠른 쿼리는 이것이다.

SELECT mode, count(*) FROM pg_locks GROUP BY mode ORDER BY 2 DESC;

AccessShareLock이 수천 개로 튀어 있다면 파티션 프루닝 실패를, RowExclusiveLock + ExclusiveLock의 블로킹 관계를 보고 싶다면 pg_blocking_pids()와 조인한 뷰를 쓴다.

4-5) CLOG — 트랜잭션당 2비트의 진실

CLOG(Commit Log, PG 10부터 디렉토리 이름이 pg_xact)는 각 트랜잭션의 상태를 2비트로 저장한다. 상태는 IN_PROGRESS, COMMITTED, ABORTED, SUB_COMMITTED 네 가지. MVCC에서 "이 튜플을 만든 XID가 커밋됐나?"를 물을 때마다 CLOG를 찾아보므로 모든 읽기에 간접 참조가 하나 더 낀다.

간단한 산수 하나 — XID는 32비트, 트랜잭션당 2비트면 디스크 위 CLOG의 이론 최대 크기는 2비트 × 2^32 = 1 GB다. 실제로 pg_xact 디렉토리가 GB 단위로 자라는 걸 본 적이 있다면 놀랄 일이 아니다. freeze와 함께 오래된 segment가 잘려 나가기에 평시에는 수십 MB 수준에 머문다.

CLOG는 디스크 위 파일이면서 동시에 공유 메모리에 SLRU(Simple LRU)로 캐시된다. 이름 그대로 "Simple" — 작은 고정 슬롯 풀에 단순 LRU를 돌리는 구조다. 일반 buffer pool처럼 clock sweep이나 ring buffer 같은 정교한 장치가 없는 대신, 코드가 짧고 경합 지점이 명확하다. 대용량 트랜잭션에서 CLOG 컨텐션이 문제가 되는 것도 이 단순함 때문이다.

PG 17에서는 SLRU 버퍼 크기들이 드디어 GUC로 노출되었다 — transaction_buffers, subtransaction_buffers, commit_timestamp_buffers 등. 그 이전까지는 코드에 상수로 박혀 있어서 튜닝이 불가능했다. transaction_buffers의 기본값은 shared_buffers / 512이고 상한 8MB로 클램프된다. 즉 shared_buffers를 크게 잡아도 CLOG 버퍼는 자동으로 끝까지 자라지 않는다. 대용량 트랜잭션을 처리하는 서버에서 CLOG 컨텐션이 의심된다면 17로 올리고 이 값을 명시적으로 키워볼 가치가 있다.

마지막으로 실측 크기 계산 한 번. max_connections=200, work_mem=4MB, shared_buffers=8GB 가정. shared_buffers 8GB + wal_buffers 16MB + proc array/lock table(수십 MB 수준) + CLOG 버퍼 8MB ≈ 공유 메모리 총량 8.1GB. 여기에 백엔드별 사유 메모리는 별도 — work_mem 4MB × 플랜 노드 3 × 연결 200 = 최악 2.4GB가 힙에 따로 붙는다. OS 관점에서 PG 한 인스턴스의 실제 RSS 상한은 shared_buffers + (work_mem × 플랜 노드 × 연결 수) 정도로 잡아야 현실에 가깝다. 이 산수가 안 맞으면 한밤중에 OOM killer가 친절하게 가르쳐 준다.

공유 메모리 다섯 영역의 지도를 잡았으니, 이제 이 버퍼 풀이 디스크와 만나는 쓰기 경로로 내려간다.

5) WAL writer·bgwriter·checkpointer — 쓰기 경로 3인 1조

PostgreSQL의 쓰기 경로를 이해하는 가장 빠른 길은 "세 명이 각자 다른 것을 쓴다" 를 외우는 것이다. walwriter는 WAL을, bgwriter는 dirty 버퍼 일부를, checkpointer는 모든 dirty 버퍼를 디스크에 내려보낸다. 셋이 같은 디스크를 두고 협력하되, 주기와 대상이 다르다.

5-1) walwriter — commit 전에 미리 내려보내는 쪽

walwriter는 비동기 커밋을 가능하게 만드는 조용한 일꾼이다. 기본값은 wal_writer_delay=200ms, wal_writer_flush_after=1MB. 즉 200ms마다 혹은 WAL 버퍼에 1MB가 쌓이면 디스크로 flush한다. synchronous_commit=on이면 각 커밋이 자기 WAL이 디스크에 닿을 때까지 기다리지만, off면 walwriter가 나중에 내려줄 때까지 기다리지 않고 반환한다. 즉 walwriter의 주기가 비동기 커밋의 데이터 손실 창을 결정한다. off 상태에서 wal_writer_delay를 2초로 키우면 최악의 경우 2초어치가 날아갈 수 있다는 뜻이다.

5-2) bgwriter — LRU 꼬리의 청소부

bgwriter는 shared_buffers에서 곧 교체될 dirty 버퍼들을 미리 디스크에 써 두는 역할이다. 백엔드가 새 페이지가 필요해서 BufferAlloc을 호출했는데 LRU 꼬리의 victim 버퍼가 dirty면, 백엔드가 직접 디스크에 쓰고 나서 교체해야 한다. 이걸 피하려고 bgwriter가 선제적으로 돌아다니며 flush해 두는 것이다.

기본값은 bgwriter_delay=200ms, bgwriter_lru_maxpages=100, bgwriter_lru_multiplier=2.0. 200ms마다 깨어나서 "최근에 백엔드가 몇 개를 요청했나"를 보고 그 2배만큼을 미리 flush하되, 한 라운드에 100페이지를 넘지는 않는다. pg_stat_bgwriter의 buffers_clean과 buffers_backend가 이 일꾼의 성적표다. buffers_backend가 꾸준히 올라간다면 bgwriter가 못 따라가고 있다는 신호다. 이때는 bgwriter_lru_maxpages를 키우거나 bgwriter_delay를 줄인다.

5-3) checkpointer — spread write와 full_page_writes

checkpointer는 주기적으로 모든 dirty 버퍼를 디스크에 내려보내고 체크포인트 기록을 WAL에 남긴다. 크래시 시 recovery가 여기서부터 재생을 시작한다. 주기의 기본값은 checkpoint_timeout=5min, checkpoint_completion_target=0.9. 즉 5분마다 시작하되, 그 쓰기를 5분의 90%(4분 30초)에 걸쳐 퍼트려서 내보낸다. spread write라고 부른다. 이게 없으면 체크포인트마다 IO가 스파이크로 튄다.

여기서 full_page_writes=on(기본)과 맞물리는 함정이 있다. 이 옵션은 체크포인트 이후 어떤 페이지가 처음 변경될 때 그 페이지 전체(8KB)를 WAL에 함께 기록하라는 뜻이다. partial write(토른 페이지) 문제로부터 recovery를 안전하게 만드는 장치다. 그런데 부작용이 있다 — 체크포인트 직후에는 거의 모든 업데이트가 full page image를 동반하므로 WAL 양이 수 배에서 수십 배로 튄다. 복제 환경에서는 이 스파이크가 그대로 replica lag으로 보인다.

여기서 틀리기 쉽다. full_page_writes를 "integrity 보험"으로만 읽지 말자. off로 끄면 복구가 위험해지지만, on인 채로 방치하면 체크포인트 튜닝이 복제 지연 대응의 첫 단추가 된다. checkpoint_timeout을 늘리면 체크포인트 빈도가 줄어 full page image 총량이 줄지만, 대신 한 번에 써야 할 양이 늘어난다. max_wal_size도 함께 움직여야 하는 이유다. 참고로 특정 구간의 WAL에서 FPI(full page image)가 차지하는 비율은 pg_waldump -z <segment>로 바로 측정할 수 있다. 이 비율이 30%를 계속 넘는다면 체크포인트 주기 튜닝의 타이밍이다.

5-4) pg_stat_bgwriter 읽는 법

bgwriter와 checkpointer가 제대로 일하고 있는지 판단하는 가장 빠른 뷰는 pg_stat_bgwriter다. 컬럼만 외워 두면 대부분의 판단이 30초 안에 끝난다.

컬럼	의미
`buffers_checkpoint`	checkpointer가 flush한 dirty buffer 누적
`buffers_clean`	bgwriter가 선제적으로 flush한 dirty buffer 누적
`buffers_backend`	backend가 할 수 없어서 직접 쓴 dirty buffer — 건강 지표의 반대
`buffers_backend_fsync`	backend가 직접 `fsync`한 횟수. 0이어야 정상
`maxwritten_clean`	bgwriter가 `lru_maxpages` 한도에 걸려 멈춘 횟수

건강 진단 공식 하나를 외워 둔다 — buffers_backend / (buffers_clean + buffers_backend). 이 비율이 10%를 꾸준히 넘으면 bgwriter 튜닝 시점이다. bgwriter_lru_maxpages를 200/400으로 올리거나 bgwriter_delay를 100ms로 줄이는 식으로 먼저 손댄다. 반대로 buffers_backend_fsync가 0이 아닌 수로 올라가면 "OS가 bgwriter의 request queue를 거부했다"는 심각한 신호다. 스토리지 쪽부터 봐야 한다.

PG 17 주의사항 — 17에서는 이 뷰의 일부 컬럼이 pg_stat_checkpointer로 분리되었다. 16 이전 대시보드 쿼리를 17로 옮길 때 buffers_checkpoint, checkpoints_timed, checkpoints_req 같은 컬럼이 새 뷰로 이사 간 걸 놓치면 무심코 0으로 읽힌다.

5-5) synchronous_commit 5단계 — 손실 창 vs 지연

앞서 walwriter 절에서 "비동기 커밋의 손실 창은 walwriter 주기"라고 했는데, 이 손실 창을 세밀하게 조정하는 다이얼이 synchronous_commit이다. 5단계가 있다.

값	primary fsync	primary 대기	standby 대기	손실 창
`off`	X	X	X	최대 `wal_writer_delay × 3` (기본 600ms)
`local`	O	O	X	0 (단, 복제 고려 없음)
`on` (기본)	O	O	remote_write까지	standby OS가 받은 시점까지
`remote_write`	O	O	standby OS write	standby가 받고 write까지
`remote_apply`	O	O	standby replay까지	0 (read-your-writes 보장)

트레이드오프가 직관적이다. off는 가장 빠르지만 primary 크래시 시 수백 ms가 날아갈 수 있고, remote_apply는 primary 커밋이 standby의 replay까지 기다리므로 네트워크 RTT + 재생 시간이 그대로 커밋 레이턴시에 올라탄다. 기본값 on이 "primary fsync + remote_write"로 잡혀 있는 건 이 둘의 중간 절충이다. 세션별로 바꿀 수 있다는 점이 중요하다 — 중요한 결제 트랜잭션만 SET LOCAL synchronous_commit = remote_apply로 올리고 나머지는 기본값으로 두는 전략이 현실적이다.

쓰기 경로의 세 일꾼을 따라왔다. 이제 이들이 만들어 놓은 오래된 튜플 버전을 청소하는 마지막 상주 프로세스로 간다.

파라미터	기본값	역할
`wal_writer_delay`	200ms	walwriter 주기
`wal_writer_flush_after`	1MB	walwriter flush 임계
`bgwriter_delay`	200ms	bgwriter 주기
`bgwriter_lru_maxpages`	100	라운드당 최대 flush 페이지
`bgwriter_lru_multiplier`	2.0	수요 예측 배수
`checkpoint_timeout`	5min	체크포인트 주기
`checkpoint_completion_target`	0.9	spread write 비율
`full_page_writes`	on	체크포인트 후 첫 변경 시 전체 페이지 WAL 기록
`max_wal_size`	1GB	체크포인트 강제 트리거 임계

6) autovacuum launcher와 worker

PostgreSQL의 MVCC는 오래된 튜플 버전을 나중에 청소하는 모델이다. 이 청소를 전담하는 게 autovacuum이다. 구조는 간단하다 — launcher 하나가 상주하며 autovacuum_naptime(기본 1분)마다 DB를 순회하고, 청소가 필요한 DB가 있으면 그쪽에 worker를 spawn한다. 동시에 뛸 수 있는 worker 수는 autovacuum_max_workers(기본 3). 이 값은 proc array 크기에 영향을 주기 때문에 재시작이 필요하다.

파라미터	기본값	의미
`autovacuum_naptime`	1min	launcher가 DB를 살피는 주기
`autovacuum_max_workers`	3	동시 worker 수 (재시작 필요)
`autovacuum_vacuum_threshold`	50	기본 변경 건수 하한
`autovacuum_vacuum_scale_factor`	0.2	비례 계수
`autovacuum_vacuum_cost_delay`	2ms	비용 기반 throttle 지연
`autovacuum_vacuum_cost_limit`	200	한 라운드에 쓸 수 있는 비용

6-1) threshold 공식과 스케일 계수

테이블이 청소 대상이 되는 조건은 단순한 공식이다 — 변경된 튜플 수 > threshold + scale_factor × reltuples. 기본값으로 풀면 50 + 0.2 × 테이블 크기. 즉 1만 행짜리 테이블은 2050행이 바뀌면 돌고, 1억 행짜리는 2천만 행이 바뀌어야 돈다. 큰 테이블일수록 autovacuum이 점점 뜸해진다는 뜻이다. 큰 테이블에는 ALTER TABLE ... SET (autovacuum_vacuum_scale_factor = 0.02) 같은 per-table 오버라이드가 거의 필수다.

6-2) cost-based throttle — 왜 VACUUM이 느린가

autovacuum worker는 cost-based throttle로 IO 사용량을 제한한다. 페이지를 shared_buffers에서 찾으면 1, 디스크에서 읽으면 10, 더럽히면 20의 비용이 쌓인다. 한 라운드의 누적 비용이 autovacuum_vacuum_cost_limit(200)을 넘으면 autovacuum_vacuum_cost_delay(2ms)만큼 잠든다. 이게 "VACUUM이 왜 그렇게 느리냐"에 대한 답이다. 느린 게 아니라 일부러 느리게 하고 있다. OLTP 쓰기를 방해하지 않으려는 설계다. 반대로 긴급하게 청소해야 할 때는 cost_delay를 0으로 놓고 수동으로 VACUUM (VERBOSE)를 돌리게 된다.

6-3) workers는 슬롯 풀이다 — cost balance의 진짜 공식

autovacuum_max_workers가 3이라고 해서 "언제나 3개가 돈다"는 건 아니다. launcher는 필요한 DB에만 worker를 붙이고, 일이 끝나면 슬롯을 반납한다. 다만 매우 큰 테이블 셋이 동시에 threshold를 넘으면 3개가 동시에 돌게 되고, 이때 총 IO는 cost_limit × 3이 아니라 — 문서가 정확히 적지만 — cost_limit을 여러 worker가 나눠 쓰도록 조정된다.

정확히는 이렇다. autovacuum_vacuum_cost_limit = -1(기본)일 때, autovacuum은 vacuum_cost_limit(기본 200)을 현재 활성 worker 수로 나누는 cost balance 동작에 들어간다. worker가 3개면 각자 약 66의 예산을 나눠 갖는다. 그래서 워커 수를 늘린다고 총 처리량이 비례해 늘지 않는다 — 예산 총액은 고정된 채 분할만 된다.

큰 DB에서 autovacuum이 늦는 이유는 주로 worker 수가 아니라 cost_delay 쓰로틀과 테이블 동결 스캔 양쪽이다. 큰 테이블 하나를 빨리 청소해야 한다면 ALTER TABLE tbl SET (autovacuum_vacuum_cost_delay = 0) 같은 per-table 오버라이드가 더 직접적이다.

6-4) 관측: pg_stat_progress_vacuum

PG 9.6부터 VACUUM의 진행 상황을 실시간으로 노출하는 뷰가 있다 — pg_stat_progress_vacuum. "왜 이 VACUUM이 한 시간째 안 끝나는가"를 추적할 때 첫 관측창이 이것이다. phase 컬럼이 일곱 단계를 돈다.

initializing — 초기화
scanning heap — 힙 페이지 스캔, dead tuple 식별
vacuuming indexes — 인덱스에서 dead tuple 참조 제거
vacuuming heap — 힙에서 dead tuple 공간 회수
cleaning up indexes — 인덱스 cleanup
truncating heap — 빈 페이지 잘라내기
final cleanup — 마무리

어느 phase에서 정체되는지가 바로 진단이다. scanning heap에서 오래 머물면 테이블 크기 + IO 쓰로틀 조합, vacuuming indexes에서 막히면 인덱스 수가 많거나 특정 인덱스가 거대한 경우, truncating heap에서 멈춘 듯 보이면 AccessExclusiveLock 획득 대기 때문일 수 있다. 이 구분이 없으면 "전부 느리다"로만 보이고 다음 액션을 못 고른다.

6-5) wraparound와 anti-wraparound

PostgreSQL의 MVCC는 32비트 XID(트랜잭션 ID)를 쓴다. 2^31 = 약 21억 개의 XID가 한 바퀴를 돌면 "이 튜플이 과거인지 미래인지" 를 판단할 수 없게 된다. 이게 유명한 wraparound 문제다. PG는 주기적으로 오래된 XID를 특수 값 FrozenXID로 교체해서 "영원히 과거"로 표시한다. 이걸 freezing이라고 부른다. 평소 autovacuum이 일반 청소와 함께 슬슬 해두지만, 미루다가 아슬아슬해지면 anti-wraparound VACUUM이 발동한다.

문서가 이 조건을 명시한다.

"Tables whose pg_class.relfrozenxid value is more than autovacuum_freeze_max_age transactions old are always vacuumed."

— PostgreSQL 17 §24.1 Routine Vacuuming

그리고 한 발 더.

"The system will launch autovacuum processes to prevent wraparound even when autovacuum is otherwise disabled."

— PostgreSQL 17 §19.10

기본값은 autovacuum_freeze_max_age=2억, vacuum_freeze_table_age=1.5억. 즉 relfrozenxid가 2억 트랜잭션 이상 뒤처진 테이블은 반드시 청소된다. 그리고 이 anti-wraparound VACUUM은 cost_delay를 무시한다. 쓰로틀이 없다. 큰 테이블이 이 상태에 걸리면 수 시간 동안 IO를 통째로 가져가고, 그동안 OLTP가 체감할 만한 느려짐을 겪는다.

여기서 틀리기 쉽다. autovacuum을 "자동"이라고 믿고 방치하지 말자. 평소 pg_stat_user_tables.n_dead_tup과 SELECT datname, age(datfrozenxid) FROM pg_database를 주기적으로 관측해서, age가 1억을 넘기 시작한 DB는 선제적으로 VACUUM FREEZE를 돌린다. 이건 자동이 실패했을 때를 대비한 수동 타임 버퍼다. 특히 autovacuum을 "쓰기 방해된다"는 이유로 끄거나 scale factor를 너무 키우는 경우, 이 버퍼가 없으면 어느 날 서비스 타임에 anti-wraparound가 터진다.

7) 확장의 자리: background worker와 shared_preload_libraries

PostgreSQL의 확장 모델은 0편에서 얘기한 1986년 설계 선언의 직계다. 그 물리적 구현이 background worker와 shared_preload_libraries다. 공식 문서가 이렇게 정의한다.

"Background workers are modules that can be launched by the postmaster and run under its control."

— PostgreSQL 17 §47 Background Worker Processes

즉 확장은 자기만의 백그라운드 프로세스를 postmaster의 통제 하에 띄울 수 있다. pg_cron, pg_stat_statements, timescaledb, citus 같은 확장이 이 메커니즘으로 동작한다. 이 기능이 쓰는 전역 슬롯 풀이 max_worker_processes(기본 8)다.

7-1) `shared_preload_libraries` — fork 이전에 로드되어야 하는 이유

일부 확장은 공유 메모리 공간을 미리 예약해야 한다. pg_stat_statements가 대표적이다. 이런 확장은 postmaster가 기동하며 공유 메모리를 할당하는 시점에 이미 로드되어 있어야 한다. 그래서 postgresql.conf의 shared_preload_libraries = 'pg_stat_statements,pg_cron'에 넣고 재시작해야 한다. CREATE EXTENSION만으로는 안 되고, 서버 재시작이 강제되는 유일한 이유가 여기다.

7-2) `max_worker_processes`는 슬롯 풀이다

여기서 자주 터지는 함정 하나를 짚자. max_worker_processes(기본 8)는 병렬 쿼리의 worker, 논리 복제 worker, 그리고 확장이 띄운 background worker가 전부 같이 써야 하는 하나의 풀이다. 추가로 max_parallel_workers(기본 8, 단 max_worker_processes 이하로 제한됨)와 max_logical_replication_workers(기본 4)가 이 풀 위에 얹힌 상한이다.

여기서 틀리기 쉽다. 슬롯이 모자라면 에러가 나는 게 아니라 조용히 serial 실행으로 강등된다. 병렬로 돌 줄 알았던 쿼리가 단일 worker로 돌면서 성능이 뚝 떨어지고, pg_stat_activity에는 worker가 안 보인다. 원인이 "worker slot 고갈"이라는 걸 눈치채지 못하면 플래너 탓으로 몰고 가기 쉽다. pg_cron이나 citus를 올린 뒤 병렬 쿼리가 갑자기 느려졌다면 max_worker_processes를 16/32로 키우는 것이 첫 수다.

8) 실무에서 이렇게 읽고 쓴다

연결 수를 늘릴 땐 max_connections와 함께 proc array의 의존 4인방(autovacuum_max_workers, max_wal_senders, max_worker_processes)을 같이 계산한다. 공유 메모리 크기가 고정이므로 전부 재시작이 필요하다는 사실을 자동화 스크립트에 반영해 둔다.
shared_buffers를 바꿀 땐 effective_cache_size도 같이 움직인다. 전자는 할당, 후자는 힌트. 후자를 안 움직이면 플래너가 옛날 세계관에서 돈다.
체크포인트 튜닝은 복제 지연 대응의 첫 단추다. checkpoint_timeout을 5분 → 15분으로 늘리고 max_wal_size를 함께 올리면 full page image 총량이 줄어 replica lag 스파이크가 평평해진다. 단, recovery 시간이 길어진다는 대가는 받아들여야 한다.
pg_stat_bgwriter.buffers_backend를 대시보드에 띄운다. 이 값이 꾸준히 오르면 bgwriter가 못 따라가고 있다는 뜻이고, bgwriter_lru_maxpages/bgwriter_delay 조정이 필요하다.
SELECT datname, age(datfrozenxid) FROM pg_database를 주 1회 스냅샷으로 찍어 둔다. age가 1억을 넘는 DB가 보이면 서비스 저부하 시간에 VACUUM FREEZE를 선제적으로 돌린다. anti-wraparound가 피크 타임에 터지는 것보다 훨씬 낫다.
확장을 올릴 때 max_worker_processes를 반드시 재평가한다. pg_cron, timescaledb, citus, 논리 복제 subscription이 전부 같은 풀을 판다. 슬롯이 모자라면 병렬 쿼리가 조용히 serial로 떨어진다.
work_mem은 세션당이 아니라 플랜 노드당이다. 한 쿼리가 sort/hash 노드 5개를 가지면 work_mem × 5를 먹는다. 연결 수 × work_mem만 계산하면 실제 메모리의 절반도 안 잡힌다.

9) 한 줄 정리

PostgreSQL은 postmaster 하나가 fork로 자식을 찍어내는 프로세스 DB이고, 그 자식들은 공유 메모리 세그먼트 한 덩어리를 매개로 협력한다. 쓰기 경로의 3인 1조, 공유 메모리 5영역, worker slot 한 풀 — 이 세 축을 머릿속에 띄워두면 대부분의 튜닝 파라미터는 어디에 작용하는지 자명해진다. 다음 편부터는 이 지도 위에서 WAL 포맷·MVCC·락 구조를 하나씩 확대해 들어간다.

태그: postgresql, postgres-architecture, postmaster, shared-buffers, wal-writer, bgwriter, checkpointer, autovacuum, wraparound, background-worker

Spring Boot Actuator — Endpoint SPI와 Health·Metrics·Prometheus 내부

dding-shark — Tue, 14 Apr 2026 22:06:20 +0900

Spring Boot Actuator — Endpoint SPI와 Health·Metrics·Prometheus 내부

들어가며

운영 중인 서비스를 다루다 보면 결국 세 가지 질문으로 되돌아온다. 지금 살아 있나, 트래픽을 받을 준비가 됐나, 무슨 일이 일어나고 있나. Spring Boot는 이 세 질문에 답할 수 있는 창구를 Actuator라는 이름으로 묶어놓았다. spring-boot-starter-actuator 의존성 한 줄이 /actuator 경로를 열고, 그 아래에 health, metrics, prometheus 같은 엔드포인트를 걸어둔다. 다만 이 창구는 기본값이 의도적으로 소심하게 잡혀 있다. 뭔가 설정해주지 않으면 web에는 health 하나밖에 안 보인다.

Actuator의 설계 중심은 @Endpoint라는 기술 중립 SPI다. 한 번 선언하면 web과 JMX 양쪽에 동시에 노출되고, @ReadOperation / @WriteOperation / @DeleteOperation이라는 세 가지 HTTP 메서드 대응 어노테이션으로 동작을 정의한다. Health·Info·Metrics 같은 내장 엔드포인트들도 이 SPI 위에 쌓여 있다. 구조를 이해하면 커스텀 엔드포인트를 만드는 일이 @RestController 짜는 것만큼 가볍게 느껴진다. 그런데 실무에서 Actuator를 들여다보면 거의 항상 다음 지점에서 막힌다.

/actuator에 붙었더니 health만 보인다 — 기본 web 노출이 health 하나뿐이고, 나머지는 management.endpoints.web.exposure.include로 명시해야 보인다
/actuator/health가 갑자기 느려졌다 — 커스텀 HealthIndicator가 외부 DB/서드파티 호출에서 대기 중이다. 집계 엔드포인트 하나가 전체 헬스 응답을 붙잡는다
exposure.include=* 한 줄이 프로덕션에서 자격 증명 노출로 이어진다 — env, configprops, beans, threaddump가 전부 열리면서 프로퍼티 원본이 밖으로 새나간다
/actuator/prometheus가 404다 — 엔드포인트 노출은 했는데 micrometer-registry-prometheus 의존성이 없어서 PrometheusMeterRegistry 빈 자체가 안 만들어졌다

이 글은 왜 → 구조(Endpoint SPI) → 동작(내장 엔드포인트) → Health/Metrics/Prometheus → 보안 → 실무 순으로 Spring Boot 3.x / Spring Framework 6.x / Micrometer 1.x 기준으로 정리한다.

1) Actuator가 하는 일과 기본 노출 정책
2) management.endpoints 네임스페이스 설정
3) @Endpoint SPI: 기술 중립 엔드포인트 구조
4) @ReadOperation / @WriteOperation / @Selector
5) 내장 엔드포인트 한눈에
6) Health Contributor: 기본 등록과 커스텀 작성
7) Kubernetes Probes와 ApplicationAvailability
8) Info Contributor와 build-info.properties
9) Micrometer MeterRegistry: Counter·Timer·Gauge·Tag
10) Prometheus 노출
11) Spring Security 통합과 포트 분리
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) Actuator가 하는 일과 기본 노출 정책

Actuator는 **"운영 관점에서 앱을 들여다보는 창구"**를 표준화한 모듈이다. 앱이 살아 있는지, 메트릭이 어떤 값인지, 프로퍼티가 어떻게 바인딩됐는지, 빈이 몇 개 등록돼 있는지 — 이 모든 걸 HTTP(또는 JMX)로 꺼내 볼 수 있게 한다. 핵심은 이 창구들이 개별 컨트롤러로 일일이 만들어진 게 아니라 공통 SPI 위에 얹혀 있다는 것이다. 내장 엔드포인트도 커스텀 엔드포인트도 같은 @Endpoint 인프라를 공유한다.

spring-boot-starter-actuator 의존성만 추가하면 Boot 자동구성이 WebEndpointAutoConfiguration과 JmxEndpointAutoConfiguration을 타면서 /actuator 경로와 JMX 도메인을 함께 세팅한다. 다만 어떤 엔드포인트가 밖으로 노출되느냐는 별개 문제다. 여기서 틀리기 쉽다 — 활성(enabled)과 노출(exposure)은 다른 축이다. 활성은 엔드포인트 빈이 실제로 등록되느냐이고, 노출은 그 엔드포인트가 web이나 JMX 채널로 공개되느냐다. 둘 다 켜져야 밖에서 보인다.

1-1) 기본 노출 정책

채널	기본 노출 대상
web	`health`
JMX	`*` (모든 엔드포인트)

web이 유독 인색하다. health 하나뿐이고 나머지는 명시해야 보인다. 이 정책은 의도된 것이다. env나 beans, threaddump 같은 엔드포인트는 자격 증명·내부 구조 노출 위험이 있어서, 개발자가 "나는 이걸 열겠다"고 선언할 때만 나가도록 잠가놨다. JMX는 기본적으로 로컬/내부망용이라 덜 엄격하다.

2) management.endpoints 네임스페이스 설정

노출·활성·세부 동작은 전부 management. 네임스페이스로 모여 있다. Boot의 설정 메타데이터도 이 네임스페이스를 별도로 분리해 두었는데, 이유는 애플리케이션 설정(spring.*)과 운영 설정(management.*)을 분리하려는 것이다. 포트·경로·보안까지 모두 management로 나눠 두면, 운영이 앱 설정을 건드리지 않고도 엔드포인트 정책만 조정할 수 있다.

2-1) 대표 설정

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
        exclude: env
      base-path: /actuator       # 기본 /actuator
    jmx:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: when-authorized   # never / always / when-authorized
      probes:
        enabled: true                  # liveness/readiness 분리 노출
  server:
    port: 9090                        # 애플리케이션 포트와 분리

여기서 기억할 세 가지.

첫째, endpoints.web.exposure.include는 엔드포인트 id 기반 화이트리스트다. 쉼표 구분 목록 또는 * 와일드카드가 들어간다. exclude는 include에 걸린 것 중 일부를 빼는 용도다. include: "*"에서 exclude: env로 제외하는 패턴이 흔한데, 이게 안전해 보여도 이후 Boot가 새 엔드포인트를 추가했을 때 자동으로 열리는 문제가 생긴다. 운영에서는 include를 명시 리스트로 잠그는 쪽이 안전하다.

둘째, endpoint.{id}. 네임스페이스는 각 엔드포인트의 세부 옵션이다. health.show-details가 대표적이다. never(기본)는 {"status": "UP"}만 반환하고, always는 모든 HealthIndicator의 디테일을 다 뱉는다. when-authorized는 Spring Security로 인증된 요청에만 디테일을 보여준다.

셋째, management.server.port를 애플리케이션 포트와 다르게 지정하면 내부망 전용 포트로 Actuator가 분리된다. LB에서 8080만 외부 공개하고 9090은 쿠버네티스 내부 probe나 Prometheus scrape 전용으로 두는 게 흔한 구성이다.

3) @Endpoint SPI: 기술 중립 엔드포인트 구조

Actuator 설계의 핵심은 엔드포인트 정의를 특정 전송 기술에 묶지 않는다는 점이다. @RestController는 HTTP 전용이고 @ManagedResource는 JMX 전용이다. Actuator는 그 중간을 원했다. **"한 번 선언하면 web과 JMX 둘 다에 나간다"**라는 모델을 위해 @Endpoint라는 추상을 새로 만들었다.

@Endpoint(id="custom")이 붙은 빈은 EndpointDiscoverer가 찾아내 ExposableWebEndpoint 또는 ExposableJmxEndpoint로 변환한다. 변환 과정에서 메서드마다 붙은 @ReadOperation, @WriteOperation, @DeleteOperation을 HTTP GET/POST/DELETE 또는 JMX 속성/작업에 각각 매핑한다. 디스패처 역할은 WebMvcEndpointHandlerMapping(Servlet 스택)이나 WebFluxEndpointHandlerMapping(Reactive)이 맡는다.

3-1) 어노테이션 맵

어노테이션	용도
`@Endpoint(id="...")`	기술 중립 엔드포인트 선언. web·JMX 동시 노출
`@WebEndpoint(id="...")`	web 전용 엔드포인트
`@JmxEndpoint(id="...")`	JMX 전용 엔드포인트
`@ServletEndpoint(id="...")`	서블릿 레벨 커스텀 엔드포인트 (Boot 3.3+에서 deprecated)
`@ReadOperation`	HTTP GET / JMX 속성 읽기
`@WriteOperation`	HTTP POST / JMX 작업
`@DeleteOperation`	HTTP DELETE / JMX 작업
`@Selector`	경로 변수 매핑 (`/actuator/{id}/{selector}`)

3-2) 엔드포인트 발견 흐름

이 구조 덕분에 한 엔드포인트를 두 채널이 공유하는 비즈니스 로직으로 다룰 수 있다. health도 info도 이 경로로 나간다.

4) @ReadOperation / @WriteOperation / @Selector

실제로 커스텀 엔드포인트를 만들어 보자. 앱의 피쳐 토글 상태를 읽고 쓰는 엔드포인트라고 가정한다.

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {

    private final Map<String, Boolean> features = new ConcurrentHashMap<>();

    @ReadOperation
    public Map<String, Boolean> features() {
        return features;
    }

    @ReadOperation
    public Feature feature(@Selector String name) {
        Boolean enabled = features.get(name);
        return enabled == null ? null : new Feature(enabled);
    }

    @WriteOperation
    public void configureFeature(@Selector String name, boolean enabled) {
        features.put(name, enabled);
    }

    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }

    public record Feature(boolean enabled) {}
}

이 한 클래스만으로 다음이 동시에 노출된다.

HTTP	경로	메서드
GET	`/actuator/features`	`features()`
GET	`/actuator/features/{name}`	`feature(name)`
POST	`/actuator/features/{name}` (body: `{"enabled": true}`)	`configureFeature(name, enabled)`
DELETE	`/actuator/features/{name}`	`deleteFeature(name)`

여기서 주의할 것이 있다. @ReadOperation은 반환값이 null이면 HTTP 404를 자동으로 돌려준다. 명시적으로 ResponseEntity를 만들 필요가 없다. @WriteOperation의 파라미터 중 @Selector가 붙지 않은 것은 요청 body의 JSON 필드로 매핑된다. 위의 enabled 파라미터가 그렇다. 이건 @RequestBody와 다르다 — 객체 전체가 아니라 필드 단위로 개별 파라미터에 바인딩된다.

4-1) @Selector와 매치 타입

@Selector는 두 가지 매치 모드를 지원한다.

@ReadOperation
public Object one(@Selector String name) { ... }          // 단일 경로 세그먼트

@ReadOperation
public Object path(@Selector(match = Match.ALL_REMAINING) String[] parts) { ... }
// /actuator/features/a/b/c → parts = ["a", "b", "c"]

두 번째 패턴은 중첩 키 같은 걸 표현할 때 쓴다. 내장 엔드포인트 중 logger가 이런 구조를 쓴다 — /actuator/loggers/com.example.Foo처럼 로거 이름에 점(.)이 들어가기 때문이다.

5) 내장 엔드포인트 한눈에

Boot는 운영에서 쓸 만한 엔드포인트를 이미 내장해 두었다. 의존성만 추가해 두면 활성 상태로 있고, 노출만 해주면 된다.

id	용도	HTTP 메서드
`health`	`HealthContributor` 집계 상태	GET
`info`	빌드/Git/커스텀 info	GET
`metrics`	Micrometer 메트릭 조회	GET (`?tag=key:value`)
`prometheus`	Prometheus scrape 포맷 출력	GET
`loggers`	로그 레벨 조회/변경	GET/POST
`env`	`Environment` 프로퍼티 조회	GET
`configprops`	`@ConfigurationProperties` 바인딩 결과	GET
`mappings`	MVC/WebFlux 매핑 목록	GET
`beans`	ApplicationContext의 모든 빈	GET
`conditions`	자동구성 조건 평가 결과	GET
`threaddump`	JVM 스레드 덤프	GET
`heapdump`	JVM 힙 덤프 (바이너리)	GET
`scheduledtasks`	스케줄러 작업 목록	GET
`caches`	캐시 목록/조작	GET/DELETE
`httpexchanges`	최근 HTTP 요청 기록 (3.0부터 `httptrace` → `httpexchanges`로 이름 변경)	GET
`sessions`	HTTP 세션 조회/만료	GET/DELETE
`flyway` / `liquibase`	마이그레이션 이력	GET
`shutdown`	`ApplicationContext.close()` (기본 비활성)	POST

이 중 운영 필수는 health, info, metrics, prometheus, loggers 정도다. env, beans, configprops, threaddump, heapdump는 디버깅용이지 외부에 상시 노출할 것이 아니다. shutdown은 기본 비활성이고, management.endpoint.shutdown.enabled=true + 노출 + permitAll 조합이 걸리면 외부에서 curl -X POST로 앱을 죽일 수 있다. 여기서 틀리기 쉽다 — Actuator 보안을 별도로 걸지 않으면 이 조합이 생각보다 쉽게 발생한다.

6) Health Contributor: 기본 등록과 커스텀 작성

/actuator/health는 단일 표시기가 아니라 여러 HealthContributor의 집계 결과다. Boot가 클래스패스와 자동구성을 훑어서 감지된 컴포넌트마다 표시기를 등록한다. DataSource가 있으면 DataSourceHealthIndicator가, Redis가 있으면 RedisHealthIndicator가 자동으로 달라붙는다.

6-1) 자동 등록되는 주요 Indicator

조건	Indicator
항상	`DiskSpaceHealthIndicator`, `PingHealthIndicator`
DataSource 빈 존재	`DataSourceHealthIndicator`
`spring-data-redis`	`RedisHealthIndicator`
`spring-data-mongodb`	`MongoHealthIndicator`
Elasticsearch	`ElasticsearchRestHealthIndicator`
RabbitMQ	`RabbitHealthIndicator`
Kafka	`KafkaHealthIndicator`

PingHealthIndicator는 항상 UP을 반환하는 기본 표시기다. 아무 의존성이 없는 상태에서도 /actuator/health가 UP을 돌려주는 이유다.

6-2) 커스텀 HealthIndicator

커스텀 헬스 표시기는 HealthIndicator 하나만 구현하면 된다.

@Component
public class ExternalApiHealthIndicator implements HealthIndicator {

    private final ExternalApiClient client;

    @Override
    public Health health() {
        try {
            ExternalApiClient.Status s = client.ping();   // 외부 호출
            if (s.ok()) {
                return Health.up()
                        .withDetail("latencyMs", s.latencyMs())
                        .build();
            }
            return Health.down().withDetail("reason", s.reason()).build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

Boot는 빈 이름에서 HealthIndicator 접미사를 떼어 id로 사용한다. 위 예시는 externalApi라는 id로 /actuator/health에 포함된다.

6-3) Status 집계 규칙

여러 표시기의 상태가 섞이면 StatusAggregator가 우선순위에 따라 최종 상태를 결정한다. 기본 우선순위는 다음과 같다.

DOWN > OUT_OF_SERVICE > UP > UNKNOWN

하나라도 DOWN이면 전체가 DOWN이다. 이 규칙이 의미하는 바는 무겁다 — 아주 작은 외부 의존성 하나가 전체 헬스를 내린다. 전체 헬스가 내려가면 쿠버네티스 liveness probe가 이걸 보고 Pod를 재시작할 수도 있다. 여기서 "이 의존성이 정말 liveness에 연결되어야 하나"를 한번 묻고 가야 한다.

6-4) 함정: 느린 HealthIndicator

커스텀 HealthIndicator에서 외부 DB/HTTP를 호출하면 응답이 오기 전까지 /actuator/health 전체가 대기한다. 표시기 하나가 3초 지연되면 헬스 응답도 3초 걸린다. 쿠버네티스는 probe 타임아웃을 보통 1초로 잡기 때문에, 이 조합이 재앙으로 간다.

해결책은 두 가지다.

그룹 분리: management.endpoint.health.group.*로 표시기를 그룹화해서, probe에는 가벼운 그룹만 연결한다
기본 비활성화 + 선택 활성화: management.health.defaults.enabled=false로 전체를 끄고 필요한 것만 켠다

management:
  endpoint:
    health:
      group:
        liveness:
          include: livenessState
        readiness:
          include: readinessState,db,redis

이 설정이면 /actuator/health/liveness는 앱 자체 상태만 보고, /actuator/health/readiness는 DB·Redis를 포함해서 본다.

7) Kubernetes Probes와 ApplicationAvailability

쿠버네티스는 liveness(살아 있나)와 readiness(트래픽 받을 준비됐나)를 구분한다. Boot는 이 두 개념을 **ApplicationAvailability**라는 추상으로 제공하고, probes.enabled=true면 /actuator/health/liveness, /actuator/health/readiness를 별도로 노출한다.

7-1) LivenessState와 ReadinessState

public enum LivenessState {
    CORRECT,   // 앱이 정상 동작 중 → UP
    BROKEN     // 내부 오류 → DOWN
}

public enum ReadinessState {
    ACCEPTING_TRAFFIC,   // 트래픽 받을 준비 완료
    REFUSING_TRAFFIC     // 아직/이제 안 받음
}

LivenessState.BROKEN은 앱 재시작이 아니면 회복 불가능한 상태를 의미한다. DB 커넥션 실패 같은 일시 장애는 liveness로 간주하지 않는다. readiness는 훨씬 자주 바뀐다 — 앱이 뜨는 중, 스케일아웃·셧다운 직전, 부하 과다 등에서 REFUSING_TRAFFIC이 될 수 있다.

7-2) 상태 변경 이벤트

상태는 코드에서 AvailabilityChangeEvent.publish로 바꾼다.

@Component
public class GracefulShutdownListener {

    @EventListener(ContextClosedEvent.class)
    public void onClose(ContextClosedEvent event) {
        AvailabilityChangeEvent.publish(
            event.getApplicationContext(),
            ReadinessState.REFUSING_TRAFFIC
        );
    }
}

이 패턴은 앱이 종료되기 전에 readiness를 먼저 내리는 graceful shutdown의 핵심이다. LB가 readiness probe 실패를 보고 Pod를 제외한 다음에야 실제 종료가 진행되도록 순서를 만들 수 있다.

7-3) 쿠버네티스 probe 설정 예시

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 9090        # management.server.port
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 9090
  periodSeconds: 5

management 포트를 분리해 두면 이 probe 트래픽은 내부망으로만 간다. 애플리케이션 포트에 probe를 걸면 메인 스레드 풀과 경쟁하게 되어 부하 상황에서 probe가 먼저 실패하는 사고가 난다.

8) Info Contributor와 build-info.properties

/actuator/info는 기본적으로 비어 있다. {}가 반환된다. 내용을 채우려면 InfoContributor가 필요하다. Boot는 몇 가지 기본 Contributor를 제공한다.

Contributor	활성 조건	출처
`EnvironmentInfoContributor`	`management.info.env.enabled=true` (3.x 기본 false)	`info.*` 프로퍼티
`GitInfoContributor`	`git.properties` 존재	Git 메타데이터
`BuildInfoContributor`	`META-INF/build-info.properties` 존재	빌드 메타데이터
`JavaInfoContributor`	`management.info.java.enabled=true`	JVM 정보
`OsInfoContributor`	`management.info.os.enabled=true`	OS 정보

8-1) build-info.properties 생성

spring-boot-maven-plugin의 build-info goal이 빌드 시점에 META-INF/build-info.properties를 만든다.

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Gradle에서는 springBoot { buildInfo() }가 같은 역할을 한다. 이 파일이 생기면 /actuator/info에서 빌드 시각·버전·아티팩트 id를 바로 볼 수 있다.

8-2) 커스텀 InfoContributor

@Component
public class RevisionInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("revision", Map.of(
            "commit", System.getenv("GIT_COMMIT"),
            "branch", System.getenv("GIT_BRANCH")
        ));
    }
}

/actuator/info의 revision 키 아래에 원하는 구조를 주입할 수 있다. 배포 파이프라인이 주입하는 환경 변수를 그대로 노출할 때 편하다.

9) Micrometer MeterRegistry: Counter·Timer·Gauge·Tag

Actuator의 metrics 엔드포인트는 Micrometer가 관리하는 메트릭을 그대로 꺼내 보여준다. Boot 2.x 이후 메트릭 API는 전부 Micrometer로 통일됐고, Actuator는 MeterRegistry를 DI 받아 쓰는 얇은 인터페이스만 제공한다.

9-1) Meter 타입

타입	용도	예시
`Counter`	누적 단조 증가	요청 수, 에러 수
`Timer`	지연 시간 + 호출 수	HTTP 요청 지연
`Gauge`	현재 값 스냅샷	큐 크기, 커넥션 풀 사용량
`DistributionSummary`	크기 분포	응답 페이로드 바이트
`LongTaskTimer`	장기 작업의 진행 중 시간	배치 작업

9-2) 기본 등록 메트릭

의존성 추가만으로 다음이 자동으로 수집된다.

JVM: jvm.memory.*, jvm.gc.*, jvm.threads.*, jvm.classes.*
시스템: system.cpu.usage, process.cpu.usage, process.files.open
HTTP 서버 요청: http.server.requests (uri·method·status·outcome 태그 포함)
Tomcat/Jetty: tomcat.sessions.*, tomcat.threads.*
Logback: logback.events (level 태그)
DataSource: hikaricp.connections.* (HikariCP 사용 시)

http.server.requests가 가장 자주 쓰인다. /actuator/metrics/http.server.requests?tag=uri:/api/users&tag=status:200처럼 태그로 필터링해서 볼 수 있다.

9-3) 커스텀 메트릭과 공통 태그

@Service
public class OrderService {

    private final Counter orderCounter;
    private final Timer processTimer;

    public OrderService(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.created")
                .description("생성된 주문 수")
                .tag("region", "kr")
                .register(registry);
        this.processTimer = registry.timer("orders.process", "type", "sync");
    }

    public void create(Order o) {
        processTimer.record(() -> {
            // ... 비즈니스 로직
            orderCounter.increment();
        });
    }
}

모든 메트릭에 공통 태그를 주입하고 싶으면 MeterRegistryCustomizer를 쓴다.

@Bean
MeterRegistryCustomizer<MeterRegistry> commonTags() {
    return registry -> registry.config().commonTags(
        "application", "order-service",
        "env", "prod"
    );
}

이렇게 등록한 태그는 모든 메트릭에 자동으로 붙는다. Prometheus에서 여러 서비스를 구분하거나 env=prod/env=dev를 나눠 볼 때 필수다.

9-4) @Timed / @Counted / @Observed

AOP 기반 어노테이션도 지원한다.

@Timed(value = "order.create.time", histogram = true)
public Order create(Command cmd) { ... }

@Timed는 TimedAspect 빈이 등록돼 있어야 동작한다. Boot 자동구성이 spring-aop가 클래스패스에 있으면 기본 등록한다. @Observed(Micrometer 1.10+)는 Timer와 Trace를 동시에 발행해 Micrometer Tracing으로 전파된다.

10) Prometheus 노출

/actuator/prometheus는 Prometheus scrape 포맷으로 메트릭을 뱉어주는 엔드포인트다. 핵심은 이 엔드포인트가 의존성에 의해 활성화된다는 점이다.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

이 의존성이 있으면 PrometheusMetricsExportAutoConfiguration이 PrometheusMeterRegistry를 등록하고, /actuator/prometheus 엔드포인트가 같이 켜진다. 없으면 엔드포인트 자체가 등록되지 않는다 — 노출 설정만 해서는 404다. 여기서 틀리기 쉽다.

10-1) Prometheus scrape 설정

# prometheus.yml
scrape_configs:
  - job_name: order-service
    metrics_path: /actuator/prometheus
    scrape_interval: 15s
    static_configs:
      - targets: ['order-service:9090']

scrape_interval은 너무 짧게 잡지 않는다. 5초 이하로 내리면 매 scrape마다 histogram 계산·라벨 직렬화에 CPU와 GC 부담이 실제로 관찰된다. 15~30초가 기본 권장이다.

10-2) 히스토그램과 백분위

Timer에서 p95, p99 같은 백분위를 보고 싶으면 두 가지 선택지가 있다.

registry.timer("orders.process",
    Tags.of("type", "sync"));
// 또는 builder로

Timer.builder("orders.process")
    .publishPercentileHistogram()   // Prometheus에서 histogram_quantile 사용
    .register(registry);

publishPercentiles(0.95, 0.99)는 앱 JVM이 백분위를 계산해서 내보낸다. 반면 publishPercentileHistogram()은 히스토그램 버킷만 내보내고 Prometheus 쪽에서 histogram_quantile로 계산한다. 후자가 여러 인스턴스 합산 시 더 정확하다 — 인스턴스별 백분위는 평균을 낼 수 없기 때문이다.

11) Spring Security 통합과 포트 분리

Actuator 엔드포인트는 Spring Security가 없으면 그냥 열려 있다. 프로덕션에서는 최소한 health·info를 제외한 나머지를 인증 뒤로 숨기는 게 기본이다.

11-1) EndpointRequest 매처

Spring Security의 EndpointRequest는 Actuator 엔드포인트에 특화된 RequestMatcher를 제공한다.

@Bean
SecurityFilterChain actuator(HttpSecurity http) throws Exception {
    http
        .securityMatcher(EndpointRequest.toAnyEndpoint())
        .authorizeHttpRequests(auth -> auth
            .requestMatchers(EndpointRequest.to("health", "info")).permitAll()
            .requestMatchers(EndpointRequest.to("prometheus")).hasRole("MONITORING")
            .anyRequest().hasRole("ADMIN")
        )
        .httpBasic(Customizer.withDefaults())
        .csrf(csrf -> csrf.disable());
    return http.build();
}

EndpointRequest.toAnyEndpoint()는 현재 등록된 모든 엔드포인트를 매치한다. 경로 하드코딩(/actuator/**)보다 안전하다 — management.endpoints.web.base-path를 바꿔도 자동으로 따라간다.

11-2) 포트 분리 + 방화벽

management:
  server:
    port: 9090
    address: 127.0.0.1   # 외부에서 접근 불가

management.server.address=127.0.0.1을 주면 9090은 로컬 루프백으로만 바인딩된다. 쿠버네티스에서는 이 설정을 쓰지 않고 0.0.0.0으로 두되, NetworkPolicy로 scrape 소스를 제한하는 쪽이 실용적이다. 어느 쪽이든 Actuator 포트를 LB 뒤로 외부 공개하지 않는 것이 원칙이다.

11-3) 와일드카드 노출의 위험

management:
  endpoints:
    web:
      exposure:
        include: "*"   # 피하기

*는 현재뿐 아니라 미래에 Boot가 추가할 엔드포인트까지 전부 연다. 운영에서 이 설정 + permitAll 조합이 나오면 env, beans, configprops, threaddump, heapdump가 전부 외부로 노출된다. env는 특히 위험하다 — 바인딩된 프로퍼티 원본이 그대로 JSON으로 나간다. DB 비밀번호가 spring.datasource.password에 바인딩돼 있으면 마스킹이 걸려도 키 이름만으로도 스키마가 드러난다.

선호되는 방식은 명시 화이트리스트다.

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers

12) 실무에서 이렇게 읽고 쓴다

운영 기본 조합: include: health,info,metrics,prometheus. 여기서 늘리고 싶으면 하나씩 추가. 와일드카드는 쓰지 않는다.
포트 분리: management.server.port=9090. LB는 8080만 외부 공개, 9090은 내부망 전용으로 scrape·probe만 받는다.
Health 그룹 분리: liveness는 livenessState만, readiness는 외부 의존성 포함. 느린 HealthIndicator 때문에 probe가 꺼지는 사고를 막는다.
Prometheus 의존성 확인: /actuator/prometheus가 404면 micrometer-registry-prometheus가 빠진 것. 노출 설정만 고쳐선 안 된다.
build-info 활성화: spring-boot-maven-plugin의 build-info goal을 켜서 /actuator/info에 빌드 메타데이터를 노출. 배포 시 어떤 커밋이 올라가 있는지 확인이 빠르다.
공통 태그: MeterRegistryCustomizer로 application, env, region 같은 태그를 common으로 박아둔다. Prometheus/Grafana에서 여러 서비스 구분이 이 위에서 돈다.
shutdown 엔드포인트: 기본 비활성인 채로 두는 게 맞다. 롤링 업데이트는 쿠버네티스가 SIGTERM으로 처리한다. Actuator로 종료 트리거를 외부에 열지 않는다.
env/configprops는 닫아둔다: 디버깅이 필요하면 ROLE_ADMIN으로 잠그거나, VPN 뒤에서만 접근 가능한 포트로 분리. 기본 노출 리스트에 넣지 않는다.
/actuator/metrics/http.server.requests로 즉석 확인: ?tag=uri:/api/xxx&tag=status:500으로 특정 엔드포인트의 에러율을 빠르게 볼 수 있다. Grafana 없이도 현장에서 확인 가능하다.
커스텀 HealthIndicator에 타임아웃: 외부 호출이 들어간다면 반드시 클라이언트 레벨 타임아웃(예: RestClient 타임아웃 2~3초)을 걸어둔다. 헬스 응답이 전체 probe를 붙잡는 사고를 막는다.

13) 한 줄 정리

Actuator는 @Endpoint SPI 위에 내장 엔드포인트와 커스텀 엔드포인트가 동일한 방식으로 쌓이는 운영 창구다. 기본은 web에 health만 노출되고, 나머지는 management.endpoints.web.exposure.include로 명시해야 한다는 엄격한 기본값이 의도적으로 깔려 있다. 운영에서는 와일드카드 노출을 금지하고, Actuator 포트를 분리하고, Health 표시기의 외부 호출 타임아웃을 걸어두는 세 가지가 사고를 막는 최소 방어선이다.

태그: Spring Boot, Actuator, Endpoint SPI, HealthIndicator, Micrometer, Prometheus, Kubernetes Probes, MeterRegistry, Observability, Spring Security

Spring Boot Externalized Configuration — @ConfigurationProperties 바인딩과 Profile·spring.config.import

dding-shark — Tue, 14 Apr 2026 22:05:49 +0900

Spring Boot Externalized Configuration — @ConfigurationProperties 바인딩과 Profile·spring.config.import

들어가며

9편에서 Environment가 어떻게 조립되는가 — PropertySource 평면 리스트에 누가 먼저 꽂히느냐로 우선순위가 결정된다는 이야기를 했다. 이번 편은 그 이야기의 자매편이다. 9편이 "조립의 원리"였다면, 이번은 Spring Boot가 실무에서 실제로 제공하는 설정 주입 수단 전부를 기능별로 펼쳐 보는 쪽이다. application.yml, application-{profile}.yml, spring.config.import, 생성자 바인딩, Duration 단위 파싱, @Validated 기동 검증 — 이름은 다들 들어봤지만 한 번에 정리해둔 지도가 없어 매번 각 기능의 문서를 따로 찾아다니게 된다.

특히 Spring Boot 2.4에서 설정 로딩 구조가 크게 바뀌었다. Config Data API라는 새 추상이 도입되면서 spring.profiles.include와 spring.config.additional-location의 상당 부분이 spring.config.import로 흡수됐다. 2.4 이전에 익숙했던 문법 일부가 3.x에서는 쓰지 말아야 할 것으로 바뀌었고, 그 차이를 모르고 쓰면 "예전엔 되던 게 왜 안 되지?"가 된다. 이 글은 Spring Boot 3.x / Spring Framework 6.x 기준으로 정리한다.

이 주제에서 특히 막히기 쉬운 지점이 있다.

APP_MAIL_HOST 환경변수를 세팅했는데 @Value("${app.mail.host}")가 못 찾는다 — Relaxed Binding은 @ConfigurationProperties 쪽이 더 관대하다
yml에 프로파일별 블록을 쓰는 예전 spring.profiles: prod 문법이 안 먹는다 — 2.4+는 spring.config.activate.on-profile로 바뀌었다
spring.config.import를 썼는데 파일이 없어서 기동 실패한다 — optional: 접두사를 빼먹은 것이다
Duration timeout = 30s를 쓰고 싶은데 바인딩이 깨진다 — 필드 타입이 long이면 단위 표기를 못 받는다

이 글은 우선순위 → 파일 전략 → 바인딩 → 검증 → 디버깅 → 실무 순으로 정리한다.

1) Externalized Configuration의 큰 그림
2) PropertySource 우선순위 14계층
3) application.yml 위치·프로파일 우선순위
4) spring.config.import: 2.4+의 새 문법
5) Profile 전략: active / include / group / default
6) @ConfigurationProperties vs @Value
7) 생성자 바인딩과 Relaxed Binding
8) Duration / DataSize / Period 컨버터
9) @Validated로 기동 시점 검증
10) Origin 추적과 /actuator/env 디버깅
11) 시크릿: configtree와 Vault
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) Externalized Configuration의 큰 그림

1-1) 세 축: 소스 / 바인딩 / 검증

Spring Boot의 설정 시스템은 세 축으로 분해된다. 독립적으로 이해하고 조합할 줄 알아야 전체가 보인다.

축	역할	대표 기능
소스(Source)	어디서 값이 오는가	`application.yml`, 환경변수, CLI 인자, Vault, ConfigMap
바인딩(Binding)	값을 어떻게 객체로 묶는가	`@Value`, `@ConfigurationProperties`, 생성자 바인딩
검증(Validation)	잘못된 값을 언제 실패시키는가	`@Validated` + JSR-380, 기동 시점 실패

9편에서 본 PropertySource 우선순위는 소스 축 이야기였다. 이번 글은 세 축을 모두 걸쳐서 다룬다 — spring.config.import가 소스 축, @ConfigurationProperties가 바인딩 축, @Validated가 검증 축이다.

1-2) "외부화"의 의미

"Externalized"라는 단어가 모호해서 혼동을 부른다. 엄밀히 말하면 빌드 산출물(jar) 안에 고정되지 않은 모든 설정이 외부화 대상이다. 같은 jar를 dev / stage / prod에 그대로 배포하되 값만 바꾸는 게 목표다. 그래서 다음 세 가지가 모두 "외부" 소스다.

빌드 시점에는 알지 못하는 값 — DB 호스트, API 키, 외부 URL
환경마다 달라지는 값 — 로그 레벨, 커넥션 풀 크기, 기능 플래그
비밀 값 — 토큰, 비밀번호, 서명 키

jar 안의 application.yml에 디폴트를 넣고, jar 밖의 프로파일/환경변수/Vault로 오버라이드하는 구조가 기본이다.

2) PropertySource 우선순위 14계층

2-1) Boot 3.x 기준 공식 순서

Spring Boot가 기동 시 꽂는 PropertySource의 공식 순서다 (위쪽이 우선). 9편에서 다룬 15단계 중 Boot 3.x에서 실질적으로 관찰되는 14개를 공식 순서대로 정리한 판이다.

#	소스	예시
1	DevTools 글로벌 설정	`~/.config/spring-boot/`
2	`@TestPropertySource`	테스트 전용
3	`@SpringBootTest(properties=...)`	테스트 전용
4	CLI 인자	`--app.mail.host=smtp.example.com`
5	`SPRING_APPLICATION_JSON`	`SPRING_APPLICATION_JSON='{"app":{"mail":{"host":"x"}}}'`
6	ServletConfig / ServletContext init 파라미터	web.xml
7	JNDI	`java:comp/env`
8	Java 시스템 프로퍼티	`-Dapp.mail.host=x`
9	OS 환경변수	`APP_MAIL_HOST=smtp.example.com`
10	`application-{profile}.yml` / `.properties`	jar 밖 → jar 안
11	`application.yml` / `application.properties`	jar 밖 → jar 안
12	`@PropertySource`	`@PropertySource("classpath:custom.properties")`
13	`SpringApplication.setDefaultProperties`	코드에서 주입한 디폴트
14	기본값 (`@Value("${key:default}")`)	최종 디폴트

요점은 이 흐름이다 — 테스트 > CLI > SPRING_APPLICATION_JSON > Servlet init > JNDI > 시스템 프로퍼티 > 환경변수 > profile yml > 공통 yml > @PropertySource > setDefaultProperties > @Value 기본값. 각 지점에서 앞선 레벨이 값을 갖고 있으면 뒤는 보지도 않는다.

2-2) 함정: CLI vs 환경변수

흔한 오해 한 가지 — "환경변수가 CLI보다 세다"는 감각은 반대다. Boot 3 공식 순서에서 CLI 인자가 OS 환경변수보다 높다. 같은 키가 CLI와 환경변수 양쪽에 있으면 CLI가 이긴다.

이게 실전에서 가장 흔한 설정 사고를 만든다. 운영자가 환경변수로 APP_MAIL_HOST를 오버라이드한다고 믿고 kubectl set env를 때렸는데, 실행 스크립트의 엔트리포인트가 java -jar app.jar --app.mail.host=old-host를 그대로 들고 있어 환경변수가 완전히 무시된다. CLI는 yml보다도 높고 환경변수보다도 높아서 한 번 박히면 운영 중에 덮을 길이 거의 없다.

실무 기본선: CLI는 임시 디버깅/일회성용, 영구 오버라이드는 환경변수 또는 프로파일 yml로 분리한다. 엔트리포인트 스크립트와 Dockerfile의 CMD에 --key=v를 박아놓지 말 것. 운영 중 오버라이드 경로를 스스로 막는 짓이다.

2-3) `server.port=${PORT:8080}` 관용구

운영 환경에서 자주 보이는 한 줄이다.

server:
  port: ${PORT:8080}

환경변수 PORT가 있으면 그 값, 없으면 8080. Heroku·Cloud Foundry·Kubernetes에서 포트를 동적으로 주입하는 패턴과 궁합이 맞다. ${KEY:default} 문법은 @Value와 yml 양쪽 모두에서 동작한다 — yml 안에서 placeholder 문법을 쓸 수 있다는 점이 처음엔 어색하지만, Boot가 yml 로드 시점에 PropertyResolver를 돌리기 때문에 가능하다.

3) application.yml 위치·프로파일 우선순위

3-1) 동일 파일명, 네 위치

같은 application.yml이어도 어디에 놓이느냐에 따라 우선순위가 다르다. 위쪽이 우선.

#	위치	용도
1	`./config/`	실행 위치 하위 `config/` 디렉토리
2	`./`	실행 위치 (jar 옆)
3	classpath `/config/`	jar 안의 `src/main/resources/config/`
4	classpath `/`	jar 안의 `src/main/resources/`

실무 패턴은 단순하다. jar 안(#3, #4)에 디폴트를 두고, jar 밖(#1, #2)으로 운영자가 오버라이드한다. 도커 이미지에는 디폴트만 구우면 되고, 컨테이너 런타임에서 /app/config/application.yml을 볼륨 마운트하면 이미지 재빌드 없이 값만 바꾼다.

참고: --spring.config.name과 --spring.config.location으로 파일명/탐색 경로 자체를 바꿀 수 있다. 기본 application이 아닌 myservice로 파일명을 바꾸거나, 위 네 위치 대신 임의의 경로를 탐색하게 만들 수 있다.

3-2) Profile-specific 파일 병합

application.yml과 application-{profile}.yml은 같이 로드되어 병합된다. 덮어쓰기가 아니다.

# application.yml (공통)
app:
  mail:
    host: localhost
    port: 25
    timeout: 10s

# application-prod.yml (prod 프로파일 활성화 시만)
app:
  mail:
    host: smtp.production.example.com

spring.profiles.active=prod로 기동하면 최종 값은 host=smtp.production.example.com, port=25, timeout=10s. 공통에서 디폴트를 잡고 프로파일에서 부분만 덮어쓰는 구조가 권장된다. 프로파일 yml에 전체를 다시 복사하면 공통 변경이 전파되지 않는다.

3-3) 같은 프로파일, 여러 위치

프로파일별 파일도 위치 우선순위가 동일하게 적용된다. ./config/application-prod.yml이 classpath의 application-prod.yml보다 우선한다. 운영 환경에서 민감 정보만 ./config/application-prod.yml로 오버라이드하고, 공개해도 되는 기본 prod 설정은 jar 안에 박아두는 분리가 가능하다.

4) spring.config.import: 2.4+의 새 문법

4-1) 왜 생겼나

Spring Boot 2.4 이전에는 여러 외부 설정 파일을 끌어올 때 spring.config.additional-location과 spring.profiles.include를 조합해야 했다. 로딩 순서가 모호했고, "프로파일 import"와 "파일 import"가 뒤섞여 있어 혼란이 컸다.

2.4에서 Config Data API가 도입되면서 단일 엔트리 spring.config.import로 통합됐다. 그리고 이 핵심 메시지가 중요하다 — spring.config.import는 단순 파일 경로가 아니라 플러그인 가능한 리졸버를 받는다. 파일, 디렉토리, Config Server, Vault, 커스텀 리졸버까지 같은 문법으로 표현한다.

4-2) 기본 문법

spring:
  config:
    import:
      - optional:file:./override.yml
      - optional:classpath:shared-config.yml
      - optional:configtree:/etc/secrets/
      - optional:configserver:http://config-server:8888

각 엔트리는 [optional:]<scheme>:<location> 형태다. scheme 종류가 의미를 결정한다.

scheme	의미
`file:`	파일 시스템의 yml/properties
`classpath:`	classpath 리소스
`configtree:`	디렉토리 구조를 키-값으로 (K8s Secret 마운트)
`configserver:`	Spring Cloud Config Server
(커스텀)	`ConfigDataLocationResolver` 구현으로 추가

4-3) 함정: optional: 빠뜨리기

spring.config.import에 적힌 파일이 존재하지 않으면 기동이 실패한다. 이게 설계된 동작이다 — 운영자가 "프로덕션 오버라이드 파일을 꼭 붙여야 한다"고 명시했는데 파일이 없다면 조용히 넘어가는 대신 빨리 터트리는 쪽이 안전하다.

문제는 로컬 개발에서다. 로컬에는 override.yml이 없는 게 정상인데 기동이 실패하면 난감하다. 해결은 optional: 접두사다.

spring:
  config:
    import:
      # 피하기: 로컬에서 파일 없으면 기동 실패
      - file:./prod-override.yml

      # 선호: 없으면 조용히 스킵
      - optional:file:./prod-override.yml

"없어도 되는 리소스"에는 반드시 optional:을 붙인다. 반대로 "반드시 있어야 하는" 시크릿 파일에는 붙이지 않는다 — 없으면 기동이 터지는 게 올바르다.

4-4) configtree: 쿠버네티스 시크릿 마운트

configtree:는 Kubernetes 환경에서 특히 유용하다. K8s가 Secret/ConfigMap을 파일 시스템에 마운트하면 각 키가 파일로 펼쳐진다.

/etc/secrets/
├── app.mail.host       → "smtp.example.com"
├── app.mail.password   → "s3cret"
└── app.mail.port       → "465"

spring.config.import=configtree:/etc/secrets/을 적으면 Boot가 이 디렉토리를 스캔해서 각 파일 이름을 키로, 파일 내용을 값으로 읽어들인다. 환경변수로 시크릿을 노출하지 않아도 돼서 ps, /proc/*/environ 같은 경로로 샐 위험이 줄어든다.

5) Profile 전략: active / include / group / default

5-1) 네 가지 속성

프로파일은 설정을 논리 그룹으로 묶는 메커니즘이다. Boot가 제공하는 네 가지 프로파일 관련 속성을 한 표로.

속성	의미
`spring.profiles.active`	지금 활성화할 프로파일 목록
`spring.profiles.include`	활성 프로파일에 추가로 병합
`spring.profiles.group.<name>`	논리 그룹 → 여러 프로파일 확장
`spring.profiles.default`	아무것도 active 안 하면 이것 사용 (기본값: `default`)

5-2) include vs active

흔한 혼동 지점이다. active는 "외부에서 한 번 결정", include는 "내부에서 항상 따라붙는 것". 예를 들어 모든 환경에서 공통으로 붙어야 하는 audit 프로파일이 있다면.

# application.yml
spring:
  profiles:
    include: audit   # active가 뭐든 audit은 항상 붙음

운영자가 --spring.profiles.active=prod로 기동해도 실제로는 default + audit + prod 세 개가 활성화된다. 이 조합이 application-audit.yml, application-prod.yml을 모두 로드한다.

5-3) group: 이름 하나로 묶어 확장

논리 그룹을 만들어 여러 프로파일을 한 번에 활성화할 수 있다.

spring:
  profiles:
    group:
      production:
        - prod
        - monitoring
        - audit
      local:
        - dev
        - mock-external

--spring.profiles.active=production으로 기동하면 실제로는 prod, monitoring, audit 세 개가 활성화된다. 팀에서 "prod 기동"을 말할 때 매번 세 개를 나열하지 않아도 된다.

5-4) YAML 문서 분리 + on-profile

한 yml 파일 안에서 프로파일별 섹션을 분리하는 문법이 Boot 2.4+에서 바뀌었다. 예전 spring.profiles: prod 문법은 쓰지 말 것.

# 피하기 (Boot 2.3 이하 문법)
spring:
  profiles: prod
spring:
  datasource:
    url: jdbc:mysql://...
---

# 선호 (Boot 2.4+)
spring:
  datasource:
    url: jdbc:h2:mem:dev
---
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: jdbc:mysql://prod-host:3306/app

---로 분리된 각 문서가 독립 단위이고, spring.config.activate.on-profile이 있는 문서는 해당 프로파일이 활성화됐을 때만 적용된다. on-profile: "prod & !dev"처럼 표현식도 지원한다.

6) @ConfigurationProperties vs @Value

6-1) 비교표

두 메커니즘은 자주 섞여 쓰이지만 성격이 다르다.

축	`@Value`	`@ConfigurationProperties`
단위	필드 하나	접두사 아래 객체 전체
SpEL (`#{...}`)	지원	미지원
Placeholder (`${...}`)	지원	지원
Relaxed Binding	제한적	완전 지원
중첩 객체	불가	가능 (하위 클래스)
컬렉션 바인딩	불가	List/Map/Set 가능
검증	없음	`@Validated` + JSR-380
불변성	`final` 불가	생성자 바인딩으로 `final` 가능
IDE 자동완성	없음	`spring-boot-configuration-processor`로 가능

실무 기본선: 여러 키를 묶어 쓰는 모든 설정은 @ConfigurationProperties. @Value는 @Scheduled(fixedDelayString = "${app.delay}")처럼 어노테이션 속성에 박아야 해서 객체로 풀 수 없는 경우에만 쓴다.

6-2) @Value가 Relaxed Binding에서 약한 이유

이 차이가 환경변수 사용 시 결정적이다. 같은 값을 두 방법으로 받는다고 해보자.

# application.yml
app:
  mail:
    host: localhost

APP_MAIL_HOST=smtp.example.com 환경변수를 세팅한 뒤 기동하면.

// @Value 방식
@Value("${app.mail.host}")
private String hostA;

// @ConfigurationProperties 방식
@ConfigurationProperties("app.mail")
public record MailProperties(String host, int port) {}

hostA도 MailProperties.host도 둘 다 smtp.example.com이 들어간다 — 이 단순 케이스에서는 양쪽 모두 동작한다. 문제는 키 형태가 애매한 경우다. yml에 app.mail-host(kebab)로 썼는데 @Value("${app.mailHost}")(camel)로 받으면 @Value는 못 찾는다. @ConfigurationProperties는 mailHost 필드가 kebab 키에 자동 매칭된다. §7에서 상세히 본다.

7) 생성자 바인딩과 Relaxed Binding

7-1) record로 불변 Properties 만들기

Spring Boot 2.3부터 생성자 바인딩이 공식 지원된다. Java record와 조합하면 불변 Properties가 한 줄이다.

@ConfigurationProperties("app.mail")
public record MailProperties(
    String host,
    int port,
    Duration timeout,
    boolean starttls
) {}

@SpringBootApplication
@ConfigurationPropertiesScan   // record가 있는 패키지 스캔
public class Application { }

등록 방법은 세 가지다.

방법	특징
`@ConfigurationProperties` + `@Component`	컴포넌트 스캔으로 등록
`@EnableConfigurationProperties(MailProperties.class)`	명시적 등록, 테스트에서 개별 활성화 쉬움
`@ConfigurationPropertiesScan`	지정 패키지에서 어노테이션 붙은 클래스 자동 등록

record는 생성자가 하나뿐이므로 자동으로 생성자 바인딩이 적용된다. 기존 JavaBean 스타일(getter/setter)로 쓰고 싶다면 클래스로 만들고 setter를 제공하면 된다.

7-2) Relaxed Binding: 네 가지 표기를 하나로

@ConfigurationProperties의 킬러 기능이다. 다음 네 가지 표기는 전부 같은 속성으로 매핑된다.

표기	예시	주 사용처
kebab-case	`app.mail-host`	yml/properties 권장
camelCase	`app.mailHost`	yml 혼용 가능
snake_case	`app.mail_host`	properties
SCREAMING_SNAKE (uppercase + underscore)	`APP_MAIL_HOST`	환경변수 전용

Kubernetes에서 환경변수로 주입하는 APP_MAIL_HOST가 yml의 app.mail-host와 같은 키로 해석되는 이유가 바로 이 Relaxed Binding이다. 규칙: 환경변수는 알파벳/숫자/언더스코어만 허용하므로 dot과 dash가 전부 _로 치환된다. 즉 app.mail-host → APP_MAIL_HOST가 된다.

7-3) 팀 컨벤션: yml은 kebab, 환경변수는 SCREAMING_SNAKE

한 팀에서 두 표기를 섞으면 디버깅 지옥이 된다. 기본선을 정해두자.

# 피하기: 한 파일에 kebab와 camelCase 혼용
app:
  mail-host: smtp.example.com
  mailPort: 465

# 선호: kebab으로 통일
app:
  mail-host: smtp.example.com
  mail-port: 465

환경변수는 자연스럽게 SCREAMING_SNAKE가 되므로 선택권이 없다. 팀 컨벤션을 yml=kebab, env=SCREAMING_SNAKE로 못 박으면 Relaxed Binding이 둘 사이를 연결한다.

7-4) 컴파일 옵션: -parameters

record 생성자 바인딩은 파라미터 이름을 바이트코드에서 읽어온다. -parameters 컴파일 플래그가 없으면 파라미터 이름이 arg0, arg1으로 박혀서 바인딩이 전부 깨진다. Gradle 설정 예시.

tasks.withType(JavaCompile) {
    options.compilerArgs << '-parameters'
}

Spring Boot Gradle plugin이 적용된 프로젝트는 이 옵션을 기본으로 넣어준다. 그래도 spring-boot-starter-parent를 사용하지 않는 멀티모듈 프로젝트에서는 명시적으로 확인해두는 게 안전하다.

8) Duration / DataSize / Period 컨버터

8-1) 단위 접미사 바인딩

Boot는 자주 쓰는 세 타입에 대해 단위 접미사를 자동으로 파싱한다.

타입	예시 문자열	ISO-8601 대안
`Duration`	`10s`, `5m`, `2h`, `30d`	`PT10S`, `PT5M`
`DataSize`	`10MB`, `2GB`, `512KB`	없음
`Period`	`30d`, `3m`, `1y`	`P30D`, `P1Y`

app:
  mail:
    timeout: 10s           # Duration → 10초
    max-size: 25MB         # DataSize → 25MB
    retention: 90d         # Period → 90일

@ConfigurationProperties("app.mail")
public record MailProperties(
    Duration timeout,
    DataSize maxSize,
    Period retention
) {}

문자열의 단위를 타입 매칭에 맡긴다는 점이 중요하다. 10s는 Duration으로 파싱되고, 10MB는 DataSize로 파싱된다. 같은 10이라도 타입이 다르면 해석이 다르다.

8-2) @DurationUnit / @DataSizeUnit: 기본 단위

단위를 안 쓰고 숫자만 적고 싶을 때가 있다. "이 필드는 초 단위"로 고정하고 yml에는 숫자만 쓰는 식.

@ConfigurationProperties("app.mail")
public record MailProperties(
    @DurationUnit(ChronoUnit.SECONDS) Duration timeout,
    @DataSizeUnit(DataUnit.MEGABYTES) DataSize maxSize
) {}

app:
  mail:
    timeout: 10       # 단위 없음 → 10초로 해석
    max-size: 25      # 단위 없음 → 25MB로 해석

yml에 timeout: 10s처럼 단위를 명시해도 여전히 동작한다. @DurationUnit은 "단위 없을 때의 기본값"만 지정하는 셈이다.

8-3) 함정: long 필드에 단위 표기

Duration 대신 long timeoutMillis 같은 원시 타입을 쓰면 단위 접미사를 못 받는다.

app:
  mail:
    timeout: 10s     # long에 바인딩하려 하면 실패

// 피하기
public record MailProperties(long timeout) {}

// 선호: 타입을 Duration으로
public record MailProperties(Duration timeout) {}

"10초"라는 의미를 값이 아니라 타입이 표현하게 하는 게 핵심이다. long으로 받으면 단위가 숫자 뒤에 사라지고 호출부에서 10 * 1000을 일일이 곱해야 한다 — 이게 버그의 온상이다.

8-4) 커스텀 Converter

Boot가 기본 제공하지 않는 타입은 Converter<String, MyType>을 빈으로 등록하면 된다.

@Configuration
public class ConverterConfig {
    @Bean
    @ConfigurationPropertiesBinding
    public Converter<String, URI> stringToUri() {
        return URI::create;
    }
}

@ConfigurationPropertiesBinding 어노테이션이 중요하다. 이게 없으면 일반 Spring MVC 컨버터로만 등록되고 Properties 바인딩 시엔 쓰이지 않는다.

9) @Validated로 기동 시점 검증

9-1) 틀린 값을 빨리 터트리기

설정 오류는 기동 시점에 터져야 한다. 런타임에 처음 그 설정을 읽는 요청이 실패하면 유저 한 명이 그 버그의 제물이 된다. Boot는 @Validated + JSR-380 조합으로 기동 시 검증을 제공한다.

@ConfigurationProperties("app.mail")
@Validated
public record MailProperties(
    @NotBlank String host,
    @Min(1) @Max(65535) int port,
    @NotNull Duration timeout,
    @Pattern(regexp = "^(TLS|STARTTLS|NONE)$") String security
) {}

yml에 host:가 비어 있거나 port: 99999가 있으면 기동이 다음처럼 실패한다.

***************************
APPLICATION FAILED TO START
***************************

Binding to target failed:

    Property: app.mail.port
    Value: 99999
    Reason: 최대 허용 값: 65535

프로덕션 배포가 이 단계에서 막힌다. 롤링 업데이트 중 잘못된 설정이 들어가면 헬스체크가 실패해서 이전 버전이 그대로 유지된다 — 이게 의도된 방어선이다.

9-2) 중첩 객체에 @Valid 붙이기

@ConfigurationProperties 안에 중첩 객체가 있으면 그 필드에 @Valid를 붙여야 하위 필드까지 검증된다.

@ConfigurationProperties("app")
@Validated
public record AppProperties(
    @NotBlank String name,
    @Valid MailProperties mail,     // @Valid 없으면 하위 검증 스킵
    @Valid List<@Valid Endpoint> endpoints
) {
    public record MailProperties(@NotBlank String host, @Min(1) int port) {}
    public record Endpoint(@NotBlank String name, @Pattern(regexp="^https?://.+") String url) {}
}

@Valid를 빠뜨리면 mail.host가 비어 있어도 기동이 성공해버린다. "검증이 돌고 있다는 착각"이 가장 위험하다 — 실제로 검증되는 건 최상위 필드만이다.

9-3) 의존성: spring-boot-starter-validation

JSR-380 구현체(Hibernate Validator)는 Boot 기본 의존성에 포함되지 않는다. 명시적으로 추가해야 한다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-validation'
}

빠뜨리면 @Validated가 조용히 아무 검증도 안 한다. 어노테이션만 붙고 돌아가는 validator가 없기 때문. 테스트를 한 번 돌려서 "일부러 틀린 값"이 실제로 기동을 실패시키는지 확인하는 게 안전하다.

10) Origin 추적과 /actuator/env 디버깅

10-1) OriginTrackedValue

Spring Boot는 각 속성 값이 어디서 왔는지를 추적한다. 모든 PropertySource가 OriginTrackedValue로 값을 감싸서 "이 값은 application-prod.yml 15번째 줄에서 왔음" 같은 메타데이터를 유지한다.

이 정보는 /actuator/env 엔드포인트에서 그대로 노출된다.

{
  "propertySources": [
    {
      "name": "systemEnvironment",
      "properties": {
        "APP_MAIL_HOST": {
          "value": "smtp.production.example.com",
          "origin": "System Environment Property \"APP_MAIL_HOST\""
        }
      }
    },
    {
      "name": "Config resource 'class path resource [application-prod.yml]'",
      "properties": {
        "app.mail.host": {
          "value": "localhost",
          "origin": "class path resource [application-prod.yml] - 3:11"
        }
      }
    }
  ]
}

위 응답에서 보이듯이 APP_MAIL_HOST가 app.mail.host의 환경변수 형태로 해석되고, 실제 적용 값은 환경변수가 이긴다 (systemEnvironment가 yml보다 위). Origin에 "15번째 줄 11번째 칸"까지 찍혀서 "이 값이 어디서 왔지?"를 IDE 없이 답할 수 있다.

10-2) 활성화

management.endpoint.env.show-values가 Boot 3부터 도입됐다. 보안상 기본값은 NEVER — 값을 가리고 키만 보여준다. 디버깅용으로 열려면 명시.

management:
  endpoint:
    env:
      show-values: WHEN_AUTHORIZED   # 인증된 요청에만 값 노출
  endpoints:
    web:
      exposure:
        include: env,health,info

ALWAYS는 시크릿이 그대로 노출되므로 프로덕션에서는 쓰지 않는다. WHEN_AUTHORIZED는 Spring Security와 조합해 관리자 권한이 있는 경우에만 값을 보여준다.

10-3) 디버깅 플로우

"왜 이 값이 이렇게 들어갔지?" 상황의 순서.

/actuator/env/app.mail.host 호출
응답의 propertySources 배열 순서가 우선순위 순 (위가 이김)
activeValue가 최종 적용된 값
각 소스의 value + origin을 훑어서 어디서 덮어썼는지 추적

Actuator를 못 여는 환경이라면 기동 로그에 --debug 플래그로 상세 출력을 켠다. ConfigDataEnvironment가 로드한 모든 파일과 프로파일 해석 결과가 찍힌다.

11) 시크릿: configtree와 Vault

11-1) 환경변수는 그만 — configtree로

가장 기본적인 시크릿 전달 방식이 환경변수였지만, 이 방식은 보안상 여러 문제가 있다.

프로세스 목록(ps eef)이나 /proc/*/environ에서 노출될 수 있다
자식 프로세스에 그대로 상속된다
로그에 찍히는 사고가 빈번하다

Kubernetes의 Secret을 파일 마운트로 붙이고 configtree: 스킴으로 읽는 방식이 권장된다.

# K8s Deployment 발췌
volumeMounts:
  - name: app-secrets
    mountPath: /etc/secrets
    readOnly: true
volumes:
  - name: app-secrets
    secret:
      secretName: app-mail-secret

# application.yml
spring:
  config:
    import: configtree:/etc/secrets/

/etc/secrets/app.mail.password 파일이 마운트되면 Boot가 그 내용을 app.mail.password 속성으로 읽는다. 환경변수보다 누수 경로가 훨씬 적다.

11-2) Spring Cloud Vault

Vault를 쓰는 경우 spring-cloud-starter-vault-config를 추가하고 spring.config.import=vault://로 끌어올 수 있다.

spring:
  cloud:
    vault:
      uri: https://vault.internal:8200
      authentication: kubernetes
  config:
    import: vault://secret/app/mail

Vault에 저장된 secret/app/mail의 키들이 Boot 속성 소스로 등록된다. Renewal, lease 관리까지 Vault 클라이언트가 처리한다. 이 글의 주제를 벗어나므로 상세는 Spring Cloud Vault 문서로.

11-3) 암호화: Boot 기본은 없다

"yml에 비밀번호를 암호화해서 넣고 기동 시 복호화"는 Boot 표준 기능이 아니다. Jasypt(jasypt-spring-boot) 같은 외부 솔루션을 쓰거나, 애초에 Vault/configtree로 분리하는 쪽이 권장된다. yml 안의 암호화 문자열은 키 관리가 또 다른 문제를 만든다 — 암복호화 키를 어떻게 배포할 것인가가 원래 문제로 돌아간다.

12) 실무에서 이렇게 읽고 쓴다

모든 설정은 @ConfigurationProperties로. @Value는 @Scheduled처럼 어노테이션 속성에 박아야 하는 경우에만.
record + @ConfigurationPropertiesScan 조합을 기본으로. -parameters 컴파일 옵션이 켜져 있는지 한 번은 확인.
yml은 kebab-case, 환경변수는 SCREAMING_SNAKE로 팀 컨벤션 고정. 혼용이 디버깅 지옥을 만든다.
Duration, DataSize, Period는 타입으로 단위를 표현. long timeoutMillis 지양, Duration timeout 선호.
**@Validated + @NotBlank / @Min**으로 기동 시점 방어선을 세움. spring-boot-starter-validation 의존성 확인.
중첩 Properties는 부모 필드에 @Valid 붙이기. 빠뜨리면 검증이 조용히 스킵된다.
spring.config.import로 외부 파일 끌어올 때는 optional: 접두사를 기본. 반드시 있어야 하는 파일만 생략.
Boot 2.3 이하의 spring.profiles: prod 문법 금지. 2.4+의 spring.config.activate.on-profile로 전환.
시크릿은 환경변수 대신 configtree: 또는 Vault. K8s Secret은 파일 마운트가 기본.
설정 오작동 디버깅은 /actuator/env/{key} 엔드포인트 먼저. origin 필드가 출처를 정확히 찍어준다.
server.port=${PORT:8080} 같은 관용구는 placeholder + default 문법으로 통일. 운영자 오버라이드 포인트를 명확히.

13) 한 줄 정리

Spring Boot의 Externalized Configuration은 소스·바인딩·검증 세 축을 spring.config.import와 @ConfigurationProperties로 통합한 체계다. Boot 2.4 이후 Config Data API가 프로파일 문법과 외부 파일 로딩을 통째로 재정리했기 때문에 예전 관습(spring.profiles:, spring.config.additional-location)을 버리고 spring.config.activate.on-profile·spring.config.import: optional:...로 이전하는 게 실무 출발선이다. record + Relaxed Binding + @Validated까지 엮으면 기동 시점에 틀린 설정을 막아주는 타입 안전한 설정 파이프라인이 완성된다.

태그: Spring Boot, Externalized Configuration, @ConfigurationProperties, spring.config.import, Profile, Relaxed Binding, Duration, @Validated, configtree, Actuator

Spring Boot AutoConfiguration — @AutoConfiguration과 조건부 조립의 내부

dding-shark — Tue, 14 Apr 2026 22:05:18 +0900

Spring Boot AutoConfiguration — @AutoConfiguration과 조건부 조립의 내부

들어가며

spring-boot-starter-web을 의존성에 추가하고 main을 돌리면, 톰캣이 뜨고, DispatcherServlet이 등록되고, Jackson이 MessageConverter에 물리고, 정적 리소스가 매핑되고, 에러 페이지가 연결된다. application.yml에 spring.datasource.url만 넣으면 HikariCP 커넥션 풀과 DataSource, JdbcTemplate, DataSourceTransactionManager까지 조용히 조립된다. 어떤 클래스도 @Bean으로 직접 등록한 적이 없다. @SpringBootApplication 한 줄이 이걸 전부 해낸다.

그런데 이 "한 줄"의 내부는 @EnableAutoConfiguration → AutoConfigurationImportSelector → META-INF/spring/.../AutoConfiguration.imports 파일 → 조건부 필터 → 빈 등록으로 이어지는 정해진 절차다. 여기에 @ConditionalOnMissingBean이 깔려 있어 사용자가 빈을 직접 두면 기본값이 양보한다. 겉보기에는 마법이지만 뜯어보면 Spring Framework의 @Conditional과 @Import 메커니즘을 파일 하나와 우선순위 규칙으로 묶어낸 시스템이다. 5편에서 @Conditional의 뿌리를, 14편에서 DispatcherServlet과 WebMvcAutoConfiguration을 봤다면, 이번 글은 그 둘을 잇는 조립 파이프라인 자체를 다룬다.

이 주제에서 실무가 자주 막히는 지점은 다음 세 곳이다.

spring.factories에 자동구성을 등록했는데 Boot 3에서 잡히지 않는다 — Boot 2.7부터는 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 파일이 표준이고, Boot 3는 옛 키를 더 이상 읽지 않는다
사용자가 @Bean DataSource를 직접 정의했더니 Boot의 기본 DataSource가 사라졌다 — DataSourceAutoConfiguration이 @ConditionalOnMissingBean(DataSource.class)으로 양보하는 의도된 동작이다
--debug 로그의 "Negative matches"에 내가 기대한 자동구성이 박혀 있는데 이유가 해석이 안 된다 — CONDITIONS EVALUATION REPORT의 세 섹션(Positive / Negative / Unconditional)을 구분해서 읽어야 한다

이 글은 왜 → 상단 어노테이션 → Selector 흐름 → imports 파일 → @AutoConfiguration → 조건부 패밀리 → 순서 → 디버깅 → 실무 순으로, Spring Boot 3.x / Spring Framework 6.x / Java 17+ 기준으로 정리한다.

1) @SpringBootApplication 한 줄 아래에 뭐가 있나
2) AutoConfigurationImportSelector: 자동구성을 끌어오는 단일 진입점
3) AutoConfiguration.imports vs 옛 spring.factories
4) @AutoConfiguration 애너테이션과 proxyBeanMethods=false
5) 조건부 어노테이션 패밀리: 자동구성에서 쓰이는 여덟 가지
6) @ConditionalOnMissingBean: 자동구성 패턴의 핵심
7) AutoConfigureBefore/After와 순서 의존성
8) 조건 평가 디버깅: --debug와 Actuator /conditions
9) 자동구성 비활성화 방법
10) @EnableWebMvc 함정과 자동구성 해제
11) 테스트에서 자동구성 선별 로드
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) @SpringBootApplication 한 줄 아래에 뭐가 있나

@SpringBootApplication은 하나의 어노테이션처럼 보이지만 실제로는 세 개의 메타 어노테이션을 묶은 합성 어노테이션이다. 이 세 개가 각각 다른 역할을 하고, 그 중 @EnableAutoConfiguration이 자동구성 전체의 트리거다.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@SpringBootConfiguration           // = @Configuration + 감지용 마커
@EnableAutoConfiguration           // = @Import(AutoConfigurationImportSelector.class)
@ComponentScan(excludeFilters = { ... })
public @interface SpringBootApplication { ... }

세 어노테이션이 하는 일은 서로 독립적이다.

@SpringBootConfiguration: 사실상 @Configuration이다. 다만 Boot 전용 마커라 @SpringBootTest 같은 테스트 도구가 이 마커로 "앱의 메인 설정 클래스"를 자동으로 찾아낸다
@EnableAutoConfiguration: 자동구성 스캔의 진입점. 내부가 @Import(AutoConfigurationImportSelector.class)로 되어 있다
@ComponentScan: @SpringBootApplication이 붙은 클래스의 패키지를 루트로 삼아 @Component 계열을 스캔한다

1-1) @EnableAutoConfiguration 내부

@EnableAutoConfiguration을 직접 열어보면 다음과 같은 구조다.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@AutoConfigurationPackage
@Import(AutoConfigurationImportSelector.class)
public @interface EnableAutoConfiguration {
    String ENABLED_OVERRIDE_PROPERTY = "spring.boot.enableautoconfiguration";
    Class<?>[] exclude() default {};
    String[] excludeName() default {};
}

@Import(AutoConfigurationImportSelector.class): ImportSelector 구현체를 @Import로 등록하면 Spring은 그 selectImports() 메서드가 반환한 클래스 배열을 @Configuration처럼 취급해 추가 등록한다. 자동구성 로딩은 이 메커니즘을 쓴다
@AutoConfigurationPackage: @SpringBootApplication이 붙은 클래스의 패키지를 "자동구성 스캔의 루트"로 기억한다. Spring Data JPA의 @Entity 스캔 같은 후속 자동구성이 이 값을 참조한다

1-2) "자동"의 실체는 @Import 리턴 배열이다

오해하지 않기 위해 한 번 짚어둔다. 자동구성은 런타임에 동적으로 클래스를 생성하는 것이 아니다. Boot는 미리 빌드된 JAR 안에 자동구성 클래스들과 그 목록 파일을 묶어두고, AutoConfigurationImportSelector가 그 목록을 읽어 @Import의 반환 배열로 넘긴다. 그 뒤는 Spring의 표준 @Configuration 처리 흐름이다.

즉 자동구성이 하는 일은 "어떤 @Configuration을 추가로 @Import할지"를 파일 기반으로 결정하는 것뿐이다. 거기에 @ConditionalOnClass, @ConditionalOnMissingBean 같은 조건부 필터가 걸려 있어 쓸모없는 설정은 걸러진다.

2) AutoConfigurationImportSelector: 자동구성을 끌어오는 단일 진입점

AutoConfigurationImportSelector는 DeferredImportSelector를 구현한 클래스다. DeferredImportSelector는 이름 그대로 지연 import를 뜻한다. Spring은 일반 @Configuration을 먼저 다 처리하고 나서 마지막에 DeferredImportSelector를 돌린다. 이 순서가 자동구성 설계의 핵심이다 — 사용자 @Configuration이 빈을 등록한 뒤에 자동구성이 돌아야 @ConditionalOnMissingBean이 "사용자 정의가 있는지" 확인할 수 있기 때문이다.

2-1) selectImports의 네 단계

getAutoConfigurationEntry가 아래 네 단계를 호출한다.

getCandidateConfigurations: ImportCandidates.load(AutoConfiguration.class, classLoader) 호출. 클래스패스의 모든 JAR에서 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 파일을 찾아 한 줄씩 읽는다. 이 파일에 나열된 클래스 이름이 곧 자동구성 후보다
removeDuplicates + getExclusions: 중복 제거, 사용자가 exclude로 지정한 것 제거
filter: AutoConfigurationImportFilter 구현체들이 조건부 필터링을 수행한다. 대표적으로 OnClassCondition이 @ConditionalOnClass를 검사해 클래스패스에 없는 자동구성을 빠르게 제거한다
fireAutoConfigurationImportEvents: 필터링이 끝난 결과를 이벤트로 발행한다. 조건 평가 리포트를 만드는 리스너가 여기서 정보를 수집한다

2-2) 시퀀스 다이어그램

여기서 주목할 점은 두 단계의 필터링이다. filter() 단계에서 @ConditionalOnClass 같은 "클래스패스만 보면 되는" 조건은 일찍 걸러낸다. 그 뒤 실제 @Configuration으로 등록된 다음에 @ConditionalOnBean, @ConditionalOnMissingBean 같은 "다른 빈 정의를 봐야 하는" 조건이 평가된다. 이 분할이 자동구성 100개 이상을 조립하면서도 기동 시간을 유지하는 최적화다.

2-3) DeferredImportSelector라서 의미 있는 것

일반 ImportSelector였다면 사용자 @Configuration과 자동구성이 뒤섞여 처리된다. 이 경우 사용자 @Bean DataSource가 아직 등록되기 전에 자동구성의 @ConditionalOnMissingBean(DataSource.class)이 평가될 수 있고, 결과는 비결정적이다. DeferredImportSelector는 "모든 일반 @Configuration 처리 후"라는 순서 계약을 제공한다. 덕분에 자동구성은 사용자 설정 전체가 정착된 스냅샷 위에서 판단을 내릴 수 있다.

3) AutoConfiguration.imports vs 옛 spring.factories

자동구성 후보 목록이 어디서 오는가를 정확히 아는 게 Boot 버전 업그레이드에서 가장 큰 함정을 피하는 길이다.

3-1) Boot 2.7 이전: spring.factories 키 방식

Boot 2.6 이하에서는 META-INF/spring.factories의 특정 키에 자동구성 클래스를 나열했다.

# META-INF/spring.factories (Boot 2.6 이하)
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.MyAutoConfiguration,\
com.example.OtherAutoConfiguration

한 키에 콤마로 여러 값을 이어 붙이고, 줄 끝은 백슬래시로 이어야 한다. 이 파일은 여러 종류의 메타 등록(ApplicationListener, FailureAnalyzer, EnvironmentPostProcessor 등)을 한 곳에서 관리하는 만능 창고였다. 그런데 항목이 늘면서 "자동구성 클래스 하나 추가할 때마다 줄바꿈·이스케이프·콤마를 신경 써야 한다"는 불편이 쌓였다.

3-2) Boot 2.7+ / 3.x: .imports 한 줄 한 클래스

Boot 2.7에서 자동구성 전용 파일이 새로 도입됐고, Boot 3에서는 이 경로가 유일한 표준이 됐다.

# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.MyAutoConfiguration
com.example.OtherAutoConfiguration
# 주석도 지원됨

한 줄에 한 클래스 FQCN, 주석은 #. 이스케이프나 콤마가 필요 없다. 파일 이름이 바로 키라 편집이 단순하다.

3-3) 두 방식 비교

항목	spring.factories (구)	AutoConfiguration.imports (신)
경로	`META-INF/spring.factories`	`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
포맷	`key=cls1,cls2,\` 연쇄	한 줄에 한 FQCN
주석	Properties 주석	`#` 주석
Boot 2.7	유효 (호환)	유효 (권장)
Boot 3.x	자동구성 키 무시됨	필수
다른 용도	ApplicationListener 등 계속 유지	자동구성 전용

여기서 틀리기 쉽다. spring.factories 자체가 사라진 것은 아니다. ApplicationListener, EnvironmentPostProcessor, FailureAnalyzer 등은 Boot 3에서도 여전히 spring.factories를 쓴다. "자동구성 키만" Boot 3에서 버려졌다. 직접 만든 starter를 2.x에서 3.x로 올리면서 spring.factories의 EnableAutoConfiguration= 블록만 남겨두면 해당 자동구성이 통째로 로딩되지 않는다. 마이그레이션 가이드는 이 파일 분리를 첫 번째 체크 항목으로 언급한다.

3-4) 마이그레이션 체크리스트

# 구조 예시
src/main/resources/
├── META-INF/
│   ├── spring.factories                         # Listener, Processor 등은 유지
│   └── spring/
│       └── org.springframework.boot.autoconfigure.AutoConfiguration.imports

마이그레이션 시 해야 할 일은 간단하다. spring.factories의 EnableAutoConfiguration= 블록을 통째로 옮겨 .imports 파일로 만들되, 한 줄에 한 FQCN으로 정리하고, 이어붙임 \와 콤마를 제거한다. IDE 플러그인이 자동으로 변환해주기도 한다.

4) @AutoConfiguration 애너테이션과 proxyBeanMethods=false

Boot 2.7에서 @AutoConfiguration이 @Configuration과 별도 어노테이션으로 분리됐다. 이전에는 자동구성도 그냥 @Configuration으로 선언하고 그 위에 @ConditionalOnClass, @AutoConfigureAfter를 수동으로 쌓아야 했다. 지금은 전용 어노테이션이 이 패턴을 묶어준다.

4-1) 어노테이션 구조

// 개략화 — 실제 정의는 before/after가 메타의 value에 @AliasFor로 연결된다
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Configuration(proxyBeanMethods = false)
@AutoConfigureBefore
@AutoConfigureAfter
public @interface AutoConfiguration {
    @AliasFor(annotation = Configuration.class)
    String value() default "";

    Class<?>[] before() default {};
    String[] beforeName() default {};
    Class<?>[] after() default {};
    String[] afterName() default {};
}

@AutoConfigureBefore와 @AutoConfigureAfter가 메타로 달려 있고, @AutoConfiguration의 before/after 속성은 @AliasFor로 각 메타 어노테이션의 value에 연결된다. 즉 @AutoConfiguration(after = X.class) 한 줄이 실제로는 @AutoConfigureAfter(X.class)와 동일한 메타데이터를 주입하는 셈이다.

세 가지 요점이 있다.

@Configuration(proxyBeanMethods = false): @Configuration을 메타로 달고 있지만 프록시를 끈다. 일반 @Configuration은 CGLIB 프록시를 생성해 @Bean 메서드끼리의 참조를 싱글턴으로 유지하는데, 자동구성은 이런 교차 참조를 거의 쓰지 않으므로 프록시를 끄는 편이 기동 속도에 이득이다
before / after 속성: 예전에는 @AutoConfigureAfter 별도 어노테이션을 달아야 했던 것을, 이제는 @AutoConfiguration(after = X.class) 한 줄에 녹일 수 있다
Lite 모드로 동작: proxyBeanMethods = false인 설정 클래스는 "Lite @Configuration"으로 분류돼, CGLIB 생성 비용이 없고 final 클래스도 허용된다

4-2) proxyBeanMethods=false가 의미하는 것

일반 @Configuration에서 메서드 간 참조가 어떻게 동작하는지 떠올려보자.

@Configuration  // proxyBeanMethods = true (기본)
public class Normal {
    @Bean A a() { return new A(); }
    @Bean B b() { return new B(a()); }  // a()를 호출하지만 싱글턴 보장됨 (프록시가 가로챔)
}

Normal 클래스는 런타임에 CGLIB 서브클래스로 감싸져 a() 호출이 컨테이너 조회로 리다이렉트된다. 그래서 b() 안의 a()는 매번 새 인스턴스를 만들지 않고 같은 싱글턴을 돌려받는다.

자동구성에서는 이 패턴을 거의 쓰지 않는다. 빈끼리의 의존은 생성자 파라미터로 주입되는 게 일반적이다.

@AutoConfiguration  // proxyBeanMethods = false
public class MyAuto {
    @Bean A a() { return new A(); }
    @Bean B b(A a) { return new B(a); }  // 컨테이너가 a를 주입
}

이 경우 프록시가 불필요하고, CGLIB 서브클래스 생성 비용이 사라진다. 기동 시간 최적화가 일차 목적이고, AOT/네이티브 이미지에서도 유리하다.

4-3) 주의: @Bean 메서드 간 직접 호출 금지

@AutoConfiguration이나 @Configuration(proxyBeanMethods = false)에서 실수로 메서드 직접 호출을 쓰면 싱글턴 보장이 깨진다.

// 피하기: @Bean 메서드를 직접 호출
@AutoConfiguration
public class Risky {
    @Bean A a() { return new A(); }
    @Bean B b() { return new B(a()); }  // ← a()가 매번 new A()를 반환. 싱글턴 깨짐
}

// 선호: 생성자 주입
@AutoConfiguration
public class Safe {
    @Bean A a() { return new A(); }
    @Bean B b(A a) { return new B(a); }
}

proxyBeanMethods = false는 "메서드 호출을 가로채지 않겠다"는 선언이다. 그 전제를 지키려면 메서드 간 참조는 파라미터 주입으로 써야 한다.

5) 조건부 어노테이션 패밀리: 자동구성에서 쓰이는 여덟 가지

5편에서 @Conditional의 뿌리를 다뤘다. 이 섹션은 그 중 자동구성에서 특히 자주 쓰이는 여덟 가지를 자동구성 관점에서 다시 정리한다.

어노테이션	평가 대상	자동구성 용도
`@ConditionalOnClass`	클래스패스	라이브러리가 있어야만 동작 (`RedisTemplate`, `DataSource` 등)
`@ConditionalOnMissingClass`	클래스패스	특정 라이브러리가 없을 때 대체 구성
`@ConditionalOnBean`	이미 등록된 빈 정의	다른 자동구성이 등록한 빈에 이어 붙이기
`@ConditionalOnMissingBean`	이미 등록된 빈 정의	사용자 정의 우선 — 자동구성 패턴의 핵심
`@ConditionalOnProperty`	Environment	기능 토글, `matchIfMissing` 기본 `false`
`@ConditionalOnWebApplication`	컨텍스트 타입	`SERVLET` / `REACTIVE` / `ANY` 구분
`@ConditionalOnResource`	ResourceLoader	설정 파일 존재 여부
`@ConditionalOnJava`	JVM 버전	특정 Java 버전 이상에서만

5-1) 평가 순서와 단계 분리

앞서 §2에서 언급한 "두 단계 필터"를 다시 보자. AutoConfigurationImportFilter가 걸러내는 건 클래스패스만 보면 되는 조건(@ConditionalOnClass, @ConditionalOnWebApplication)이다. 이 단계에서 떨어진 자동구성은 @Configuration 등록조차 되지 않는다.

그 다음 @Configuration으로 등록된 자동구성에 대해 빈 정의를 봐야 하는 조건(@ConditionalOnBean, @ConditionalOnMissingBean)이 평가된다. 이 지점이 함정이다. 이 순서 때문에 @ConditionalOnBean(X.class)이 성공하려면 X를 등록하는 자동구성이 먼저 처리되어야 하고, 이게 §7 순서에서 다시 나올 핵심 이슈다.

5-2) @ConditionalOnProperty의 matchIfMissing

@ConditionalOnProperty(name = "x.y.z", havingValue = "true")는 프로퍼티가 없으면 기본적으로 조건 불성립(빈 미등록)이다. matchIfMissing = true를 명시해야 "프로퍼티 없을 때 기본으로 켠다"가 된다.

// 환경변수가 사라지면 조용히 기능 꺼짐
@ConditionalOnProperty(name = "app.feature.enabled", havingValue = "true")

// 기본 켜짐, 명시적으로 끄려면 "false" 설정
@ConditionalOnProperty(name = "app.feature.enabled", havingValue = "true", matchIfMissing = true)

Boot가 기본으로 켜 두고 싶은 기능(예: spring.jmx.enabled는 Boot 2.2+에서 기본 false, spring.aop.auto 기본 true)은 이 두 속성의 조합으로 방향을 잡는다. 내 자동구성을 만들 때도 디폴트 상태를 명확히 문서화하려면 matchIfMissing을 꼭 의식적으로 설정한다.

6) @ConditionalOnMissingBean: 자동구성 패턴의 핵심

자동구성 설계의 중심은 이 한 어노테이션이다. "사용자가 자기 빈을 등록했으면 내 기본값은 양보한다"는 규칙이 모든 자동구성에 박혀 있다.

6-1) DataSourceAutoConfiguration의 실제 패턴

Boot 3의 DataSourceAutoConfiguration 내부 한 조각을 개략화해서 보자.

@AutoConfiguration
@ConditionalOnClass({DataSource.class, EmbeddedDatabaseType.class})
public class DataSourceAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @Conditional(PooledDataSourceCondition.class)
    @ConditionalOnMissingBean({DataSource.class, XADataSource.class})  // ← 핵심
    @Import({DataSourceConfiguration.Hikari.class, ...})
    protected static class PooledDataSourceConfiguration { ... }
}

@ConditionalOnMissingBean({DataSource.class, XADataSource.class}) 한 줄이 전체 방향을 결정한다. 사용자 @Configuration에 @Bean DataSource가 없을 때만 Boot가 HikariCP 기반 DataSource를 만들고, 사용자가 직접 정의하면 이 블록 전체가 건너뛰어진다.

6-2) 사용자 입장에서의 동작 시나리오

세 가지 시나리오로 나뉜다.

시나리오 A: 사용자가 @Bean DataSource를 두지 않음 → Boot가 spring.datasource.url을 읽어 HikariDataSource를 생성해 등록
시나리오 B: 사용자가 @Bean public DataSource myDs() { ... }를 정의 → Boot의 DataSourceAutoConfiguration 내부 분기가 통째로 스킵됨. 사용자 빈만 존재
시나리오 C: 사용자가 두 개의 @Bean DataSource를 정의 → 이건 @ConditionalOnMissingBean의 문제가 아니라 일반 빈 충돌. @Primary나 이름 지정으로 해결

시나리오 B에서 "Boot가 조용히 꺼진다"가 포인트다. 에러도 경고도 없다. 이걸 의도한 동작이라는 점을 모르면 "Boot가 HikariDataSource를 안 쓴다"는 버그 리포트처럼 보일 수 있다.

6-3) 자동구성 밖에서 쓰면 비결정적

5편에서도 짚었지만 다시 강조한다. @ConditionalOnMissingBean은 자동구성 클래스에서만 안전하게 동작한다. 사용자 @Configuration에서 쓰면 같은 레벨의 사용자 @Configuration 간 처리 순서가 보장되지 않기 때문에 "오늘은 되고 내일은 안 되는" 버그의 근원이 된다.

여기서 자주 걸린다. 내 앱 코드 안에서 "사용자가 안 두면 기본값"을 구현하고 싶다면 방법은 두 가지다. 하나는 자동구성으로 승격해 AutoConfiguration.imports에 등록하는 것, 다른 하나는 @ConditionalOnMissingBean 대신 ObjectProvider나 기본 인스턴스 생성자 주입으로 바꾸는 것이다.

// 피하기: 사용자 @Configuration에서 @ConditionalOnMissingBean
@Configuration
public class MyConfig {
    @Bean
    @ConditionalOnMissingBean(Clock.class)  // ← 순서 비결정적
    public Clock clock() { return Clock.systemUTC(); }
}

// 선호: 기본값 주입 패턴
@Configuration
public class MyConfig {
    @Bean
    public MyService myService(ObjectProvider<Clock> clockProvider) {
        Clock clock = clockProvider.getIfAvailable(Clock::systemUTC);
        return new MyService(clock);
    }
}

ObjectProvider는 해당 타입 빈이 없으면 getIfAvailable의 폴백을 돌려준다. 순서 의존성이 없고, 컨텍스트 조립이 끝난 뒤에 결정되므로 안전하다.

7) AutoConfigureBefore/After와 순서 의존성

자동구성 여러 개가 얽힐 때 누가 먼저 처리되는지가 문제로 돌아온다. @ConditionalOnBean(X.class)이 통과하려면 X를 등록하는 자동구성이 먼저 처리되어야 한다.

7-1) 세 가지 순서 제어 수단

수단	용도	예시
`@AutoConfigureBefore`	대상 자동구성보다 먼저 처리	`@AutoConfigureBefore(WebMvcAutoConfiguration.class)`
`@AutoConfigureAfter`	대상 자동구성 뒤에 처리	`@AutoConfigureAfter(DataSourceAutoConfiguration.class)`
`@AutoConfigureOrder`	Boot 내부 순서 상수	`@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 10)`

@AutoConfiguration으로 선언하면 before/after 속성으로 직접 지정할 수 있어 어노테이션을 겹겹이 쌓을 필요가 없다.

@AutoConfiguration(after = DataSourceAutoConfiguration.class)
@ConditionalOnBean(DataSource.class)
public class MyJdbcAutoConfiguration {
    @Bean
    public MyJdbcHelper myJdbcHelper(DataSource ds) { ... }
}

7-2) 왜 순서가 필요한가

MyJdbcAutoConfiguration이 @ConditionalOnBean(DataSource.class)을 쓴다면, DataSourceAutoConfiguration이 먼저 돌면서 DataSource 빈을 등록해야 조건이 통과한다. @AutoConfigureAfter를 안 적으면 어느 쪽이 먼저 처리될지 보장이 없어서, 내 자동구성이 "DataSource가 안 보인다"며 조용히 꺼져버릴 수 있다.

주의할 점이 하나 있다. 같은 자동구성 안에서 정의된 빈끼리는 순서가 자동으로 맞춰지지만, 다른 자동구성 간에는 명시가 필요하다. 내 starter가 제공하는 자동구성이 Boot의 공식 자동구성 뒤에 와야 하는 경우가 대부분이라 @AutoConfigureAfter 선언은 거의 반사적으로 들어간다.

7-3) 순서는 빈 주입 순서가 아니다

@AutoConfigureAfter가 보장하는 건 자동구성 클래스가 처리되는 순서지, 빈이 생성되는 순서가 아니다. 빈 생성 순서는 의존 그래프로 결정된다. 이 둘을 혼동하면 "@AutoConfigureAfter를 붙였는데도 내 빈이 다른 빈보다 먼저 생성된다"는 오해가 생긴다. 빈 생성 순서를 제어하려면 생성자 주입으로 의존을 명시하거나 @DependsOn을 쓴다.

8) 조건 평가 디버깅: --debug와 Actuator /conditions

자동구성이 기대대로 동작하지 않을 때 가장 먼저 켜야 할 것이 CONDITIONS EVALUATION REPORT다.

8-1) --debug 플래그

JVM 옵션 -Ddebug=true 또는 명령줄 인자 --debug를 주고 앱을 띄우면, 기동 로그 끝에 긴 리포트가 찍힌다. 로그 레벨을 다 올리는 게 아니라 조건 평가 정보만 덤프한다.

java -jar myapp.jar --debug
# 또는
java -Ddebug=true -jar myapp.jar

리포트는 세 섹션으로 나뉜다.

Positive matches: 조건을 모두 통과해 등록된 자동구성 + 어떤 조건으로 통과했는지
Negative matches: 조건에서 탈락한 자동구성 + 어느 조건에서 왜 탈락했는지
Exclusions / Unconditional classes: 사용자가 exclude로 지정한 것, 조건 없이 늘 적용되는 것

8-2) 리포트 해석 예

DataSourceAutoConfiguration이 Positive에 있는 경우의 전형적 출력이다.

DataSourceAutoConfiguration matched:
  - @ConditionalOnClass found required classes
    'javax.sql.DataSource', 'org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType'
    (OnClassCondition)

DataSourceAutoConfiguration.PooledDataSourceConfiguration matched:
  - AnyNestedCondition on DataSourceAutoConfiguration.PooledDataSourceCondition
  - @ConditionalOnMissingBean (types: javax.sql.DataSource,javax.sql.XADataSource;
    SearchStrategy: all) did not find any beans (OnBeanCondition)

같은 자동구성이 Negative에 나오는 경우는 이렇다.

RedisAutoConfiguration:
  Did not match:
    - @ConditionalOnClass did not find required class
      'org.springframework.data.redis.connection.RedisConnectionFactory'
      (OnClassCondition)

**"did not find required class"**는 클래스패스에 라이브러리가 없다는 뜻이고, **"found ... beans"**는 사용자가 이미 빈을 등록했다는 뜻이다. 이 두 문구만 읽어도 자동구성이 꺼진 이유의 90%가 해결된다.

8-3) Actuator /actuator/conditions

기동 중인 앱의 조건 평가를 런타임에 JSON으로 조회할 수 있다. spring-boot-starter-actuator를 추가하고 management.endpoints.web.exposure.include=conditions를 켜면 /actuator/conditions로 같은 정보가 나온다.

curl http://localhost:8080/actuator/conditions | jq .

로그를 뒤지는 것보다 빠르고, 운영 환경에서 "이 배포본이 어떤 자동구성을 켰는지" 확인할 때 유용하다. 민감 정보는 아니지만 내부 구조를 드러내므로 외부 노출은 피하는 게 일반적이다.

9) 자동구성 비활성화 방법

의도적으로 특정 자동구성을 끄고 싶은 경우가 있다. 프로퍼티 바인딩이 다른 DB를 쓰고 있는데 DataSourceAutoConfiguration이 기동 시 에러를 내거나, 보안 자동구성이 테스트에서 방해가 되는 식이다.

9-1) 두 가지 방법

방법 A: @SpringBootApplication(exclude = ...)

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApp { ... }

코드로 명시. 해당 클래스를 import해야 하므로 클래스패스에 실제로 있는 자동구성에만 쓴다.

방법 B: application.yml의 spring.autoconfigure.exclude

spring:
  autoconfigure:
    exclude:
      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
      - org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration

문자열이므로 클래스패스에 없어도 지정 가능. 환경별로 껐다 켰다 할 수 있어 운영에서 더 유연하다.

9-2) 비활성화는 최후 수단

자동구성을 끄기 전에 프로퍼티로 기능을 끌 수 있는지 먼저 확인한다. 대부분의 자동구성은 xxx.enabled=false 같은 스위치를 제공한다.

spring:
  jmx:
    enabled: false
  sql:
    init:
      mode: never
management:
  endpoint:
    shutdown:
      enabled: false

프로퍼티 스위치가 있는데도 exclude로 끊어버리면 자동구성이 제공하는 다른 필요한 빈까지 사라진다. 자동구성 하나는 보통 여러 빈을 같이 등록하므로, 필요한 건 남기고 필요 없는 것만 끄는 프로퍼티 방식이 안전하다.

10) @EnableWebMvc 함정과 자동구성 해제

14편에서 이미 짚은 주제지만 자동구성 관점에서 한 번 더 정리한다. 이 함정은 자동구성 조건부 설계의 대표 사례다.

10-1) WebMvcAutoConfiguration의 게이트

WebMvcAutoConfiguration은 다음 조건을 건다.

@AutoConfiguration(after = { DispatcherServletAutoConfiguration.class, ... })
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurationSupport.class })
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class)  // ← 이 줄
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 10)
public class WebMvcAutoConfiguration { ... }

주목할 건 @ConditionalOnMissingBean(WebMvcConfigurationSupport.class). WebMvcConfigurationSupport 타입 빈이 이미 있으면 이 자동구성이 통째로 꺼진다.

10-2) @EnableWebMvc의 내부

사용자가 무심코 @EnableWebMvc를 붙이면 내부에서 다음이 일어난다.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Import(DelegatingWebMvcConfiguration.class)
public @interface EnableWebMvc { }

@EnableWebMvc는 DelegatingWebMvcConfiguration을 import하고, 이 클래스는 WebMvcConfigurationSupport를 상속한 서브클래스다. 즉 @EnableWebMvc를 붙이면 컨텍스트에 WebMvcConfigurationSupport 빈이 등록되고, 위에서 본 조건이 깨져 WebMvcAutoConfiguration이 전면 해제된다.

그 결과로 사라지는 것은 적지 않다.

Jackson/JSON MessageConverter 자동 등록
정적 리소스 매핑 (/static/**, /public/**)
DefaultErrorAttributes와 기본 에러 페이지
ContentNegotiationManager 기본 구성
WebMvcProperties 바인딩

10-3) 함정 회피

MVC 설정을 커스터마이즈하고 싶을 때 @EnableWebMvc를 쓰면 안 된다. 대신 WebMvcConfigurer 빈을 추가해 자동구성 위에 얹는다.

// 피하기: @EnableWebMvc로 자동구성 통째 해제
@Configuration
@EnableWebMvc
public class BadMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new MyInterceptor());
    }
}

// 선호: @EnableWebMvc 제거, Configurer만
@Configuration
public class GoodMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new MyInterceptor());
    }
}

후자가 Boot의 WebMvcAutoConfiguration이 제공하는 모든 기본값을 유지한 채 인터셉터만 추가한다. 이 패턴이 Boot 자동구성을 확장하는 공식 방식이다 — Configurer 빈을 등록해 얹는다. WebSecurityCustomizer, RestTemplateCustomizer, JpaVendorAdapter 등도 같은 철학이다.

11) 테스트에서 자동구성 선별 로드

전체 앱 컨텍스트(@SpringBootTest)는 무겁다. 자동구성 몇 개만 로드해서 테스트하고 싶을 때가 있다.

11-1) @ImportAutoConfiguration

@SpringJUnitConfig
@ImportAutoConfiguration({
    DataSourceAutoConfiguration.class,
    JdbcTemplateAutoConfiguration.class
})
class JdbcSliceTest {
    @Autowired JdbcTemplate jdbcTemplate;
    // ...
}

지정한 자동구성만 로드한다. AutoConfiguration.imports 전체를 읽지 않고, 명시 리스트만 처리한다. 슬라이스 테스트가 빠른 이유다.

11-2) Boot 슬라이스 테스트 어노테이션

Boot가 제공하는 슬라이스 테스트는 내부적으로 @ImportAutoConfiguration을 미리 세팅해둔 합성 어노테이션이다.

어노테이션	로드하는 자동구성 (요지)
`@WebMvcTest`	`WebMvcAutoConfiguration`, `WebFluxAutoConfiguration`, `JacksonAutoConfiguration`, `HttpMessageConvertersAutoConfiguration`, `ValidationAutoConfiguration` 등
`@DataJpaTest`	`DataSourceAutoConfiguration`, `HibernateJpaAutoConfiguration` 등
`@JdbcTest`	`DataSourceAutoConfiguration`, `JdbcTemplateAutoConfiguration`
`@JsonTest`	`JacksonAutoConfiguration`, `GsonAutoConfiguration`
`@RestClientTest`	`RestTemplateAutoConfiguration`, `JacksonAutoConfiguration`

각각 필요한 자동구성만 선별 로드하고, 나머지는 spring.autoconfigure.exclude 상당의 처리로 빼놓는다. 슬라이스 테스트가 @SpringBootTest보다 훨씬 빠른 이유가 이 선별 로딩이다.

11-3) 내 starter 테스트에서의 패턴

커스텀 starter를 개발 중이라면 ApplicationContextRunner를 쓴다. 자동구성 조건을 단위 테스트처럼 확인할 수 있다.

@Test
void dataSource가_없으면_자동구성이_꺼진다() {
    new ApplicationContextRunner()
        .withConfiguration(AutoConfigurations.of(MyJdbcAutoConfiguration.class))
        .run(context -> {
            assertThat(context).doesNotHaveBean(MyJdbcHelper.class);
        });
}

@Test
void dataSource가_있으면_helper가_등록된다() {
    new ApplicationContextRunner()
        .withConfiguration(AutoConfigurations.of(
            DataSourceAutoConfiguration.class,
            MyJdbcAutoConfiguration.class))
        .withPropertyValues("spring.datasource.url=jdbc:h2:mem:test")
        .run(context -> {
            assertThat(context).hasSingleBean(MyJdbcHelper.class);
        });
}

ApplicationContextRunner는 매 테스트마다 가벼운 컨텍스트를 새로 띄우고 닫는다. 자동구성의 조건 분기를 하나씩 검증하기에 가장 적합한 도구다.

12) 실무에서 이렇게 읽고 쓴다

기동 시 자동구성 의심이 들면 --debug부터 붙인다. Positive/Negative 섹션의 "did not find required class" / "found beans" 문구 두 개로 80% 원인이 해결된다
Boot 버전 업그레이드(특히 2.x → 3.x)에서 자동구성이 안 잡히면 spring.factories의 EnableAutoConfiguration= 블록을 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports로 옮긴다. 나머지 키(ApplicationListener, FailureAnalyzer 등)는 그대로 둔다
내 자동구성은 @AutoConfiguration(after = ...)으로 순서를 명시한다. @ConditionalOnBean을 쓰는 순간 after 선언이 반사적으로 필요하다
사용자 앱 코드에서는 @ConditionalOnMissingBean을 쓰지 않는다. 필요하면 자동구성으로 승격하거나, ObjectProvider.getIfAvailable로 대체한다
자동구성 커스터마이즈는 WebMvcConfigurer, WebSecurityCustomizer, RestTemplateCustomizer 같은 Configurer 빈으로 얹는다. @EnableWebMvc, @EnableWebSecurity 같은 스위치는 자동구성을 통째로 해제한다
자동구성을 끄고 싶으면 xxx.enabled=false 프로퍼티가 있는지 먼저 확인한다. 없을 때만 spring.autoconfigure.exclude로 간다
운영 중 조건 평가가 궁금하면 Actuator /actuator/conditions. 같은 정보가 JSON으로 나온다
starter를 개발한다면 ApplicationContextRunner로 조건 분기를 단위 테스트한다. "있을 때 / 없을 때"를 한 파일에서 확인하면 리뷰가 쉽다
@AutoConfiguration의 proxyBeanMethods = false를 기억한다. @Bean 메서드끼리 직접 호출하면 싱글턴이 깨진다. 생성자 파라미터 주입을 쓴다
@ConditionalOnProperty의 matchIfMissing을 반드시 의식한다. 기본 false라 프로퍼티가 사라지면 기능이 조용히 꺼진다. 기본 켜짐을 원하면 true 명시

13) 한 줄 정리

Boot 자동구성은 AutoConfiguration.imports 파일의 FQCN 목록을 AutoConfigurationImportSelector가 @Import로 주입하고, 그 위에 @ConditionalOnMissingBean으로 사용자 정의를 우선시하는 조립 파이프라인이다. 마법이 아니라 @Conditional + @Import + 정해진 순서 계약(DeferredImportSelector, @AutoConfigureAfter)의 조합으로 돌아간다. --debug의 CONDITIONS EVALUATION REPORT 두 줄이 자동구성 장애의 90%를 설명하므로 로그부터 읽는 습관이 가장 큰 무기다.

태그: spring-boot, autoconfiguration, conditional-on-missing-bean, import-selector, auto-configuration-imports, enable-auto-configuration, proxy-bean-methods, spring-boot-3, starter, conditions-evaluation-report

Spring Security Testing — @WithMockUser·MockMvc·Reactive 테스트 전략

dding-shark — Tue, 14 Apr 2026 22:04:45 +0900

Spring Security Testing — @WithMockUser·MockMvc·Reactive 테스트 전략

들어가며

Spring Security를 써본 사람은 인증·인가를 한 번쯤 붙여본다. 그런데 그걸 테스트로 덮는 순간 두 번째 벽이 생긴다. 로컬에서 브라우저로는 멀쩡히 로그인되는 컨트롤러가 @WebMvcTest에서는 401이나 403으로 돌아오고, POST 요청은 전부 CSRF로 튕기고, @PreAuthorize를 단위 테스트로 덮었는데 권한 검증이 아예 돌지 않는다. 테스트만 통과하면 배포되는 환경에서는 이게 그대로 "가짜 안전망"이 된다.

Spring Security 6.x / Spring Boot 3.x / Spring Test 6.x 기준으로 테스트에서 막히는 지점은 거의 정해져 있다. @WithMockUser와 @WithUserDetails의 차이, MockMvc에 .with(csrf())를 빼먹었을 때의 403, @InjectMocks 단위 테스트에서 @PreAuthorize가 통째로 무력화되는 상황, 그리고 roles와 authorities 옵션의 접두사 차이까지. 한 번 정리해두면 다시 같은 실수를 하지 않는다.

POST 테스트가 403인데 CSRF 토큰을 까먹었다 — .with(csrf())가 빠진 신호다
@WithMockUser를 붙였는데 UserDetailsService가 안 불린다 — 그건 @WithUserDetails가 할 일이다
단위 테스트로 @PreAuthorize를 검증하려다 무력화를 몰랐다 — Spring 컨텍스트 없이는 AOP 프록시가 없다
@WithMockUser(roles="ADMIN")가 hasAuthority("ADMIN")은 실패시킨다 — roles는 ROLE_ 접두사가 붙지만 authorities는 안 붙는다

이 글은 왜 → 어노테이션 내부 → MockMvc 포스트프로세서 → 메서드 시큐리티 → Reactive → 실무 순으로 정리한다.

1) 왜 Security Testing은 따로 배워야 하나
2) @WithMockUser 내부: TestSecurityContextHolder
3) @WithAnonymousUser, @WithUserDetails, 커스텀 @WithSecurityContext
4) SecurityMockMvcRequestPostProcessors 총정리
5) csrf() 필수: POST/PUT/DELETE 테스트 함정
6) formLogin(), logout(), authenticated() matcher
7) @WebMvcTest vs @SpringBootTest + @AutoConfigureMockMvc
8) Method Security 테스트: AOP 프록시 조건
9) JWT / OAuth2 mock: jwt().claim().authorities()
10) WebFlux: WebTestClient + mockUser / mockJwt
11) 실무에서 이렇게 읽고 쓴다
12) 한 줄 정리

1) 왜 Security Testing은 따로 배워야 하나

Spring Security를 붙인 애플리케이션은 컨트롤러에 도달하기 전에 필터 체인이 먼저 움직인다. 인증 여부 확인, CSRF 검증, 권한 평가, 세션 관리가 전부 필터 단계에서 끝난다. 이 말은 컨트롤러 단위 테스트에서 필터 체인이 빠져 있으면 "보안 없는 컨트롤러"를 테스트하는 셈이 된다는 뜻이다. 반대로 필터 체인이 전부 배치되면, 이번엔 테스트에서 인증을 어떻게 주입할 것인가라는 문제가 생긴다.

1-1) 세 가지 테스트 축

Spring Security의 테스트 지원은 크게 세 축이다. 이 셋을 섞어 쓰는 게 실무 패턴이다.

축	도구	용도
컨텍스트 주입	`@WithMockUser`, `@WithUserDetails`, `@WithSecurityContext`	테스트 메서드 실행 전에 `SecurityContext`를 선제 주입
요청별 주입	`SecurityMockMvcRequestPostProcessors` (`user()`, `jwt()`, `csrf()` 등)	`MockMvc.perform(...).with(...)` 체인으로 요청마다 다른 인증
응답 검증	`SecurityMockMvcResultMatchers` (`authenticated()`, `unauthenticated()`)	로그인 결과·세션 상태 확인

어노테이션 기반은 테스트 메서드 전체에 영향을 주고, 포스트프로세서 기반은 한 요청에만 적용된다. 같은 테스트 클래스 안에서 섞어 쓸 수 있다.

1-2) `spring-security-test` 의존성

이 모든 API는 org.springframework.security:spring-security-test 아티팩트에 들어 있다. spring-boot-starter-test에는 자동 포함되지 않으므로 별도로 추가해야 한다.

// build.gradle.kts
testImplementation("org.springframework.security:spring-security-test")

이게 없으면 @WithMockUser 어노테이션은 존재하지만 TestExecutionListener가 등록되지 않아 아무 일도 안 일어난다. 여기서 한 번 막히면 로그에도 특별한 힌트가 없어서 오래 헤맨다.

2) @WithMockUser 내부: TestSecurityContextHolder

@WithMockUser는 Spring Security Test의 대표 어노테이션이다. 메서드나 클래스 위에 붙이면 테스트 실행 직전에 가짜 Authentication이 SecurityContext에 주입된다.

@Test
@WithMockUser
void 기본_사용자로_실행된다() {
    // username=user, password=password, roles=USER
    Authentication auth = SecurityContextHolder.getContext().getAuthentication();
    assertThat(auth.getName()).isEqualTo("user");
}

기본값은 username="user", password="password", roles={"USER"}다. 옵션으로 전부 바꿀 수 있다.

@Test
@WithMockUser(username = "alice", roles = {"ADMIN", "USER"})
void 관리자_테스트() { ... }

@Test
@WithMockUser(authorities = {"SCOPE_read", "SCOPE_write"})
void OAuth_스코프_테스트() { ... }

2-1) 동작 원리

내부는 단순하다. WithSecurityContextTestExecutionListener라는 JUnit 확장이 테스트 메서드 실행 전에 @WithMockUser를 읽어서 UsernamePasswordAuthenticationToken을 만든 뒤 TestSecurityContextHolder에 넣는다. TestSecurityContextHolder는 테스트 범위용 SecurityContextHolder 대체물이고, 각 테스트 메서드 시작 시점에 값이 전역 SecurityContextHolder로 복사된다.

테스트 격리는 여기서 보장된다. 각 테스트 메서드 끝날 때마다 컨텍스트가 리셋되므로 테스트 간 인증 상태가 새어나가지 않는다.

2-2) `roles` vs `authorities`의 `ROLE_` 접두사

여기서 틀리기 쉽다. 두 옵션은 이름만 다른 게 아니다.

옵션	`ROLE_` 접두사	예시 입력	실제 권한
`roles = {"ADMIN"}`	자동으로 붙음	`"ADMIN"`	`ROLE_ADMIN`
`authorities = {"ADMIN"}`	안 붙음	`"ADMIN"`	`ADMIN`

이게 왜 중요하냐면, @PreAuthorize("hasRole('ADMIN')")과 @PreAuthorize("hasAuthority('ADMIN')")이 완전히 다른 조건을 검사하기 때문이다. hasRole('ADMIN')은 내부에서 ROLE_ADMIN을 찾고, hasAuthority('ADMIN')은 접두사 없이 ADMIN을 찾는다.

@Test
@WithMockUser(roles = "ADMIN") // 내부적으로 ROLE_ADMIN
void hasRole은_통과() {
    // @PreAuthorize("hasRole('ADMIN')") 통과
    // @PreAuthorize("hasAuthority('ADMIN')") 실패 — ROLE_ADMIN != ADMIN
}

@Test
@WithMockUser(authorities = "ADMIN")
void hasAuthority만_통과() {
    // @PreAuthorize("hasAuthority('ADMIN')") 통과
    // @PreAuthorize("hasRole('ADMIN')") 실패 — 접두사 ROLE_ 부재
}

OAuth2 SCOPE_* 패턴을 쓸 때는 반드시 authorities를 쓴다. roles = "SCOPE_read"로 주면 ROLE_SCOPE_read가 되어 의미가 망가진다.

2-3) 어디에 붙일 수 있나

테스트 메서드 위: 해당 메서드만 적용
테스트 클래스 위: 모든 메서드에 기본 적용, 메서드별로 재정의 가능
메타 어노테이션: @WithMockUser를 감싼 커스텀 어노테이션 가능 (@WithAdmin 같은 축약형)

3) @WithAnonymousUser, @WithUserDetails, 커스텀 @WithSecurityContext

@WithMockUser 하나로 대부분 커버되지만, 상황에 따라 세 가지 형제가 필요하다.

3-1) `@WithAnonymousUser`

익명 사용자 상태를 강제한다. 클래스 위에 @WithMockUser가 걸려 있을 때 특정 메서드만 익명으로 테스트하고 싶을 때 쓴다.

@SpringBootTest
@WithMockUser(roles = "USER")
class OrderControllerTest {

    @Test
    void 로그인_사용자는_주문조회() { ... }

    @Test
    @WithAnonymousUser
    void 익명사용자는_401() { ... }
}

3-2) `@WithUserDetails`

여기가 @WithMockUser와 자주 혼동되는 지점이다. @WithMockUser는 아무 빈도 건드리지 않고 토큰을 만들어 박는다. UserDetailsService는 호출되지 않는다. 반면 @WithUserDetails는 스프링 컨텍스트에서 UserDetailsService 빈을 찾아 loadUserByUsername(value)를 실제로 호출한다.

@Test
@WithUserDetails("admin@example.com") // 실제 DB 또는 InMemory 조회
void 실제_사용자_데이터로_테스트() { ... }

실제 DB 기반 통합 테스트나, UserDetails 커스텀 구현체의 필드(예: tenantId, organizationId)를 써야 하는 인가 로직을 검증할 때 쓴다.

어노테이션	`UserDetailsService` 호출	용도
`@WithMockUser`	안 함	단순한 권한 조합만 필요한 테스트
`@WithUserDetails`	함	실제 사용자 데이터·커스텀 `UserDetails` 필드 의존 로직

컨텍스트가 없는 컨트롤러 단위 테스트(@WebMvcTest 없이 Mockito만)에서는 @WithUserDetails는 동작하지 않는다. UserDetailsService 빈이 없기 때문이다.

3-3) 커스텀 `@WithSecurityContext`

Authentication 타입 자체를 바꾸고 싶을 때 쓴다. 예를 들어 JWT 토큰 기반 커스텀 Principal을 주입하려면 팩토리를 만들어야 한다.

@Retention(RetentionPolicy.RUNTIME)
@WithSecurityContext(factory = WithMockJwtSecurityContextFactory.class)
public @interface WithMockJwt {
    String subject() default "user";
    String[] scopes() default {};
}

public class WithMockJwtSecurityContextFactory
        implements WithSecurityContextFactory<WithMockJwt> {

    @Override
    public SecurityContext createSecurityContext(WithMockJwt annotation) {
        Jwt jwt = Jwt.withTokenValue("token")
                .header("alg", "none")
                .claim("sub", annotation.subject())
                .build();
        var authorities = Arrays.stream(annotation.scopes())
                .map(s -> new SimpleGrantedAuthority("SCOPE_" + s))
                .toList();
        var auth = new JwtAuthenticationToken(jwt, authorities);
        SecurityContext ctx = SecurityContextHolder.createEmptyContext();
        ctx.setAuthentication(auth);
        return ctx;
    }
}

@Test
@WithMockJwt(subject = "alice", scopes = {"read", "write"})
void JWT_스코프_테스트() { ... }

팀 내에서 같은 패턴이 10개 이상 반복되면 커스텀 어노테이션으로 빼는 게 테스트 가독성이 훨씬 좋아진다.

4) SecurityMockMvcRequestPostProcessors 총정리

어노테이션 기반이 아니라 요청별로 인증 상태를 바꾸고 싶을 때는 MockMvc의 .with(...) 체인을 쓴다. 정적 import로 SecurityMockMvcRequestPostProcessors.*를 가져오면 코드가 짧아진다.

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*;

mockMvc.perform(post("/api/orders")
        .with(user("admin").roles("ADMIN"))
        .with(csrf())
        .contentType(MediaType.APPLICATION_JSON)
        .content("{\"itemId\":1}"))
    .andExpect(status().isCreated());

4-1) 주요 포스트프로세서 매트릭스

메서드	용도	주요 옵션
`user("name")`	임시 사용자 주입	`.roles(...)`, `.authorities(...)`, `.password(...)`
`anonymous()`	익명 사용자	—
`authentication(auth)`	커스텀 `Authentication` 직접 주입	—
`httpBasic("u", "p")`	HTTP Basic 헤더 추가	—
`csrf()`	CSRF 토큰 자동 생성·첨부	`.asHeader()` (헤더로 보내기)
`jwt()`	`JwtAuthenticationToken` mock	`.jwt(j -> j.claim("sub", ...).authorities(...))`
`opaqueToken()`	Opaque 토큰 인증 mock	`.attributes(a -> a.put("sub", ...))`
`oauth2Login()`	OAuth2 Client 로그인 상태 mock	`.authorities(...)`, `.attributes(...)`
`oauth2Client()`	`OAuth2AuthorizedClient` 주입	`.principalName(...)`, `.accessToken(...)`

4-2) `user()` vs `@WithMockUser`

둘은 거의 같은 일을 한다. 차이는 적용 범위다.

// 어노테이션: 메서드 전체
@Test
@WithMockUser(roles = "ADMIN")
void admin_전용() {
    mockMvc.perform(get("/admin/dashboard"))
        .andExpect(status().isOk());
}

// 포스트프로세서: 이 요청만
@Test
void 한_테스트_안에_역할_두_번() throws Exception {
    mockMvc.perform(get("/me").with(user("alice").roles("USER")))
        .andExpect(status().isOk());
    mockMvc.perform(get("/admin").with(user("bob").roles("ADMIN")))
        .andExpect(status().isOk());
}

한 테스트 메서드 안에서 여러 사용자로 여러 요청을 날려야 하면 포스트프로세서가 답이다.

4-3) `authentication(auth)`로 완전 커스텀 주입

특수한 Authentication 타입(멀티테넌트 토큰, 커스텀 Principal 등)을 넣을 때 쓴다.

var tenantAuth = new TenantAwareAuthenticationToken(
    "alice", "tenant-42", List.of(new SimpleGrantedAuthority("ROLE_USER")));

mockMvc.perform(get("/api/me").with(authentication(tenantAuth)))
    .andExpect(status().isOk());

5) csrf() 필수: POST/PUT/DELETE 테스트 함정

이게 실무에서 가장 자주 마주치는 함정이다. Spring Security는 기본 설정에서 상태 변경 HTTP 메서드(POST, PUT, DELETE, PATCH)에 CSRF 토큰을 요구한다. 테스트에서도 똑같이 요구한다.

5-1) 잘못된 코드와 증상

피해야 할 패턴:

@Test
@WithMockUser(roles = "USER")
void 주문_생성() throws Exception {
    mockMvc.perform(post("/api/orders")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"itemId\":1}"))
        .andExpect(status().isCreated()); // 실패: 403 Forbidden
}

이 테스트는 403 Forbidden으로 실패한다. 로그를 보면 Invalid CSRF token found for .... 분명 인증은 됐는데 왜 거부당할까. 필터 체인의 CsrfFilter가 POST에 CSRF 토큰이 없는 걸 보고 튕긴 것이다.

선호 패턴:

@Test
@WithMockUser(roles = "USER")
void 주문_생성() throws Exception {
    mockMvc.perform(post("/api/orders")
            .with(csrf())  // ← 이거 한 줄
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"itemId\":1}"))
        .andExpect(status().isCreated());
}

.with(csrf())는 유효한 CSRF 토큰을 자동 생성해서 파라미터로 첨부한다. JSON API처럼 헤더로 보내고 싶으면 .with(csrf().asHeader())를 쓴다.

5-2) REST API는 CSRF를 꺼두는 게 표준 아닌가

맞다. stateless JWT API는 보통 .csrf(csrf -> csrf.disable())로 꺼둔다. 이 설정을 테스트 컨텍스트에도 그대로 로드한다면 .with(csrf())는 필요 없다. 그런데 테스트용 보안 설정이 따로 기본값으로 로드되고 있다면 CSRF가 켜져 있을 수 있다. @WebMvcTest에서 커스텀 SecurityConfig를 import하지 않았다면 Spring Security 기본 설정(CSRF on)이 자동 적용된다.

증상이 403이면 체크 순서는 이렇다.

컨트롤러가 실제로 실행되는가 — 브레이크포인트나 로그로 확인. 실행 안 되면 필터에서 튕긴 것
CSRF 토큰이 있는가 — .with(csrf()) 추가
사용자 역할이 맞는가 — @PreAuthorize나 HttpSecurity 매처 조건 확인
CORS가 원인인가 — 이건 거의 없지만 통합 테스트에서 가끔 발생

5-3) GET에는 CSRF 불필요

GET은 기본적으로 상태 변경이 아닌 걸로 간주되므로 CSRF 검사를 안 한다. GET 테스트에 .with(csrf())를 붙이면 경고는 안 나지만 의미 없는 노이즈다.

6) formLogin(), logout(), authenticated() matcher

폼 기반 로그인 플로우를 통합 테스트하는 전용 API가 있다.

6-1) `formLogin()` — 로그인 시도

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.*;
import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.*;

@Test
void 로그인_성공() throws Exception {
    mockMvc.perform(formLogin().user("alice").password("secret"))
        .andExpect(authenticated().withUsername("alice"))
        .andExpect(redirectedUrl("/home"));
}

@Test
void 로그인_실패() throws Exception {
    mockMvc.perform(formLogin().user("alice").password("wrong"))
        .andExpect(unauthenticated())
        .andExpect(redirectedUrl("/login?error"));
}

formLogin()은 내부에서 POST /login에 username/password 파라미터와 CSRF 토큰을 자동으로 넣어준다. 직접 post("/login")을 쓰는 것보다 훨씬 짧다.

6-2) `logout()` — 로그아웃 플로우

@Test
@WithMockUser
void 로그아웃() throws Exception {
    mockMvc.perform(logout())
        .andExpect(unauthenticated())
        .andExpect(redirectedUrl("/login?logout"));
}

logout()도 내부에서 POST /logout + CSRF를 처리한다.

6-3) Result Matcher

matcher	검증 대상
`authenticated()`	`SecurityContext`에 인증된 `Authentication`이 있는가
`unauthenticated()`	없거나 `Anonymous`인가
`.withUsername("x")`	principal 이름
`.withRoles("ADMIN")`	권한에 `ROLE_ADMIN` 포함
`.withAuthentication(m)`	Hamcrest matcher로 세밀한 검증

.andExpect(authenticated()
    .withUsername("alice")
    .withRoles("USER", "ADMIN"))

7) @WebMvcTest vs @SpringBootTest + @AutoConfigureMockMvc

두 어노테이션의 선택은 보안 설정을 포함해서 테스트할 것인가, 로직만 볼 것인가로 갈린다.

7-1) `@WebMvcTest`

컨트롤러 한 개 + MVC 관련 빈만 로드한다. 빠르지만 커스텀 SecurityConfig를 자동으로 안 불러온다.

피해야 할 패턴:

@WebMvcTest(OrderController.class)
class OrderControllerTest {
    // SecurityConfig가 로드되지 않아 Spring Security 기본값 적용
    // — 기본값: 모든 요청 인증 필요 + CSRF on
}

선호 패턴:

@WebMvcTest(OrderController.class)
@Import(SecurityConfig.class) // 실제 보안 설정 포함
class OrderControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean OrderService orderService;
    ...
}

여기서 @MockBean UserDetailsService를 선언하고 @WithMockUser를 쓰면 헷갈린다. @WithMockUser는 UserDetailsService를 호출하지 않는다. @MockBean은 빈 주입을 만족시키려고 필요한 것뿐이고, @WithMockUser는 아예 그 빈을 건드리지 않고 토큰을 만들어 박는다. 이 구분을 알면 "왜 when(...).thenReturn(...)을 해놨는데 안 불리지"라는 혼란이 없어진다.

7-2) `@SpringBootTest` + `@AutoConfigureMockMvc`

전체 컨텍스트를 로드한다. 실제 빈들이 전부 올라오고 SecurityConfig도 자동 포함된다.

@SpringBootTest
@AutoConfigureMockMvc
class OrderIntegrationTest {
    @Autowired MockMvc mockMvc;
    // 실제 UserDetailsService, 실제 PasswordEncoder, 실제 DB까지
}

느리지만 완전한 통합 테스트다. @WithUserDetails가 제대로 동작하는 것도 여기다.

7-3) `MockMvc` 자동 Security 통합

Spring Boot 3.x의 @AutoConfigureMockMvc는 Security 필터 체인을 MockMvc에 자동 배치한다. 따라서 별도 설정이 필요 없다. 반면 Boot 없이 raw Spring Test를 쓸 때는 명시적으로 붙여야 한다.

// Spring Boot 없는 경우에만 필요
mockMvc = MockMvcBuilders.webAppContextSetup(ctx)
    .apply(SecurityMockMvcConfigurers.springSecurity())
    .build();

이게 빠진 상태에서 @WithMockUser를 쓰면 **컨트롤러의 Principal이 null**로 들어온다. 컨텍스트에는 auth가 있는데 필터를 안 거치니 HttpServletRequest에 principal이 박히지 않는 것이다. 증상이 "auth는 있는데 컨트롤러에서는 null"이면 이걸 의심한다.

8) Method Security 테스트: AOP 프록시 조건

@PreAuthorize, @PostAuthorize, @Secured는 전부 AOP 프록시 위에서 동작한다. 메서드 호출 시점에 프록시가 Authentication을 꺼내 조건을 평가하고, 실패하면 AccessDeniedException을 던진다. 프록시가 없으면 그냥 평범한 메서드 호출이 되어 어노테이션이 완전히 무시된다.

8-1) 단위 테스트에서 흔히 틀리는 패턴

피해야 할 패턴:

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @InjectMocks OrderService service; // ← 프록시 없음
    @Mock OrderRepository repo;

    @Test
    @WithMockUser(roles = "USER")
    void 권한없는_사용자_거부() {
        // 기대: AccessDeniedException
        // 실제: 그냥 통과. @PreAuthorize가 아예 평가 안 됨
        assertThatThrownBy(() -> service.deleteOrder(1L))
            .isInstanceOf(AccessDeniedException.class); // 실패
    }
}

@InjectMocks는 순수 자바 객체를 만든다. Spring AOP 프록시로 감싸지 않는다. 그래서 @PreAuthorize("hasRole('ADMIN')")이 붙어 있어도 무시된다. 게다가 @ExtendWith(MockitoExtension.class)는 Spring 컨텍스트를 띄우지 않으므로 @WithMockUser의 WithSecurityContextTestExecutionListener도 등록되지 않아서 이중으로 무력화된다.

8-2) 제대로 검증하는 방법

메서드 시큐리티는 Spring 컨텍스트 위에서 테스트해야 한다.

선호 패턴:

@SpringBootTest
class OrderServiceMethodSecurityTest {

    @Autowired OrderService service;
    @MockBean OrderRepository repo;

    @Test
    @WithMockUser(roles = "USER")
    void 일반사용자는_주문삭제_불가() {
        assertThatThrownBy(() -> service.deleteOrder(1L))
            .isInstanceOf(AccessDeniedException.class);
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    void 관리자는_주문삭제_가능() {
        assertThatCode(() -> service.deleteOrder(1L))
            .doesNotThrowAnyException();
    }
}

풀 컨텍스트가 무거우면 슬림하게 줄일 수도 있다.

@ExtendWith(SpringExtension.class)
@Import(OrderService.class)
@EnableMethodSecurity
class OrderServiceSlimTest {
    @Autowired OrderService service;
    ...
}

@Import로 대상 빈만 올리고 @EnableMethodSecurity로 AOP 프록시만 활성화한다. @SpringBootTest보다 빠르면서 메서드 시큐리티는 살아 있다.

8-3) 요약 표

테스트 스타일	AOP 프록시	`@PreAuthorize` 동작
`@ExtendWith(MockitoExtension)` + `@InjectMocks`	없음	무시됨
`@SpringBootTest`	있음	동작
`@ExtendWith(SpringExtension)` + `@Import` + `@EnableMethodSecurity`	있음	동작
`@WebMvcTest` (서비스 계층)	없음 (컨트롤러만)	무시됨

9) JWT / OAuth2 mock: jwt().claim().authorities()

Resource Server로 JWT 검증을 하는 API는 테스트에서 실제 토큰을 발급받기 어렵다. JwtDecoder를 mock하는 것도 가능하지만, SecurityMockMvcRequestPostProcessors.jwt()가 훨씬 간단하다.

9-1) JWT 기본

mockMvc.perform(get("/api/profile")
        .with(jwt().jwt(builder -> builder
            .subject("alice")
            .claim("email", "alice@example.com"))))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.username").value("alice"));

jwt()는 내부에서 JwtAuthenticationToken을 만들어 SecurityContext에 박는다. 실제 서명 검증은 일어나지 않는다.

9-2) 스코프 권한 주입

JWT는 SCOPE_* 권한으로 변환되는 게 기본이다. 포스트프로세서에서 직접 지정할 수 있다.

mockMvc.perform(post("/api/orders")
        .with(jwt().authorities(
            new SimpleGrantedAuthority("SCOPE_orders:write")))
        .with(csrf())
        .contentType(MediaType.APPLICATION_JSON)
        .content("{...}"))
    .andExpect(status().isCreated());

@PreAuthorize("hasAuthority('SCOPE_orders:write')")를 이 조합으로 검증한다.

Introspection 기반 Opaque 토큰:

mockMvc.perform(get("/api/me")
        .with(opaqueToken().attributes(a -> a.put("sub", "alice"))));

OAuth2 Client로 로그인한 상태(/oauth2/authorization/google 흐름을 지난 상태) mock:

mockMvc.perform(get("/")
        .with(oauth2Login()
            .authorities(new SimpleGrantedAuthority("ROLE_USER"))
            .attributes(a -> a.put("email", "alice@gmail.com"))));

OAuth2 Login은 OAuth2User를 principal로 만드는 흐름이라, 컨트롤러에서 @AuthenticationPrincipal OAuth2User로 받을 때 필드 값이 필요한 경우 attributes로 채워준다.

10) WebFlux: WebTestClient + mockUser / mockJwt

Reactive 스택은 MockMvc가 아니라 WebTestClient를 쓴다. 포스트프로세서도 이름이 다르다.

10-1) `SecurityMockServerConfigurers`

import static org.springframework.security.test.web.reactive.server.SecurityMockServerConfigurers.*;

@Test
void reactive_admin_엔드포인트() {
    webTestClient
        .mutateWith(mockUser("alice").roles("ADMIN"))
        .get().uri("/admin/stats")
        .exchange()
        .expectStatus().isOk();
}

mutateWith는 WebTestClient의 설정을 테스트별로 변경하는 진입점이다. 내부적으로 ServerWebExchange에 Authentication을 주입한다.

10-2) 주요 configurer

메서드	용도
`mockUser(...)`	기본 사용자 주입
`mockAuthentication(auth)`	커스텀 `Authentication`
`mockJwt()`	`JwtAuthenticationToken` mock
`mockOpaqueToken()`	Opaque 토큰 mock
`mockOAuth2Login()`	OAuth2 로그인 상태
`csrf()`	CSRF 토큰

webTestClient
    .mutateWith(mockJwt()
        .jwt(j -> j.subject("alice"))
        .authorities(new SimpleGrantedAuthority("SCOPE_read")))
    .get().uri("/api/data")
    .exchange()
    .expectStatus().isOk();

10-3) `@WithMockUser`는 Reactive에서도 동작

어노테이션 기반은 MVC/Reactive 공통이다. @WithMockUser는 ReactiveSecurityContextHolder와 SecurityContextHolder 양쪽 모두에 맞춰진 TestSecurityContextHolder를 경유해 주입된다. 어노테이션을 쓰면 스택에 관계없이 같은 방식이 되고, 포스트프로세서(혹은 WebTestClientConfigurer)를 쓸 때만 서블릿·리액티브 API가 갈린다.

11) 실무에서 이렇게 읽고 쓴다

컨트롤러 단위 테스트는 @WebMvcTest + @Import(SecurityConfig.class). SecurityConfig를 안 불러오면 테스트용 기본값이 적용돼 실제 동작과 달라진다
POST/PUT/DELETE 테스트 실패하면 403부터 확인. 99%가 .with(csrf()) 빠진 케이스다. JSON API라면 .with(csrf().asHeader())까지 고려
@WithMockUser vs @WithUserDetails 선택 기준은 단 하나: UserDetailsService를 실제로 호출할 필요가 있는가. 커스텀 UserDetails 필드(tenantId 등)를 로직이 쓴다면 @WithUserDetails
@MockBean UserDetailsService와 @WithMockUser를 섞어 쓰는 실수: when(...).thenReturn(...)이 호출 안 된 것처럼 보이는 이유. 애초에 @WithMockUser는 그 빈을 안 부른다
roles는 ROLE_ 접두사 붙고, authorities는 안 붙는다. hasRole과 hasAuthority의 차이를 모르면 테스트가 설정 따라 들쭉날쭉 통과한다
@PreAuthorize 단위 테스트는 Spring 컨텍스트 필수. Mockito @InjectMocks로는 AOP 프록시가 없어 검증 자체가 무력화된다. @SpringBootTest 또는 @Import + @EnableMethodSecurity
JWT/OAuth2 Resource Server는 jwt() 포스트프로세서. JwtDecoder를 직접 mock하지 말고 Security Test API를 써라. 서명 검증·시간 검증을 건너뛰면서도 권한은 그대로 주입된다
WebFlux는 mutateWith(mockUser(...)). MVC의 .with(user(...))와 이름이 다르다. 혼동하면 컴파일은 되지만 주입이 안 된다
통합 테스트에서 formLogin()과 logout() 유틸을 써라. post("/login")을 직접 쓰면 CSRF·파라미터 이름·경로를 매번 직접 관리하게 된다
디버깅 팁: 401/403이 나면 먼저 .andDo(print())로 필터 체인 응답 헤더와 바디를 찍어본다. WWW-Authenticate나 에러 메시지에 거의 원인이 나온다

12) 한 줄 정리

Spring Security Testing은 "컨텍스트 주입 + 요청별 주입 + 응답 검증" 세 축을 섞어 쓰는 작업이다. @WithMockUser와 @WithUserDetails는 UserDetailsService 호출 여부에서 갈리고, MockMvc의 .with(csrf())는 상태 변경 요청에 거의 항상 필요하며, @PreAuthorize 검증은 AOP 프록시가 있는 컨텍스트에서만 의미를 가진다. roles와 authorities의 ROLE_ 접두사 차이를 놓치면 같은 코드가 설정 따라 통과·실패를 왕복하니 처음부터 구분해서 쓴다.

태그: spring-security, testing, mockmvc, webtestclient, withmockuser, withuserdetails, method-security, csrf, jwt, webflux

Spring Security OAuth2 Client — Authorization Code Flow와 ClientRegistration 내부

dding-shark — Tue, 14 Apr 2026 22:04:12 +0900

Spring Security OAuth2 Client — Authorization Code Flow와 ClientRegistration 내부

들어가며

바로 앞 글(27편 Resource Server)이 "이미 발급된 토큰을 받기만 하는 쪽"이었다면, 이번 글은 정반대다. 토큰을 발급받아 오는 쪽 — 사용자를 IdP로 리다이렉트하고, 돌아온 code를 token endpoint에 교환하고, 받은 access_token을 저장해 뒀다가 API 호출할 때 붙여 주는 전 과정을 Spring Security가 알아서 해 준다. spring-boot-starter-oauth2-client 하나 추가하면 application.yml 여덟 줄로 구글 로그인이 동작한다. 그 아래에서 필터 두 개가 리다이렉트를 주고받고, ClientRegistration이 설정을 들고 있고, OAuth2AuthorizedClientManager가 토큰 수명을 관리한다.

문제는 이 흐름이 브라우저 리다이렉트를 3번 거친다는 점이다. 디버거를 찍어도 세션이 끊어졌다 붙었다 하니 한 번에 따라가기 어렵고, 실패하면 어느 단계에서 어긋났는지 증상만 봐서는 모른다. 다음 네 지점이 거의 항상 한 번씩은 걸린다.

Authorization Code Flow를 머릿속에 못 그리면 디버깅이 안 잡힌다 — 리다이렉트가 3번 일어나고, 필터는 그 중 2개만 관여한다
redirect-uri를 하드코딩했다가 배포 환경별로 매번 고친다 — {baseUrl} placeholder를 쓰면 자동으로 치환된다
로그아웃을 눌렀는데 다시 로그인 버튼을 누르면 바로 통과된다 — IdP 쪽 세션이 살아 있어서다. OIDC Logout이 답이다
멀티 인스턴스로 띄웠더니 OAuth 콜백이 랜덤하게 튕긴다 — HttpSession 기반 리포지토리가 기본이라 sticky session 또는 JDBC/Spring Session이 필요하다

이 글은 왜 → 플로우 → 필터/리포지토리 → 토큰 관리 → API 호출 → PKCE/OIDC → 실무 순으로 Spring Security 6.x / Spring Boot 3.x 기준으로 정리한다.

1) OAuth2 Client와 Resource Server의 역할 분리
2) Authorization Code Flow 전체 시퀀스
3) ClientRegistration과 Boot 자동구성
4) OAuth2AuthorizationRequestRedirectFilter 내부
5) OAuth2LoginAuthenticationFilter와 토큰 교환
6) OAuth2User와 OidcUser: UserInfo 조회
7) AuthorizedClientRepository vs Service: 어디에 저장하나
8) OAuth2AuthorizedClientManager와 자동 refresh
9) @RegisteredOAuth2AuthorizedClient와 WebClient로 API 호출
10) PKCE: public client와 Spring Security 6의 권장
11) OIDC Logout과 OidcClientInitiatedLogoutSuccessHandler
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) OAuth2 Client와 Resource Server의 역할 분리

OAuth2의 세 축은 Authorization Server, Client, Resource Server다. Resource Server는 "토큰을 받기만 하는 쪽"이고, **Client는 "토큰을 발급받는 쪽"**이다. 사용자를 IdP로 리다이렉트하고, IdP에서 돌아온 code를 토큰으로 교환하고, 그 토큰을 저장해 두었다가 외부 API를 호출할 때 Authorization: Bearer로 붙인다. Spring Security가 이 모든 단계를 필터와 서비스로 쪼개 놓았다.

이 차이를 못 잡으면 스타터부터 잘못 고른다. 백엔드 API만 있는 서비스가 oauth2-client를 추가하면 브라우저가 IdP 로그인 페이지로 리다이렉트되기 시작하고, 반대로 로그인 기능이 필요한 서비스가 oauth2-resource-server만 추가하면 콜백 처리는커녕 리다이렉트도 일어나지 않는다. 두 스타터는 서로의 대체재가 아니라 다른 일을 하는 서로 다른 모듈이다.

구분	OAuth2 Client	OAuth2 Resource Server
역할	토큰을 발급받아 저장/사용	토큰을 받아 검증
스타터	`spring-boot-starter-oauth2-client`	`spring-boot-starter-oauth2-resource-server`
주도 필터	`OAuth2AuthorizationRequestRedirectFilter` + `OAuth2LoginAuthenticationFilter`	`BearerTokenAuthenticationFilter`
DSL	`http.oauth2Login(...)` / `http.oauth2Client(...)`	`http.oauth2ResourceServer(...)`
세션 필요?	예 — 리다이렉트 상태 보관	아니오 — STATELESS 권장

oauth2Login과 oauth2Client도 서로 다르다. oauth2Login은 "OAuth2로 사용자를 로그인시킨다"(= 내 앱의 Authentication 주체를 IdP가 제공한 OAuth2 사용자로 세팅). oauth2Client는 "OAuth2를 외부 API 호출용 자격증명으로 쓴다"(= 로그인은 별도로 하고, 토큰은 외부 서비스 호출용). 대부분의 웹 앱은 oauth2Login만 켜면 두 일이 한 번에 된다.

2) Authorization Code Flow 전체 시퀀스

Authorization Code Flow는 OAuth2에서 가장 흔하고 동시에 가장 디버깅이 까다로운 그랜트다. 브라우저가 세 번 리다이렉트되는 동안 세션은 유지되고, 민감한 자격증명(클라이언트 시크릿)은 브라우저를 거치지 않는다. 일단 시퀀스부터 그리고 본문을 읽는 게 훨씬 빠르다.

시퀀스에서 눈여겨볼 세 지점. 첫째, 클라이언트 시크릿은 브라우저를 거치지 않는다. code가 브라우저로 돌아온 뒤, 앱 서버가 직접 IdP의 token endpoint에 code + client_secret(또는 code_verifier)을 POST로 교환한다. 이 교환이 백엔드 간 통신이라 시크릿이 노출되지 않는다. 둘째, state 파라미터가 CSRF 방어를 한다. 리다이렉트 시작 시 앱이 세션에 state를 저장하고, 콜백에서 돌아온 state와 비교한다. 안 맞으면 거부. 셋째, code는 일회용 + 단명이다. 보통 수십 초 안에 만료되고 한 번 교환하면 소멸한다.

이 시퀀스가 머릿속에 안 들어가 있으면 "왜 내 앱이 방금 IdP로 튕겼지?"에서 멈춘다. 리다이렉트가 3번이라는 걸 기억해 두면 네트워크 탭에서 단계별로 끊어 볼 수 있다.

3) ClientRegistration과 Boot 자동구성

ClientRegistration은 "한 IdP를 어떻게 부르면 되는가"의 메타데이터다. client id, client secret, authorization uri, token uri, scope, redirect uri, 사용자 이름 클레임 — IdP 연동에 필요한 모든 설정이 이 한 객체에 들어 있다. Spring Security는 이걸 빌더로도, application.yml로도, OIDC Discovery로도 만들 수 있다.

3-1) 빌더로 직접

ClientRegistration google = ClientRegistration.withRegistrationId("google")
    .clientId("xxx")
    .clientSecret("yyy")
    .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
    .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
    .redirectUri("{baseUrl}/login/oauth2/code/{registrationId}")
    .scope("openid", "profile", "email")
    .authorizationUri("https://accounts.google.com/o/oauth2/v2/auth")
    .tokenUri("https://oauth2.googleapis.com/token")
    .userInfoUri("https://openidconnect.googleapis.com/v1/userinfo")
    .userNameAttributeName(IdTokenClaimNames.SUB)
    .jwkSetUri("https://www.googleapis.com/oauth2/v3/certs")
    .clientName("Google")
    .build();

대부분의 항목은 IdP 문서에서 옮겨 적는 값이다. 여기서 놓치면 안 되는 게 redirectUri의 {baseUrl}과 {registrationId} placeholder다. Spring Security가 런타임에 request의 scheme/host/port와 registration id로 치환하므로 로컬, 스테이징, 프로덕션에서 각각 값을 바꿀 필요가 없다. http://localhost:8080/login/oauth2/code/google이나 https://app.example.com/login/oauth2/code/google이 자동으로 만들어진다. 하드코딩하지 말 것. 들어가며의 두 번째 함정이다.

3-2) OIDC Discovery로 자동 채우기

OIDC를 지원하는 IdP는 /.well-known/openid-configuration 엔드포인트에서 위 URL들을 전부 JSON으로 내려준다. Spring Security는 이걸 한 줄로 읽어서 ClientRegistration을 만들 수 있다.

ClientRegistration keycloak = ClientRegistrations
    .fromIssuerLocation("https://idp.example.com/realms/app")
    .registrationId("keycloak")
    .clientId("my-client")
    .clientSecret("secret")
    .build();

fromIssuerLocation이 discovery 문서를 GET해서 authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri를 전부 채운다. 빌더로 채운 값들과 merge되므로 예외(값을 바꾸고 싶은 경우)만 .xxx(...)로 덮으면 된다.

3-3) Spring Boot 자동구성

프로덕션에서 실제로 가장 많이 쓰는 방식은 application.yml이다.

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}
            scope: openid, profile, email
          keycloak:
            client-id: my-client
            client-secret: ${KEYCLOAK_SECRET}
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
            scope: openid, profile
        provider:
          keycloak:
            issuer-uri: https://idp.example.com/realms/app

Boot가 하는 일은 두 가지다. 첫째, 등록된 provider에 issuer-uri가 있으면 discovery를 호출해 엔드포인트를 채운다. 둘째, CommonOAuth2Provider enum(GOOGLE/GITHUB/FACEBOOK/OKTA)에 해당하는 registration은 provider 블록 없이도 기본 URL이 내장돼 있다. 그래서 구글은 client-id/client-secret만 있으면 끝난다.

빈으로는 InMemoryClientRegistrationRepository가 기본으로 뜬다. 멀티 테넌시나 런타임 추가가 필요하면 JdbcClientRegistrationRepository로 바꿔서 DB에 저장한다.

4) OAuth2AuthorizationRequestRedirectFilter 내부

Flow의 첫 번째 리다이렉트(앱 → IdP)를 만드는 필터다. 이름이 긴 만큼 이름이 곧 역할이다 — Authorization Request를 만들어서 Redirect로 내려보낸다.

트리거는 두 가지다. 사용자가 직접 /oauth2/authorization/{registrationId} URL을 치거나(로그인 버튼이 보통 이 URL로 링크), 인증 필요한 엔드포인트에서 LoginUrlAuthenticationEntryPoint가 해당 URL로 리다이렉트하거나. oauth2Login이 등록되면 기본 entry point가 이 리다이렉트로 설정된다.

필터가 하는 일 순서.

matcher 체크 — URL이 /oauth2/authorization/{registrationId}에 매칭되는지 확인한다. OAuth2AuthorizationRequestResolver가 담당한다.
ClientRegistration 조회 — ClientRegistrationRepository에서 registration id로 찾는다. 없으면 그냥 다음 필터로 넘긴다(이 필터가 처리할 일이 아님).
OAuth2AuthorizationRequest 생성 — state(랜덤 32바이트 base64), PKCE 활성 시 code_verifier + code_challenge, 그리고 authorization uri + scope + redirect uri + client id를 조합한 full URL을 만든다.
세션에 저장 — AuthorizationRequestRepository(기본 HttpSessionOAuth2AuthorizationRequestRepository)에 이 요청을 state를 키로 저장한다. 콜백 검증 시 꺼내 쓸 code_verifier와 원래 요청 URL을 여기에 같이 넣는다.
302 리다이렉트 — RedirectStrategy로 브라우저에 full authorization URL로 리다이렉트 응답을 보낸다.

여기서 중요한 게 세션이다. state와 code_verifier는 콜백에서 다시 꺼내 검증/교환에 써야 하는데, 브라우저는 IdP를 경유해 돌아오므로 앱 측에서 기억할 곳은 세션뿐이다(기본 구현 기준). 세션이 없거나 콜백 시점에 다른 노드로 라우팅되면 AuthorizationRequest가 사라져서 [invalid_state_parameter] 오류가 난다.

여기서 틀리기 쉽다. 무상태(STATELESS) 설정을 전면 적용한 뒤 oauth2Login을 켜면 이 필터가 세션을 못 만들어 바로 깨진다. oauth2Login을 쓴다면 세션은 필요하다. 필요하면 OAuth 플로우 동안만 세션을 허용하고 나머지는 상태 없이 가도록 설계한다(이 글 범위 밖, 별도 튜닝).

http.oauth2Login(oauth2 -> oauth2
    .authorizationEndpoint(endpoint -> endpoint
        .baseUri("/oauth2/authorization")             // 기본값
        .authorizationRequestRepository(repo)         // 커스터마이즈
        .authorizationRequestResolver(resolver)       // PKCE 활성 등
    )
);

5) OAuth2LoginAuthenticationFilter와 토큰 교환

두 번째 리다이렉트로 브라우저가 /login/oauth2/code/{registrationId}?code=...&state=...에 도착하면 이 필터가 받는다. 이번엔 토큰 교환과 사용자 로딩, 인증 주체 세팅까지 한꺼번에 처리한다.

5-1) 다섯 단계

state 검증 — 쿼리의 state와 세션에 저장된 OAuth2AuthorizationRequest.state를 비교한다. 불일치 시 즉시 거부. CSRF 방어의 핵심이다.
토큰 교환 — OAuth2AuthorizationCodeGrantRequest를 만들어 OAuth2AccessTokenResponseClient에 넘긴다. 기본 구현은 RestClientAuthorizationCodeTokenResponseClient(6.3+) 또는 DefaultAuthorizationCodeTokenResponseClient로, IdP의 token endpoint에 POST로 code + client_secret + redirect_uri + code_verifier(PKCE)를 보낸다. 응답은 OAuth2AccessTokenResponse — access_token, token_type, expires_in, 선택적 refresh_token, OIDC면 id_token.
ID Token 검증 (OIDC) — OIDC면 OidcAuthorizationCodeAuthenticationProvider가 나서서 id_token의 서명(JWKS), iss, aud, exp, nonce를 검증한다. 여기서 실패하면 로그인 자체가 거부된다.
UserInfo 조회 — OAuth2UserService(기본 DefaultOAuth2UserService) 또는 OIDC면 OidcUserService가 userinfo endpoint를 호출해 사용자 프로필을 가져온다(OIDC는 id token만으로도 충분한 경우 스킵 가능). 결과는 OAuth2User 또는 OidcUser.
Authentication 생성 + 저장 — OAuth2LoginAuthenticationToken(authenticated=true)을 만들어 SecurityContextHolder에 꽂고, 토큰들을 OAuth2AuthorizedClient로 묶어 OAuth2AuthorizedClientRepository에 저장한다. 이후 AuthenticationSuccessHandler가 원래 요청 URL로 리다이렉트.

5-2) 두 종류의 Authentication이 나뉜다

여기서 혼동 포인트가 하나 있다. **로그인 결과로 SecurityContextHolder에 들어가는 Authentication**과 AuthorizedClient에 저장되는 토큰은 역할이 다르다. 전자는 "내 앱의 로그인 주체가 누구인가"를 표현하고, 후자는 "이 사용자의 IdP 발급 access token이 뭐인가"를 들고 있다. 앱 안에서 /me 같은 엔드포인트의 권한 체크는 전자가 처리하고, 외부 API(구글 Calendar 등) 호출은 후자의 토큰을 꺼내 Bearer로 붙인다.

OAuth2LoginAuthenticationToken의 principal 타입은 OAuth2User (또는 OIDC면 OidcUser)다. @AuthenticationPrincipal OAuth2User user로 주입받을 수 있고, 거기서 getAttributes()로 IdP가 내려준 클레임을 꺼낸다.

6) OAuth2User와 OidcUser: UserInfo 조회

OAuth2User는 OAuth2 로그인이 끝나고 난 뒤 Spring Security가 쓰는 "사용자" 추상이다. UserDetails와는 별개다 — 폼 로그인에서 쓰는 UserDetails는 로컬 사용자 DB의 표현이고, OAuth2User는 IdP가 내려준 프로필의 표현이다.

public interface OAuth2User {
    Map<String, Object> getAttributes();
    Collection<? extends GrantedAuthority> getAuthorities();
    String getName();
}

기본 DefaultOAuth2UserService는 ClientRegistration.getProviderDetails().getUserInfoEndpoint().getUri()로 GET을 때려 JSON을 가져온다. userNameAttributeName으로 지정된 클레임(구글은 sub, 깃허브는 id, 네이버는 response처럼 중첩인 경우도)을 getName() 값으로 쓴다. 이걸 잘못 설정하면 Principal name이 null이 되거나 IllegalArgumentException이 난다.

OIDC면 OidcUser가 대신 들어가고, 이건 OAuth2User를 확장해서 OidcIdToken과 OidcUserInfo를 추가로 들고 있다.

public interface OidcUser extends OAuth2User, IdTokenClaimAccessor {
    OidcUserInfo getUserInfo();
    OidcIdToken getIdToken();
}

OidcIdToken에는 IdP가 서명한 JWT가 들어 있어서 별도 userinfo 호출 없이도 sub, email, name을 꺼낼 수 있다. 많은 경우 userinfo는 호출하지 않아도 ID Token만으로 충분하다.

6-1) 권한 매핑

IdP가 내려준 scope이나 roles 클레임을 앱의 GrantedAuthority로 바꾸고 싶으면 두 방법이 있다.

http.oauth2Login(oauth2 -> oauth2
    .userInfoEndpoint(info -> info
        .userAuthoritiesMapper(authorities -> {
            // 기본 SCOPE_xxx들을 ROLE_xxx로 바꾸거나,
            // 커스텀 클레임(roles)에서 추출해 권한을 재구성
            return remapped;
        })
        .oidcUserService(customOidcUserService)
    )
);

GrantedAuthoritiesMapper는 이미 생성된 authority를 한 번 더 가공하는 자리이고, OidcUserService(또는 OAuth2UserService) 커스텀 빈은 애초에 OidcUser/OAuth2User를 만들 때 권한을 직접 세팅한다. 복잡한 매핑은 후자가 낫다.

7) AuthorizedClientRepository vs Service: 어디에 저장하나

토큰 저장은 Spring Security가 두 계층으로 추상화해 놓았다. 이름이 비슷해서 헷갈리기 쉽다.

타입	역할	기본 구현
`OAuth2AuthorizedClientRepository`	HTTP 레벨 조회/저장 — request/response/principal 문맥 필요	`HttpSessionOAuth2AuthorizedClientRepository`
`OAuth2AuthorizedClientService`	Principal 레벨 영속 — HTTP 문맥 없이도 동작	`InMemoryOAuth2AuthorizedClientService`

**OAuth2AuthorizedClientRepository**는 컨트롤러 필터 체인에서 "지금 이 요청의 주체가 가진 토큰"을 가져올 때 쓴다. 기본 구현은 세션을 저장소로 쓰고, 사용자별 토큰을 HTTP 세션에 넣는다.

**OAuth2AuthorizedClientService**는 HTTP 밖(예: 스케줄러, 배치 잡)에서 토큰을 꺼낼 때 쓴다. principal name만 알면 저장/조회가 가능하다.

HttpSessionOAuth2AuthorizedClientRepository는 내부적으로 세션에 직접 저장하고, AuthenticatedPrincipalOAuth2AuthorizedClientRepository는 OAuth2AuthorizedClientService에 저장 책임을 위임한다. 후자를 쓰면 세션에 토큰을 안 넣고도 원리 상 동작한다.

7-1) 멀티 인스턴스 함정

기본이 세션 저장이라 앱을 여러 인스턴스로 띄웠는데 세션 공유를 안 하면 OAuth 콜백이 랜덤하게 실패한다. /oauth2/authorization/...로 리다이렉트 만든 인스턴스와 /login/oauth2/code/...로 콜백 받은 인스턴스가 다르면 AuthorizationRequestRepository가 값을 못 찾는다. 들어가며의 네 번째 함정이다.

해결은 세 가지.

sticky session — 로드밸런서에서 같은 사용자는 같은 인스턴스로 고정. 가장 단순하지만 장애 시 불편.
Spring Session + Redis — 세션 자체를 공유 스토리지에 저장. HttpSessionOAuth2AuthorizedClientRepository가 그대로 동작한다.
JDBC 리포지토리로 교체 — JdbcOAuth2AuthorizedClientService를 써서 DB 테이블에 저장. AuthenticatedPrincipalOAuth2AuthorizedClientRepository와 조합한다.

@Bean
OAuth2AuthorizedClientService authorizedClientService(
        JdbcOperations jdbc,
        ClientRegistrationRepository clients) {
    return new JdbcOAuth2AuthorizedClientService(jdbc, clients);
}

@Bean
OAuth2AuthorizedClientRepository authorizedClientRepository(
        OAuth2AuthorizedClientService service) {
    return new AuthenticatedPrincipalOAuth2AuthorizedClientRepository(service);
}

스키마는 Spring Security가 기본 DDL 파일(oauth2-client-schema.sql)을 제공한다. Flyway/Liquibase에 얹어 초기 마이그레이션으로 관리한다.

8) OAuth2AuthorizedClientManager와 자동 refresh

OAuth2AuthorizedClient에 저장된 access_token은 언젠가 만료된다. 만료 시 refresh_token으로 새 access token을 받아오는 절차를 매번 직접 짜는 건 고역이다. Spring Security는 이걸 OAuth2AuthorizedClientManager 한 개로 추상화한다.

8-1) 역할

OAuth2AuthorizedClientManager.authorize(OAuth2AuthorizeRequest)를 부르면 Manager가 한다.

저장소(Repository 또는 Service)에서 해당 principal + registration의 OAuth2AuthorizedClient를 조회.
access token이 살아 있으면 그대로 반환.
만료됐고 refresh_token이 있으면 refresh grant로 새 token을 받아 저장소 갱신.
아직 없으면 authorization_code/client_credentials 등 설정된 grant로 처음 획득.

8-2) Provider 체인

Manager 내부는 OAuth2AuthorizedClientProvider 체인이다. 각 provider가 한 그랜트 타입을 책임진다. 기본 조합은 OAuth2AuthorizedClientProviderBuilder로 만든다.

@Bean
OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clients,
        OAuth2AuthorizedClientRepository authorizedClients) {

    OAuth2AuthorizedClientProvider provider = OAuth2AuthorizedClientProviderBuilder.builder()
        .authorizationCode()
        .refreshToken()
        .clientCredentials()
        .build();

    DefaultOAuth2AuthorizedClientManager manager =
        new DefaultOAuth2AuthorizedClientManager(clients, authorizedClients);
    manager.setAuthorizedClientProvider(provider);
    return manager;
}

체인 순서대로 각 provider가 "내가 처리할 수 있는 상태인가?"를 확인하고 맞는 것이 처리한다. 예를 들어 만료된 access token + 유효한 refresh token 상태면 refreshToken() provider가 나서서 refresh grant를 수행한다.

서블릿 스택의 기본 구현은 DefaultOAuth2AuthorizedClientManager, HTTP 문맥이 없을 때(배치, 스케줄러)는 AuthorizedClientServiceOAuth2AuthorizedClientManager를 쓴다. 후자는 OAuth2AuthorizedClientService 기반이라 request/response가 필요 없다.

8-3) 만료 임계치

refresh 시점을 결정하는 건 expiresAt이지만, 정확히 만료된 순간에 refresh를 시도하면 이미 만료된 상태라 401이 날 수도 있다. DefaultOAuth2AuthorizedClientManager는 내부적으로 clockSkew(기본 60초)만큼 일찍 만료로 판단한다. 시계가 조금 어긋나 있어도 안전하게 돈다. 이 값은 OAuth2AuthorizedClientProviderBuilder.refreshToken(cfg -> cfg.clockSkew(Duration.ofSeconds(30)))로 조정 가능하다.

9) @RegisteredOAuth2AuthorizedClient와 WebClient로 API 호출

저장된 토큰을 외부 API 호출에 꽂는 표준 통로는 두 가지다.

9-1) @RegisteredOAuth2AuthorizedClient

컨트롤러 메서드 인자로 OAuth2AuthorizedClient를 주입받는다. 내부적으로 OAuth2AuthorizedClientArgumentResolver가 OAuth2AuthorizedClientManager.authorize(...)를 호출해서 만료 시 자동 refresh까지 처리한다.

@GetMapping("/calendar")
String calendar(@RegisteredOAuth2AuthorizedClient("google") OAuth2AuthorizedClient client) {
    String token = client.getAccessToken().getTokenValue();
    // 이 token으로 구글 Calendar API 호출
    return ...;
}

한 메서드 안에서 일회성으로 토큰을 꺼낼 때 쓴다. client.getRefreshToken()까지 꺼낼 수 있고, Manager가 만료를 확인해서 이미 갱신된 상태로 준다.

9-2) OAuth2AuthorizedClientExchangeFilterFunction

WebClient(또는 Spring Security 6.3+에서는 RestClient)에 필터로 꽂아 두면, 매 요청마다 토큰을 자동으로 Authorization: Bearer 헤더로 붙이고 만료되면 refresh한다.

@Bean
WebClient googleApi(OAuth2AuthorizedClientManager manager) {
    ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2 =
        new ServletOAuth2AuthorizedClientExchangeFilterFunction(manager);
    oauth2.setDefaultClientRegistrationId("google");

    return WebClient.builder()
        .apply(oauth2.oauth2Configuration())
        .build();
}

// 사용처
String resp = googleApi.get()
    .uri("https://www.googleapis.com/calendar/v3/...")
    .retrieve()
    .bodyToMono(String.class)
    .block();

필터가 현재 요청의 SecurityContext에서 principal을 찾아 해당 OAuth2AuthorizedClient를 자동으로 꺼낸다. setDefaultClientRegistrationId("google")로 기본 registration을 지정하거나, 호출마다 .attributes(clientRegistrationId("google"))로 지정한다.

배치/스케줄러처럼 HTTP 문맥이 없는 곳에서 이 필터를 쓰려면 AuthorizedClientServiceOAuth2AuthorizedClientExchangeFilterFunction을 쓰고 Manager도 service 기반으로 붙여야 한다.

10) PKCE: public client와 Spring Security 6의 권장

Authorization Code Flow의 변형으로 **PKCE (Proof Key for Code Exchange, RFC 7636)**가 있다. 원래는 public client(모바일 앱, SPA)가 client secret을 안전하게 못 들고 있어서 생긴 해결책이다.

10-1) 원리

브라우저/앱이 리다이렉트 직전에 랜덤 code_verifier를 생성하고, 이걸 SHA-256으로 해시한 code_challenge를 authorization request에 포함시킨다. IdP가 이 code_challenge를 code에 묶어 기억. 나중에 토큰 교환 시점에 원본 code_verifier를 같이 보내면 IdP가 해시를 다시 계산해서 초기 값과 맞는지 확인한다. 중간에 code를 탈취해도 code_verifier가 없으면 토큰으로 못 바꾼다.

10-2) Spring Security에서 활성화

Spring Security 6부터는 confidential client(서버 측 앱)에도 PKCE가 권장된다. ClientAuthenticationMethod.NONE으로 설정하면 자동으로 PKCE가 켜지고, confidential 클라이언트로 켜고 싶으면 OAuth2AuthorizationRequestResolver를 커스터마이즈한다.

@Bean
OAuth2AuthorizationRequestResolver pkceResolver(ClientRegistrationRepository clients) {
    DefaultOAuth2AuthorizationRequestResolver resolver =
        new DefaultOAuth2AuthorizationRequestResolver(clients, "/oauth2/authorization");
    resolver.setAuthorizationRequestCustomizer(
        OAuth2AuthorizationRequestCustomizers.withPkce());
    return resolver;
}

// http.oauth2Login(...).authorizationEndpoint(e -> e.authorizationRequestResolver(resolver))

OAuth2AuthorizationRequestCustomizers.withPkce()가 code_verifier를 생성해 OAuth2AuthorizationRequest.additionalParameters에 넣고, 토큰 교환 시에 그대로 전달되도록 붙여준다. code_verifier는 AuthorizationRequestRepository(세션)에 요청과 함께 저장돼 있다가 콜백 때 꺼내진다.

10-3) 왜 confidential에도 권장인가

PKCE가 client secret을 대체하는 게 아니라 code 탈취 공격에 대한 추가 방어층이기 때문이다. 서버 측 앱이라도 내부망 프록시나 로그를 통해 code가 유출될 수 있고, PKCE는 그 상황에서도 교환을 무력화시킨다. 설정 비용이 거의 없으므로 기본으로 켜는 것이 현재 업계 권장이다.

11) OIDC Logout과 OidcClientInitiatedLogoutSuccessHandler

Spring Security의 /logout은 기본적으로 내 앱의 세션만 끊는다. SecurityContextHolder를 비우고, JSESSIONID 쿠키를 만료시킨다. 그런데 사용자가 IdP에서도 로그인돼 있는 상태라면 IdP 세션은 여전히 살아있다. 직후에 로그인 버튼을 다시 누르면 IdP는 "이미 로그인되어 있으므로 동의 화면 없이 바로 code 발급"을 한다. 체감상 로그아웃이 안 된 것처럼 보인다. 들어가며의 세 번째 함정이다.

이걸 해결하려면 OIDC RP-Initiated Logout(IdP의 end_session_endpoint를 호출)을 써야 한다. Spring Security는 OidcClientInitiatedLogoutSuccessHandler로 이걸 지원한다.

@Bean
SecurityFilterChain web(HttpSecurity http,
                         ClientRegistrationRepository clients) throws Exception {
    OidcClientInitiatedLogoutSuccessHandler handler =
        new OidcClientInitiatedLogoutSuccessHandler(clients);
    handler.setPostLogoutRedirectUri("{baseUrl}/");

    return http
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .oauth2Login(Customizer.withDefaults())
        .logout(logout -> logout
            .logoutSuccessHandler(handler))
        .build();
}

동작은 이렇게 간다. 사용자가 /logout을 누르면 Spring Security가 로컬 세션을 비우고, success handler가 IdP의 end_session_endpoint로 리다이렉트를 만든다. URL에는 id_token_hint(방금 로그인에 쓰였던 ID Token)와 post_logout_redirect_uri가 붙는다. IdP가 자기 세션을 비우고 post_logout_redirect_uri로 다시 리다이렉트. 여기서도 {baseUrl} placeholder를 쓰면 환경별 하드코딩이 사라진다.

주의할 점 — post_logout_redirect_uri는 IdP 측에 사전 등록되어 있어야 한다(대부분의 IdP가 화이트리스트를 요구). 안 맞으면 IdP가 리다이렉트를 거부한다. 로컬/스테이징/프로덕션 각 URL을 전부 IdP 콘솔에 등록해 둔다.

SSO 환경에서 "로그아웃이 덜 된 것 같다"는 리포트가 올라오면 90% 이 handler를 안 붙인 경우다.

12) 실무에서 이렇게 읽고 쓴다

redirect-uri는 무조건 {baseUrl}/login/oauth2/code/{registrationId}로 쓴다. 환경별 yml 분기 없이 로컬/스테이징/프로덕션이 자동으로 맞춰진다. 반대로 IdP 콘솔에는 전부 등록해 둔다.
issuer-uri 한 줄로 시작한다. OIDC IdP(Keycloak, Auth0, 구글)는 discovery가 되므로 provider 블록에 issuer-uri만 넣으면 authorization/token/userinfo/jwks 전부 채워진다.
멀티 인스턴스면 세션 저장을 분리한다. Spring Session + Redis가 가장 단순하다. 그게 싫으면 JdbcOAuth2AuthorizedClientService + AuthenticatedPrincipalOAuth2AuthorizedClientRepository로 DB에 저장한다. sticky session은 임시방편이다.
/logout에는 OidcClientInitiatedLogoutSuccessHandler를 붙인다. 안 붙이면 IdP 세션이 남아서 재로그인 시 동의 없이 통과된다. SSO 환경에서 반드시.
외부 API 호출은 WebClient + ServletOAuth2AuthorizedClientExchangeFilterFunction. 수동으로 client.getAccessToken().getTokenValue()를 붙이는 패턴은 refresh를 직접 처리해야 해서 잔버그가 난다. 필터를 쓰면 만료 시 Manager가 자동으로 refresh.
PKCE를 confidential 클라이언트에도 켠다. OAuth2AuthorizationRequestCustomizers.withPkce() 한 줄이다. 보안상의 추가층이고 비용이 거의 없다.
권한은 userAuthoritiesMapper보다 oidcUserService/oauth2UserService를 커스텀하는 쪽이 디버깅하기 좋다. 권한 원천을 한 군데로 모으고, 테스트에서 user service를 mock하면 권한 분기까지 단번에 검증된다.
디버깅은 org.springframework.security.oauth2.client와 org.springframework.web.client를 DEBUG. authorization request 생성, state 검증, token endpoint 호출까지 로그에 남는다. 네트워크 탭과 교차로 보면 3번의 리다이렉트가 투명하게 그려진다.
refresh token은 보통 DB에 저장되므로 암호화 또는 별도 보호를 고려한다. 탈취 시 access token을 계속 재발급할 수 있으니 무기한 쿠키처럼 다뤄선 안 된다. DB 컬럼 레벨 암호화 또는 KMS 연동이 일반적이다.

13) 한 줄 정리

OAuth2 Client의 전체 동작은 OAuth2AuthorizationRequestRedirectFilter(앱→IdP)와 OAuth2LoginAuthenticationFilter(콜백→토큰 교환) 두 필터의 합주로 끝나고, 결과물은 SecurityContextHolder의 OAuth2User와 OAuth2AuthorizedClientRepository의 토큰으로 분리 저장된다. 외부 API 호출은 OAuth2AuthorizedClientManager 한 개가 만료 확인 + refresh까지 맡고, WebClient 필터에 꽂으면 자동으로 Bearer가 붙는다. redirect-uri는 {baseUrl} placeholder, 멀티 인스턴스는 세션 공유, 로그아웃은 OidcClientInitiatedLogoutSuccessHandler — 이 세 가지가 실무에서 90% 이상의 함정을 없앤다.

태그: spring-security, oauth2, oauth2-client, authorization-code, oidc, pkce, client-registration, authorized-client, webclient, spring-boot

상어코딩

Oracle 아키텍처 해부 — SGA·PGA·백그라운드 프로세스와 RAC의 기반

Oracle 아키텍처 해부 — SGA·PGA·백그라운드 프로세스와 RAC의 기반

들어가며

목차

1) 연결 모델 네 가지: Dedicated·Shared·Threaded·DRCP

1-1) Dedicated Server — 표준 모델

1-2) Shared Server — "MTS"가 아니다

1-3) Threaded Execution — 12c+ Linux 전용

1-4) DRCP — 웹·API 워크로드용 커넥션 풀

1-5) 네 모델 비교와 선택 기준

2) SGA 해부: 여섯 영역과 그 쓰임

2-1) 여섯 영역과 역할

2-2) AMM vs ASMM — 메모리 자동화의 두 단계

2-3) Shared Pool의 세 덩어리

2-4) Redo Log Buffer의 세 트리거

2-5) 관측의 라이선스 함정

3) PGA: 세션 사설 메모리와 두 개의 한도

3-0) UGA와 CGA — PGA 안의 두 하위 영역

3-1) 두 한도 — target과 limit

3-2) Work Area의 세 가지 실행 경로

4) 백그라운드 프로세스 생태계: 여덟 주연

4-1) 여덟 프로세스 요약

4-2) DBWR의 쓰기 네 조건

4-3) LGWR — 커밋의 동기 fsync

4-4) CKPT — 쓰지 않는 체크포인터

4-5) SMON·PMON·ARCn·RECO

5) SCN과 UNDO: 논리 시계와 Read Consistency

5-1) SCN — 64비트 단조 증가 논리 시계

5-2) UNDO Tablespace — 사전 이미지 창고

5-3) RETENTION GUARANTEE — 진짜 보장이 필요할 때

5-4) ORA-01555 — 구조적 장애

6) Library Cache: hard/soft parse와 ACS

6-1) CURSOR_SHARING — 세 가지 전략

6-2) ACS — Adaptive Cursor Sharing

6-3) library cache lock / pin — Oracle 고유 경합

7) RAC로 가는 길: 단일 인스턴스에서 공유 everything으로

8) 실무에서 이렇게 읽고 쓴다

9) 한 줄 정리

MySQL(InnoDB) 아키텍처 해부 — 스레드·버퍼 풀·redo/undo·purge·doublewrite·binlog

MySQL(InnoDB) 아키텍처 해부 — 스레드·버퍼 풀·redo/undo·purge·doublewrite·binlog

들어가며

목차

1) 스레드 모델: thread-per-connection과 handlerton

1-1) thread_handling 세 값

1-2) handlerton — 서버와 엔진 사이의 vtable 계약

1-3) binlog가 서버 레이어에 있는 이유

2) InnoDB 버퍼 풀: LRU midpoint·AHI·change buffer

2-1) LRU midpoint — full scan이 hot을 쫓아내지 않게

2-2) AHI — 적응형 해시 인덱스

2-3) change buffer — non-unique secondary index 전용

2-4) instance 분할 — 1GB 임계와 mutex contention

2-5) flush list와 dirty ratio

3) redo log: group commit 1층과 flush 전략

3-1) redo log 파일 — 8.0.30 이후 통합 파라미터

3-2) innodb_flush_log_at_trx_commit — 0/1/2의 실제 의미

3-3) group commit 1층 — redo log buffer 묶기

3-4) checkpoint와 flush 다이얼

3-5) redo capacity 사이징

4) doublewrite buffer: partial page write 방어선

4-1) 8.0.20 이후 분리된 파일

4-2) 오버헤드 — NVMe 5~10%, HDD 최대 30%

4-3) 오해 정리 — doublewrite는 무결성 전능이 아니다

4-4) atomic write 검증 체크리스트

5) undo tablespace와 purge thread

5-1) undo tablespace — 8.0부터 독립 파일

5-2) purge thread — MVCC 가비지 수집

5-3) undo truncate — 8.0 기본 ON

5-4) history list length 관측

6) binlog와 2PC: group commit 2층

6-1) 2PC 순서 — prepare, binlog, commit

6-2) group commit 2층 — FLUSH/SYNC/COMMIT 단계

6-3) binlog 사이징과 rotation

6-4) binlog_format — ROW가 기본

6-5) 병렬 복제 — WRITESET + preserve_commit_order

7) 실무에서 이렇게 읽고 쓴다

8) 한 줄 정리

gRPC Deadline · Cancellation · Context Deep Dive — 5쌍의 레이어가 동시에 서야 한다

gRPC Deadline · Cancellation · Context Deep Dive — 5쌍의 레이어가 동시에 서야 한다

들어가며

3-2) `innodb_flush_log_at_trx_commit` — 0/1/2의 실제 의미

3-4) `repeated`로 풀 수 있는 범위

5-2) StreamObserver 라이프사이클 — `onNext*` `(onError | onCompleted)`

5-3) `Status.asException`으로 명시적 에러 래핑

6-3) `isReady` / `setOnReadyHandler` — outbound flow control

6-5) `isCancelled` polling — 서버 쪽 취소 감지