풀소유

Codex App 개발 환경에 OmO, Codesight, agentmemory 붙이기

kyoulho — Sun, 31 May 2026 08:41:04 +0900

이 글의 기준은 Codex App / Codex Desktop이다. 터미널에서 codex를 직접 실행하는 Codex CLI 기준이 아니다.

Codex Desktop은 프로젝트 폴더를 열고, 여러 thread와 worktree를 병렬로 굴리는 데스크톱 작업 공간이다. 그래서 도구를 붙일 때도 CLI 기준으로 생각하면 헷갈린다.

내가 만들려는 구조는 이렇다.

Codex Desktop
→ 여러 thread/worktree로 작업한다.

Codesight
→ 프로젝트 구조를 미리 스캔해서 AI가 읽을 지도를 만든다.

agentmemory
→ thread와 세션 사이의 작업 기억을 이어준다.

OmO / LazyCodex
→ Codex lifecycle에 보조 hook/plugin을 붙인다.

왜 이 셋을 붙이는가

Codex Desktop을 쓰면 thread를 여러 개 만들 수 있다. 이건 강점이다. 하지만 thread가 많아지면 같은 문제가 반복된다.

프로젝트 구조를 매번 다시 읽는다.
이전 thread에서 실패한 접근을 다른 thread가 다시 시도한다.
작업 종료 후 다음 thread로 넘길 맥락이 사라진다.
어떤 문서가 진짜 기준인지 헷갈린다.

그래서 역할을 나눈다.

도구	무엇을 해주는가	왜 필요한가
Codesight	코드베이스 지도를 만든다	새 thread가 프로젝트 구조를 빨리 이해하게 한다
agentmemory	작업 기억을 저장하고 검색한다	이전 thread의 결정·실패·handoff를 이어받게 한다
OmO	Codex hook/plugin으로 실행 보조를 붙인다	rules, checker, LSP, ultrawork, continuation 같은 보조 기능을 쓴다

Codex Desktop 기준 작업 흐름

Codex Desktop에서는 보통 이렇게 작업한다.

1. 앱에서 프로젝트 폴더를 연다.
2. thread를 만든다.
3. Codex가 별도 worktree에서 작업한다.
4. 변경사항을 리뷰한다.
5. 필요하면 반영하거나 버린다.

여기에 세 도구를 붙이면 흐름은 이렇게 바뀐다.

1. 프로젝트 루트에 AGENTS.md와 docs/**를 둔다.
2. Codesight로 .codesight/wiki를 만든다.
3. agentmemory 서버를 띄우고 MCP를 연결한다.
4. 필요하면 agentmemory hook을 연결한다.
5. OmO/LazyCodex를 설치한다.
6. Codex Desktop thread 시작 시 AGENTS.md, Codesight, memory를 읽게 한다.
7. 작업 종료 전 handoff를 남긴다.

CLI 명령을 아예 안 쓰는 것은 아니다. Codex Desktop을 쓰더라도 설치, 갱신, 서버 실행은 터미널에서 한다.

Codesight

무엇을 해주는가

Codesight는 코드베이스 지도를 만든다. Codex Desktop에서 새 thread를 만들면 thread는 프로젝트를 다시 이해해야 한다.

백엔드는 어디인가?
프론트엔드는 어디인가?
테스트는 어디인가?
도메인 문서는 어디인가?
어떤 파일을 먼저 읽어야 하는가?

Codesight는 이 탐색을 미리 해둔다.

프로젝트 스캔
→ .codesight/wiki 생성
→ Codex Desktop thread가 구조 파악용으로 읽음

즉, Codesight는 코드를 고치는 도구가 아니다.

Codesight = AI가 읽는 프로젝트 지도

어떻게 적용하는가

프로젝트 루트에서 실행한다.

npx codesight --wiki

생성 결과를 확인한다.

find .codesight -maxdepth 3 -type f | sort

AGENTS.md에는 짧게 적는다.

## Codesight

- .codesight/wiki가 있으면 구조 파악용으로 읽어라.
- Codesight 결과물은 Source of Truth가 아니다.
- 정책 판단은 AGENTS.md와 docs/**에서 다시 확인해라.

코드 변경 시 어떻게 하는가

Codesight는 생성 산출물이다. 코드가 바뀌면 지도도 낡는다. 하지만 모든 수정마다 돌릴 필요는 없다.

작은 버그 수정
→ 갱신 안 함

문서 구조 변경
→ npx codesight --wiki

패키지 구조 변경
→ npx codesight --wiki

큰 리팩토링 전
→ npx codesight --wiki

큰 리팩토링 중 구조가 계속 바뀜
→ npx codesight --watch

커밋마다 자동 갱신
→ 기본값으로 쓰지 않음

--hook은 조심한다.

npx codesight --hook

커밋마다 Codesight 생성 파일이 바뀌면 커밋 범위가 지저분해질 수 있다. 개인 프로젝트에서는 처음부터 hook을 기본값으로 둘 필요 없다.

Codex Desktop worktree 주의점

Codex Desktop은 thread별 worktree를 만들 수 있다. 그래서 Codesight를 실행할 때는 현재 갱신하려는 worktree 경로에서 실행해야 한다.

cd <codex-desktop-worktree-path>
npx codesight --wiki

원본 프로젝트 루트에서 만든. codesight/wiki와 Codex Desktop thread의 worktree 안 파일 상태가 다를 수 있다.

이 차이를 모르면 낡은 지도를 보고 작업하게 된다.

agentmemory

무엇을 해주는가

agentmemory는 작업 기억을 저장한다. Codex Desktop에서는 thread가 여러 개 생긴다. 그러면 이런 문제가 생긴다.

A thread에서 실패한 접근을 B thread가 다시 시도한다.
어제 thread에서 남긴 다음 작업을 오늘 thread가 모른다.
사용자가 금지한 방향을 다른 thread가 다시 제안한다.

agentmemory는 이런 기억을 저장하고 다시 꺼내게 한다.

저장할 것은 이 정도다.

완료한 작업
실패한 접근
다음 작업
주의사항
handoff
정책 문서 위치

저장하면 안 되는 것도 있다.

긴 로그 전문
비밀값
검증되지 않은 추측
docs에 없는 정책 단정
이미 docs에 있는 내용을 그대로 복붙한 장문

정책은 docs에 두고, memory에는 작업 기억과 정책 문서 위치를 남긴다.

어떻게 실행하는가

https://github.com/rohitg00/agentmemory 에서 확인한다. 나는 설치 방식을 선호하고 작업 중에는 터미널에서 agentmemory 서버를 항상 실행한다.

Codex Desktop에 어떻게 붙이는가

Codex Desktop에서 생각할 통로는 두 개다.

MCP
→ Codex Desktop이 memory를 검색하고 읽는 통로

hook
→ 작업 이벤트를 memory에 자동 기록하는 통로

처음에는 MCP부터 붙인다. 자동 기록보다 검색이 되는지 먼저 확인하는 게 낫다.

MCP 등록은 Codex Desktop 설정에서 하거나, 환경에 따라 다음 명령으로 Codex 설정에 추가한다.

codex mcp add agentmemory -- npx -y @agentmemory/mcp

AGENTS.md에도 추가한다.

## agentmemory

- agentmemory MCP가 연결되어 있다면 현재 프로젝트의 최근 memory를 검색해라.
- 검색 결과가 없으면 없다고 말해라.
- memory 내용이 AGENTS.md 또는 docs/**와 충돌하면 AGENTS.md와 docs/**를 우선한다.

hook까지 쓰려면 CodexApp의 훅 설정을 하면 된다.

아래 명령어는 Codex Desktop에서 plugin-local hook이 기대대로 동작하지 않을 때 global hook으로 우회 연결하는 용도다. 때문에 훅이 중복 등록되어 중복 호출될 수 있다. 잘 확인하고 실행하자

agentmemory connect codex --with-hooks

내 적용 순서는 이렇다.

1. agentmemory 서버 실행
2. MCP 연결
3. Codex Desktop thread에서 memory 검색 테스트
4. handoff를 수동으로 기록하도록 지시
5. 필요하면 hook 연결
6. hook이 실제로 기록하는지 확인

OmO / LazyCodex

무엇을 해주는가

OmO는 Codex 또는 OpenCode의 실행 흐름을 보조하는 harness다. Codex 쪽에서는 LazyCodex Light edition으로 붙는다.
설치하면 Codex plugin cache 아래에 OmO plugin이 들어가고, hooks/hooks.json을 통해 Codex lifecycle에 붙는다.

보통 이런 경로를 확인할 수 있다.

~/.codex/plugins/cache/sisyphuslabs/omo/<version>/hooks/hooks.json

Codex Desktop 기준에서 OmO에 기대하는 역할은 이렇다.

rules 보조
comment checker 보조
LSP 기반 피드백 보조
ultrawork / ulw 흐름 보조
작업 continuation 보조
telemetry
git-bash 보조

즉, OmO를 이렇게 보면 안 된다.

OmO = SparkShell

더 정확히는 이렇다.

OmO = Codex lifecycle 보조 hook/plugin 묶음

어떻게 설치하는가

Codex용 LazyCodex를 설치한다.

npx lazycodex-ai install

자동화 옵션까지 적용하려면 다음을 쓴다.

npx lazycodex-ai install --no-tui --codex-autonomous

설정이 들어갔는지 확인한다.

grep -n "omo" ~/.codex/config.toml
grep -n "plugin" ~/.codex/config.toml
ls ~/.codex

plugin cache를 확인한다.

find ~/.codex/plugins/cache/sisyphuslabs/omo -path '*/hooks/hooks.json'

omo 명령이 안 잡히면 PATH를 추가한다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

주의할 점도 있다.

Codex용
→ npx lazycodex-ai install

OpenCode용
→ bunx oh-my-openagent install

npx omo / bunx omo
→ 쓰지 않는다. 다른 패키지로 해석될 수 있다.

OmO를 실제로 어떻게 쓰는가

Codex Desktop에서 OmO는 별도 명령으로 매번 실행하는 도구가 아니다.

틀린 이해:
작업할 때마다 OmO 명령을 직접 실행한다.

맞는 이해:
OmO plugin/hook을 설치하고 승인한다.
Codex lifecycle에 붙은 보조 기능이 필요한 이벤트에서 개입하게 둔다.

ulw 또는 ultrawork 키워드를 써서 깊은 작업 모드를 유도하는 쪽이 현실적이다.
하지만 나는 훅으로 등록해서 사용중이다. thread가 작업하는 동안 발생하는 로그를 보면 에이전트가 필요한 명령을 판단해서 사용하는걸 볼 수 있다.

ulw: 이 작업을 끝까지 진행해라.
먼저 계획을 세우고, 작은 단위로 구현하고, 테스트 결과까지 확인해라.
중간에 멈추지 말고 실패 원인을 보고해라.

또는

ultrawork 모드로 진행해라.
작업 계획, 구현, 검증, 남은 리스크를 순서대로 보고해라.

AGENTS.md

도구를 설치해도 Codex Desktop이 알아서 잘 쓰지는 않는다. 명시적으로 사용방법을 가이드한다.

짧게 쓴다고 쓴건데... 너무 길다

# 저장소 작업 규칙

이 파일은 AI coding agent가 이 저장소에서 작업할 때 따르는 공통 규칙이다.

특정 도구나 실행 환경에 종속되지 않는다.  
Codex Desktop, Codex CLI, Cursor, Claude Code, OpenCode 등 어떤 에이전트가 실행되더라도 이 파일을 먼저 따른다.

---

## 문서와 도구의 우선순위

- **AGENTS.md**: 모든 에이전트가 항상 따르는 공통 작업 규칙.
- **docs/**: Source of Truth. 오래가는 제품·도메인·아키텍처 정책을 둔다.
- **Codesight**: 코드베이스 지도와 탐색 보조 도구. 생성 산출물이며 Source of Truth가 아니다.
- **agentmemory**: 최근 결정, 금지사항, 반복 회귀 원인, handoff, 세션 요약을 저장·조회하는 작업 메모리. Source of Truth가 아니다.
- **OmO / LazyCodex**: Codex lifecycle에 보조 hook/plugin을 붙이는 실행 보조 도구. Source of Truth가 아니다.

에이전트는 자신이 어떤 실행 환경에서 동작하는지 확실히 알 수 없으므로, 이 파일에서는 실행 환경별 역할을 전제하지 않는다.

---

## 기본 원칙

- Source of Truth는 `AGENTS.md`와 `docs/**`이다.
- Codesight, agentmemory, OmO 결과는 모두 보조 정보다.
- 보조 정보가 Source of Truth와 충돌하면 Source of Truth를 우선한다.
- 작업 범위는 사용자의 요청 범위로 제한한다.
- 오래가는 제품·도메인·아키텍처 정책은 docs에 둔다.
- 정책 변경이 필요한 작업은 docs를 먼저 수정한다.
- 단순 버그 수정에서 정책이 바뀌지 않으면 docs를 건드리지 않는다.
- 테스트 통과만으로 UI 완료를 선언하지 않는다.
- 실제 화면을 확인하지 못했으면 수동 확인 미완료라고 보고한다.
- 모르는 것을 추측해서 확정하지 않는다.
- 근거가 부족하면 부족하다고 보고하고, 확인 가능한 근거를 우선한다.

---

## 기본 작업 순서

작업자는 항상 다음 순서를 따른다.

1. `AGENTS.md`
2. 작업이 단순 문구 수정이 아니라면 agentmemory에서 관련 memory recall
3. `docs/README.md`가 있으면 읽는다
4. `docs/project/status.md`가 있으면 읽는다
5. `docs/project/roadmap.md`가 있으면 읽는다
6. `.codesight/wiki/index.md`가 있으면 읽는다
7. 현재 작업 entrypoint를 찾는다
8. `.codesight/wiki/*` 중 현재 작업과 직접 관련된 article 1~2개를 읽는다
9. 관련 `docs/architecture/*`가 있으면 읽는다
10. 필요 시 `docs/reference/*`를 읽는다
11. 필요한 원본 코드 파일을 읽는다

위 문서나 디렉터리가 없으면 없는 것으로 보고하고, 존재하는 문서를 기준으로 진행한다.

장기 결정 배경은 가능하면 `docs/project/decision-log.md`에 둔다.  
구현 근거는 현재 `docs/**`와 실제 코드를 우선한다.

---

## 문서 유지·삭제 정책

문서는 개발 판단과 구현에 직접 도움이 될 때만 유지한다.

삭제·이동 판단 기준은 다음과 같다.

- 현재 구현·정책·운영 판단에 쓰이지 않는 문서는 유지하지 않는다.
- Source of Truth를 반복하는 중복 문서는 하나로 합친다.
- 과거 결정 배경은 필요하면 decision log에 남기고, 긴 임시 문서는 삭제 또는 archive 처리한다.
- generated output은 재생성 가능한 산출물로 보고 수동 보존 가치를 두지 않는다.
- 삭제가 코드 탐색이나 정책 판단을 더 어렵게 만들면 삭제하지 않는다.
- 문서 삭제나 이동은 작업 보고에 명시한다.

---

## Codesight 사용 정책

Codesight는 코드 탐색 비용과 토큰 사용량을 줄이기 위한 보조 도구다.

Codesight output은 Source of Truth가 아니며, docs 또는 실제 코드와 충돌하면 docs와 실제 코드를 우선한다.

### 기본 원칙

- 세션 시작 시 `.codesight/CODESIGHT.md` 전체를 읽지 않는다.
- 먼저 `.codesight/wiki/index.md`만 읽고 현재 작업에 필요한 article을 고른다.
- 좁은 작업은 관련 wiki article 1개와 entrypoint 코드만 읽고 시작한다.
- 넓은 리팩토링, 영향도 분석, 구조 파악이 필요할 때만 Codesight graph/raw output을 추가로 참고한다.
- Codesight output이 stale로 보이면 stale 가능성을 보고하고, 실제 코드와 Source of Truth 문서를 기준으로 판단한다.
- Codesight 결과는 위치 탐색에 사용하고, 정책 판단에는 사용하지 않는다.

### 권장 사용 방식

- **Backend/API 작업**: `index.md` → 관련 route/service/database article → 관련 docs
- **Frontend/UI 작업**: `index.md` → 관련 page/component/state article → 관련 docs
- **DB/Migration 작업**: `index.md` → database article → 관련 migration과 roadmap
- **아키텍처 변경**: `index.md` → overview article → 관련 architecture docs
- **외부 연동 작업**: Codesight보다 먼저 `docs/reference/**`와 provider별 reference 문서를 확인한다.

### 금지

- 매 작업마다 `.codesight/CODESIGHT.md` 전체를 읽지 않는다.
- `.codesight/wiki/*`를 Source of Truth처럼 취급하지 않는다.
- `.codesight/` 아래에 사람이 작성한 수동 topic map을 만들거나 유지하지 않는다.
- generated Codesight raw output을 agentmemory에 저장하지 않는다.
- Codesight stale 가능성을 무시하고 구현 판단을 확정하지 않는다.

---

## agentmemory 사용 정책

agentmemory는 최근 결정, 금지사항, 반복 회귀 원인, handoff, 세션 요약을 저장·조회하는 작업 메모리다.

agentmemory는 Source of Truth가 아니다.  
agentmemory 내용이 `AGENTS.md` 또는 `docs/**`와 충돌하면 반드시 Source of Truth를 우선한다.

agentmemory는 다음 방식으로 사용할 수 있다.

- MCP를 통한 수동 recall/remember
- 세션 종료 시 자동 세션 요약
- hook 기반 자동 기록
- hook 기반 자동 요약
- 다음 세션 시작 시 최근 handoff/context recall

자동 기록과 자동 요약은 전체 로그를 무제한 저장하는 용도가 아니다.  
저장 대상은 다음 작업에 반복적으로 영향을 줄 짧은 맥락으로 제한한다.

### 작업 시작 시

단순 문구 수정이 아닌 작업은 시작 시 agentmemory를 recall한다.

다음 중 하나에 해당하면 작업 시작 시 반드시 agentmemory를 recall한다.

- 넓은 코드 변경
- 리팩토링
- 도메인 정책 변경
- 데이터 정합성 관련 변경
- 인증, 권한, 결제, 금융, 보안, 외부 연동 관련 변경
- 외부 provider ingest 또는 adapter 관련 변경
- 이전 회귀 가능성이 있는 버그 수정
- 사용자가 "전에 정한 것", "기존 정책", "최근 결정"을 언급한 작업
- 다음 작업자에게 이어질 가능성이 있는 작업

기본 recall 대상:

- PROJECT HOT
- PROJECT FORBIDDEN
- PROJECT HANDOFF
- 최근 세션 요약

필요 시 추가 recall 대상:

- PROJECT STALE
- 현재 작업 키워드
- 관련 도메인 키워드

recall한 memory는 최근 작업 맥락으로만 사용한다.

memory가 현재 docs와 충돌하거나 오래된 것으로 보이면 작업을 멈추고 stale 가능성을 보고한다.

agentmemory가 비활성화되어 있거나 recall에 실패해도 작업은 `AGENTS.md`와 docs 기준으로 진행하되, 보고서에 recall 실패를 명시한다.

### 작업 종료 시

작업 종료 시 agentmemory에 짧은 요약을 남길 수 있다.

특히 다음 중 하나가 생기면 remember한다.

- 새로 확정된 프로젝트 정책
- 반복 회귀 원인
- 금지된 구현 방식
- 다음 작업자가 알아야 할 짧은 handoff
- 향후 에이전트 작업에 반복적으로 영향을 줄 결정
- 현재 docs 반영 전까지 임시로 기억해야 할 주의사항
- 긴 작업을 중단하거나 다음 세션으로 넘겨야 하는 경우의 현재 상태

정책이 바뀌지 않은 일반 구현 작업이라도, 다음 세션에서 바로 이어서 작업할 가능성이 있으면 짧은 HANDOFF를 남길 수 있다.

### 자동 세션 요약 / hook 사용

agentmemory hook 기반 자동 기록·자동 요약은 사용할 수 있다.

다만 hook은 다음 원칙을 따른다.

- 전체 세션 로그를 장기 memory로 그대로 저장하지 않는다.
- 최종 요약은 짧은 handoff 중심으로 남긴다.
- 장기 정책은 PROJECT HOT 또는 PROJECT FORBIDDEN으로 명시적으로 저장한다.
- 임시 디버깅 과정, 긴 테스트 출력, raw response, credential, 로컬 DB 값은 저장하지 않는다.
- Codesight raw output은 저장하지 않는다.
- 자동 요약 내용이 Source of Truth와 충돌하면 Source of Truth를 우선하고 memory를 stale로 표시한다.

### 저장할 수 있는 memory

- 새로 확정된 프로젝트 정책
- 반복 회귀 원인
- 금지된 구현 방식
- 다음 작업자가 알아야 할 짧은 handoff
- 향후 에이전트 작업에 반복적으로 영향을 줄 결정
- stale 가능성이 확인된 과거 결정
- 다음 세션에서 이어서 작업하기 위한 짧은 세션 요약

### 저장하지 않는 memory

- API key, app secret, token, credential
- 계좌번호 전체, 주민번호, 식별 가능한 민감정보
- raw API response
- local DB 내용
- agent 실행 로그 전문
- 긴 테스트 출력
- 전체 작업 보고서 전문
- 임시 디버깅 메모 전체
- 곧 바뀔 가능성이 높은 구현 세부사항
- generated Codesight raw output
- Codex/Cursor/Claude 세션 전체 원문

### Memory 형식

memory는 짧고 명시적으로 작성한다.

권장 prefix:

- **PROJECT HOT**: 현재 유효한 작업 규칙
- **PROJECT FORBIDDEN**: 금지된 구현 방식
- **PROJECT HANDOFF**: 다음 작업자가 알아야 할 짧은 인계
- **PROJECT STALE**: 더 이상 유효하지 않은 과거 결정
- **PROJECT SUMMARY**: 다음 세션 연결을 위한 짧은 세션 요약

예시:

- PROJECT HOT: Workspace-affecting mutations must update local state, not only refresh the router.
- PROJECT FORBIDDEN: Do not restore deprecated fallback path.
- PROJECT HANDOFF: Current work stopped after adding provider ingest tests; next step is wiring mapper integration.
- PROJECT SUMMARY: Session focused on docs, Codesight/wiki, and agentmemory policy; Source of Truth remains AGENTS.md and docs.

---

## OmO / LazyCodex 사용 정책

OmO / LazyCodex는 Codex lifecycle 보조 hook/plugin이다. Source of Truth가 아니다.

- OmO를 SparkShell 자동 압축 도구로 전제하지 않는다.
- Codex Desktop에서는 SparkShell은 CLI에서만 사용 가능한 것으로 보이며, 기본 Bash 출력에 자동 개입한다고 가정하지 않는다.
- `ulw` 또는 `ultrawork` 키워드는 긴 작업 모드 유도에 사용할 수 있다.
- OmO hook/plugin 동작은 실제 실행 결과로 확인한다.
- OmO 결과가 `AGENTS.md` 또는 `docs/**`와 충돌하면 `AGENTS.md`와 `docs/**`를 우선한다.
- OmO가 없거나 동작하지 않아도 작업은 `AGENTS.md`와 docs 기준으로 진행한다.

Spring @Bean메서드 직접 호출은 일반 Java 호출과 다르다

kyoulho — Wed, 27 May 2026 20:21:58 +0900

Spring의 @Configuration 클래스 안에서 @Bean 메서드를 직접 호출하면, 일반 Java 메서드 호출처럼 보이지만 실제로는 다르게 동작할 수 있다. 핵심은 @Configuration(proxyBeanMethods = true)와 Spring proxy다.

문제 코드

@Bean
public Job reportJob() {
    return new JobBuilder("reportJob", jobRepository)
            .start(reportStep(null))
            .build();
}

@Bean
@JobScope
public Step reportStep(
        @Value("#{jobParameters['reportDate']}") String reportDate
) {
    return new StepBuilder("reportStep", jobRepository)
            .tasklet((contribution, chunkContext) -> {
                System.out.println("reportDate = " + reportDate);
                return RepeatStatus.FINISHED;
            }, transactionManager)
            .build();
}

겉으로는 reportStep(null)이다. 순수 Java라면 당연히 reportDate는 null이어야 한다. 그런데 Spring Batch에서 JobParameter를 넘기면 실제 값이 출력될 수 있다.

./gradlew bootRun --args='--spring.batch.job.name=reportJob reportDate=2026-05-27'

reportDate = 2026-05-27

이유

null이 실제 Step 객체에 들어간 것이 아니다. @Configuration(proxyBeanMethods = true)에서는 Spring이 @Bean 메서드 호출을 CGLIB proxy로 가로챌 수 있다. 그리고 @JobScope가 붙은 Bean은 애플리케이션 시작 시점에 실제 객체가 만들어지지 않는다. 대신 scoped proxy가 먼저 들어간다. 흐름은 이렇다.

애플리케이션 시작
→ reportStep(null)처럼 보이는 호출 발생
→ 실제 Step 생성 X
→ scoped proxy 반환

Job 실행
→ JobScope 활성화
→ JobParameters 사용 가능
→ 실제 Step delegate 생성
→ reportDate 값 바인딩

즉 핵심은 이것이다.

null은 delegate에 전달되지 않았다.
null은 proxy를 얻는 과정의 더미 인자에 가깝다.
실제 객체는 scope가 활성화된 뒤 생성된다.

proxyBeanMethods = false 면 다르다

@Configuration(proxyBeanMethods = false)

이면 @Bean 메서드 직접 호출을 Spring이 가로채지 않는다. 그러면 다음 호출은 정말 일반 Java 메서드 호출처럼 동작할 수 있다.

reportStep(null)

정리하면 다음과 같다.

설정	@Bean 직접 호출
proxyBeanMethods = true	Spring proxy가 가로챌 수 있음
proxyBeanMethods = false	일반 Java 호출처럼 동작할 수 있음
@Component 내부 메서드 호출	일반 Java 호출

권장 방식

@Bean 메서드에 null을 넘기는 코드는 동작할 수 있어도 읽기 어렵다. 이렇게 쓰는 편이 낫다.

@Bean
public Job reportJob(Step reportStep) {
    return new JobBuilder("reportJob", jobRepository)
            .start(reportStep)
            .build();
}

그리고 Spring Batch에서는 더 좋은 구조가 있다.

Job과 Step은 구조 정의 객체로 두고, 실행 시점 값이 필요한 Tasklet, Reader, Writer에 scope를 붙인다.

@Bean
public Step reportStep(Tasklet reportTasklet) {
    return new StepBuilder("reportStep", jobRepository)
            .tasklet(reportTasklet, transactionManager)
            .build();
}

@Bean
@StepScope
public Tasklet reportTasklet(
        @Value("#{jobParameters['reportDate']}") String reportDate
) {
    return (contribution, chunkContext) -> {
        System.out.println("reportDate = " + reportDate);
        return RepeatStatus.FINISHED;
    };
}

결론

@Bean 메서드 직접 호출은 일반 Java 호출처럼 보이지만, Spring proxy 때문에 실제 의미가 달라질 수 있다. 특히 scoped proxy가 끼면 null을 넘긴 것처럼 보여도 실제 delegate는 나중에 scope가 활성화된 뒤 생성된다. 실무 원칙은 간단하다.

@Bean 메서드 직접 호출에 의존하지 말 것.
Job/Step은 scope 없이 둔다.
실행 시점 값은 Tasklet/Reader/Writer 같은 하위 Bean에 @StepScope로 주입한다.

[종목 검색 API] 5. Redis Sentinel과 CircuitBreaker 장애 대응 실험

kyoulho — Tue, 26 May 2026 20:09:03 +0900

Redis Sentinel

Redis Sentinel은 Redis master 장애를 감지하고 replica를 새 master로 승격시키는 HA 구조다. Redis Cluster처럼 데이터를 여러 노드에 분산 저장하는 구조가 아니다.

구분	Redis Sentinel	Redis Cluster
목적	master 장애 대응	sharding + HA
데이터 분산	없음	있음
주요 기능	failover	hash slot 분산
적합한 상황	단일 Redis의 HA	Redis 용량·처리량 분산

Redis cache-aside 구조에서는 Redis가 정상일 때 반복 검색어를 캐시로 흡수한다. 하지만 Redis가 죽으면 cache layer가 사라지고 DB fallback이 증가한다. 따라서 이번 실험의 대상은 Redis Cluster가 아니라 Redis Sentinel이다.

실험 조건

한국투자증권 Open API에서 제공하는 실제 종목 데이터를 사용했다. 해당 데이터를 Batch로 적재해 stock_master 테이블에 저장했고, 총 9,092건의 종목 데이터를 기준으로 실험했다.

부하는 k6로 주었다.

시나리오: 30s@10 -> 1m@30 -> 30s@0
장애 주입: 시작 후 75초에 Redis master stop
Redis timeout: 100ms
Sentinel 구성: master 1 / replica 1 / sentinel 2

확인한 지표는 다음이다.

p95 / p99
DB query count
Redis get/set error
CircuitBreaker bypassed get

장애 흐름

Sentinel 환경의 Redis master 장애 흐름은 다음과 같다.

Redis master 장애
→ Sentinel failover 진행
→ Redis get/set error 발생
→ CircuitBreaker OPEN
→ Redis 호출 bypass
→ DB fallback 증가

Sentinel은 Redis master를 복구한다. 하지만 CircuitBreaker가 OPEN 상태라면 애플리케이션은 복구된 Redis를 호출하지 않는다.

Sentinel은 HA 계층이고, CircuitBreaker는 장애 격리 계층이다. 둘은 대체 관계가 아니다.

Sentinel의 효과를 보려면 CircuitBreaker가 복구된 Redis로 돌아갈 수 있어야 한다.

기존 CircuitBreaker 설정

설정	값	의미
sliding window type	COUNT_BASED	실패율을 시간 기준이 아니라 최근 호출 개수 기준으로 계산한다.
sliding window size	20	최근 Redis 호출 20개를 기준으로 실패율을 계산한다.
minimum number of calls	10	최소 10번 이상 호출이 쌓여야 실패율을 계산한다. 호출 수가 너무 적을 때 성급하게 OPEN 되는 것을 막는다.
failure rate threshold	50	최근 호출 중 실패율이 50% 이상이면 CircuitBreaker를 OPEN 한다.
wait duration in open state	10s	OPEN 상태가 되면 10초 동안 Redis 호출을 차단한다.
permitted calls in half-open	3	10초가 지난 뒤 HALF_OPEN 상태에서 Redis에 시험 호출 3개를 허용한다.
automatic transition	true	OPEN 상태에서 10초가 지나면 자동으로 HALF_OPEN으로 전환한다.
Redis timeout	100ms	Redis 명령이 100ms 안에 끝나지 않으면 실패로 본다.

Sentinel 환경에서는 OPEN에서 HALF_OPEN으로 전환되는 시점이 중요하다. 너무 빨리 Redis를 다시 호출하면 failover가 끝나기 전에 error가 증가한다. 너무 늦게 Redis를 다시 호출하면 Redis가 복구됐는데도 DB fallback을 계속 탄다.

후보 선정

이전 실험에서는 주로 Redis 복귀 시점을 앞당기는 방향을 확인했다. 하지만 CircuitBreaker 튜닝에는 다른 축도 있다. Redis 장애를 얼마나 빠르게 감지하고 차단할 것인가다. slidingWindowSize와 minimumNumberOfCalls를 줄이면 더 적은 샘플로 실패율을 판단한다.
장애 감지는 빨라질 수 있지만, 일시적인 오류에도 민감해질 수 있다. 이번에는 복귀 시점과 장애 감지 민감도를 함께 비교했다.

후보	설계 의도
A baseline-current	현재 설정 기준선
B faster-wait	waitOpen만 줄였을 때 Redis 복귀가 빨라지는지 확인
C stable-window	waitOpen을 줄이되 window, minCalls를 키워 일시 오류에 덜 민감해지는지 확인
D balanced-probe	C에서 halfOpen probe만 늘렸을 때 회복 확인이 나아지는지 확인
E sensitive-window	window, minCalls를 줄였을 때 장애 감지가 빨라지는지 확인
F sensitive-recovery	민감한 감지와 빠른 복귀를 같이 적용했을 때의 변화 확인
G medium-sensitive	A와 E 사이의 중간 민감도 확인

후보별 설정은 다음과 같다.

후보	waitOpen	halfOpen	slidingWindow	SizeminCalls	failRate
A baseline-current	10s	3	20	10	50
B faster-wait	5s	3	20	10	50
C stable-window	6s	3	30	12	50
D balanced-probe	6s	4	30	12	50
E sensitive-window	10s	3	10	5	50
F sensitive-recovery	6s	3	10	5	50
G medium-sensitive	8s	3	15	8	50

Redis timeout은 모든 후보에서 100ms로 고정했다. 이번 실험에서는 Redis timeout이 아니라 CircuitBreaker 회복 정책을 비교한다.

측정 결과

후보별 3회 측정 결과의 평균은 다음과 같다.

후보	p95 평균	p99 평균	DB query 평균	get_error 평균	set_error 평균
A	22.90ms	239.41ms	960.33	18.67	9.00
B	27.54ms	175.77ms	946.67	28.67	13.67
C	30.96ms	245.57ms	943.33	30.67	14.33
D	30.52ms	275.08ms	945.33	36.00	19.00
E	27.40ms	190.24ms	953.67	15.67	7.00
F	28.69ms	229.31ms	940.67	24.33	9.33
G	31.56ms	282.83ms	926.33	25.00	8.33

HTTP 실패율은 모든 후보에서 0이었다.

결과 해석

A baseline-current

A는 기존 설정이다.

p95 평균은 22.90ms로 가장 낮다.

다만 get_error 평균은 18.67이고, set_error 평균은 9.00이다.

기준선으로 나쁘지 않지만, cache error 관점에서는 개선 여지가 있었다.

B faster-wait

B는 waitOpen만 10초에서 5초로 줄인 후보다.

p99 평균은 낮아졌지만, get_error와 set_error가 모두 증가했다.

Redis 복귀를 앞당긴 효과보다, failover 직후 Redis를 다시 호출하면서 생기는 error 증가가 더 컸다.

C stable-window

C는 waitOpen을 6초로 줄이고, slidingWindowSize와 minimumNumberOfCalls를 키웠다.

DB query 평균은 A보다 낮아졌지만, p95와 cache error가 증가했다.

실패율 판단을 둔감하게 만든다고 장애 구간 안정성이 좋아지지는 않았다.

D balanced-probe

D는 C에서 halfOpen probe를 3에서 4로 늘린 후보다.

get_error와 set_error가 후보 중 가장 높다.

half-open probe를 늘리면 Redis 회복 확인은 더 적극적으로 할 수 있지만, failover 직후 불안정한 Redis에 더 많은 요청을 보낼 수 있다. 이번 조건에서는 불리했다.

E sensitive-window

E는 slidingWindowSize를 20에서 10으로, minimumNumberOfCalls를 10에서 5로 줄인 후보다.

waitOpen과 halfOpen은 기존 설정과 동일하게 유지했다. p95는 A보다 높지만, get_error와 set_error가 후보 중 가장 낮다. E는 장애 감지를 더 민감하게 하면서도 Redis 복귀 시점은 기존처럼 보수적으로 유지한 설정이다. 이번 실험에서는 이 조합이 가장 안정적이었다.

지표	A	E
p95 평균	22.90ms	27.40ms
p99 평균	239.41ms	190.24ms
DB query 평균	960.33	953.67
get_error 평균	18.67	15.67
set_error 평균	9.00	7.00

F sensitive-recovery

F는 E에서 waitOpen을 10초에서 6초로 줄인 후보다.

DB query 평균은 가장 낮은 편이지만, get_error가 E보다 크게 증가했다.

민감한 장애 감지와 빠른 복귀를 같이 적용하면 Redis error가 다시 늘어난다.

G medium-sensitive

G는 A와 E 사이의 중간 민감도 후보다.

DB query 평균은 가장 낮지만, p95와 p99가 모두 느린 편이다.

set_error는 낮지만 get_error가 높아 선택 후보로 보기는 어렵다.

선택 후보

이번 실험에서는 E sensitive-window를 선택한다.

설정	값
wait duration in open state	10s
permitted calls in half-open	3
sliding window size	10
minimum number of calls	5
failure rate threshold	50
Redis timeout	100ms

E는 Redis 복귀 시점을 앞당기지 않았다. 대신 장애 감지 window를 줄였다. 즉 “더 빨리 Redis로 돌아가는 설정”이 아니라, “장애 Redis를 더 빨리 차단하는 설정”이다. 이번 측정에서는 이 방향이 더 안정적이었다.

B, F처럼 waitOpen을 줄인 후보는 Redis 복귀를 앞당겼지만 error가 증가했다.

C, D처럼 window를 키운 후보도 p95와 error 측면에서 불리했다.

E는 get/set error가 가장 낮고, p99 평균도 A보다 낮다.

현재 실험 조건에서는 E가 가장 안정적인 선택이다.

운영 반영 기준

이번 결과는 현재 조건에서의 선택이다. 운영 반영 전에는 같은 지표를 다시 본다.

p95 / p99
DB query count
get_error / set_error
bypassed_get
HTTP 실패율

운영에서는 Redis 배포 방식, 네트워크 지연, 실제 검색 트래픽이 달라질 수 있다.

따라서 운영값은 운영 관측치를 기준으로 확정한다.

정리

Redis 장애 대응은 한 계층으로 끝나지 않는다.

Redis timeout은 응답 대기 시간을 제한한다.
CircuitBreaker는 장애 Redis 호출을 막는다.
Sentinel은 Redis master를 복구한다.
DB fallback은 최종 방어선이다.
Sentinel을 붙였다고 CircuitBreaker가 필요 없어지는 것이 아니다.
CircuitBreaker가 있다고 Sentinel이 필요 없어지는 것도 아니다.
Sentinel의 효과를 보려면 CircuitBreaker가 복구된 Redis로 돌아갈 수 있어야 한다.

이번 실험에서는 Redis로 더 빨리 돌아가는 후보보다, 장애 감지를 더 민감하게 하는 후보가 더 안정적이었다.

현재 실험 조건에서는 E 설정을 다음 운영 검증 후보로 둔다.

[종목 검색 API] 4. Redis 장애 격리 실험: Timeout과 CircuitBreaker로 충분했을까?

kyoulho — Sat, 23 May 2026 18:17:00 +0900

이전 글에서는 자동완성 검색 API에 Redis Cache를 붙이고 실제 입력 패턴으로 부하 테스트를 진행했다.

자동완성 API의 1차 방어선은 Redis가 아니라 debounce였다. debounce를 적용하자 API 요청 수와 DB query count가 크게 줄었다.

하지만 Redis 장애 테스트에서는 다른 문제가 드러났다. Redis가 운영 중 내려가자 API 실패율은 0%였지만, p95와 p99가 크게 튀었다.

DB 검색 쿼리 평균 실행 시간은 12.05ms 수준이었다. 즉 전체 지연의 핵심은 DB 자체가 아니었다. 문제는 Redis 장애 시 매 요청마다 Redis get/set 실패를 기다리는 구조였다. 그래서 이번 글에서는 Redis timeout을 줄이고, CircuitBreaker를 적용했다.

기존 문제: fallback은 실패율을 막지만 latency는 막지 못한다

기존 구조는 cache-aside였다.

request
→ Redis get
    hit  → return
    miss → DB search
→ Redis set
→ response

Redis가 정상일 때는 문제가 없다. 하지만 Redis가 죽으면 흐름이 달라진다.

request
→ Redis get 실패 대기
→ local stock_master search
→ Redis set 실패 대기
→ response

fallback은 동작한다. 그래서 API는 5xx를 내지 않는다. 하지만 사용자는 느려진 응답을 그대로 맞는다.

이게 fallback만으로 부족한 이유다.

fallback = 실패율 방어
circuit breaker = 장애 전파 시간 방어

둘은 다르다. fallback은 “서비스가 죽지 않게” 만든다. CircuitBreaker는 “계속 기다리지 않게” 만든다.

적용한 개선

Redis timeout 단축

먼저 Redis command timeout을 짧게 가져갔다.

spring:
  data:
    redis:
      timeout: 100ms

Redis가 죽었을 때 오래 기다리지 않는다. 자동완성 API에서 Redis는 성능 최적화 계층이다.

Redis가 느리거나 죽었다고 검색 API가 Redis를 오래 기다리면 안 된다.

CircuitBreaker 적용

그 다음 Redis cache adapter 앞에 Resilience4j CircuitBreaker를 뒀다. 구조는 다음과 같다.

StockSearchCache
  └── CircuitBreakingStockSearchCache
        └── RedisStockSearchCache

동작 원칙은 다음이다.

상황	처리
Redis get 성공 + hit	cache hit 반환
Redis get 성공 + miss	null 반환, local stock_master 검색
Redis get 실패	null 반환, local stock_master 검색
CircuitBreaker OPEN	Redis 호출 생략, local stock_master 검색
Redis put 실패	예외 삼킴, API 응답 유지
CircuitBreaker OPEN 상태의 put	Redis set 생략

중요한 점은 서비스가 Redis 장애를 몰라도 된다는 것이다. StockSearchService는 여전히 이렇게만 본다.

val cached = cache.get(cacheKey)
if (cached != null) {
    return cached
}

val results = searchLocal(...)
cache.put(cacheKey, results, ttl)

return results

Redis 장애 격리는 cache adapter 내부 책임이다. 검색 서비스는 cache hit이면 반환하고, cache miss처럼 보이면 local DB를 조회한다.

Kotlin null 문제

구현 중 의외로 중요한 지점이 있었다. Redis cache miss는 정상적인 null이다.
그런데 Resilience4j의 executeSupplier에서 Kotlin null을 그대로 다루면 문제가 생길 수 있다.

그래서 miss를 별도 non-null wrapper로 감쌌다.

private sealed interface CacheLookup {
    data class Hit(val results: List<StockSearchResult>) : CacheLookup
    data object Miss : CacheLookup
}

이렇게 하면 구분이 명확해진다.

CacheLookup.Miss = 정상적인 cache miss
Exception = Redis 장애
CallNotPermittedException = CircuitBreaker OPEN

이 구분이 중요하다. cache miss를 실패로 잡으면 CircuitBreaker가 잘못 열린다. 반대로 Redis 장애를 miss처럼만 처리하면 장애 상태를 계속 반복한다.

재측정 결과

Redis timeout과 CircuitBreaker를 적용한 뒤 다시 테스트했다. 동일하게 debounced 입력 패턴으로 부하를 주고, 테스트 중간에 Redis를 중단했다. k6 결과는 다음과 같았다.

항목	값
k6 http_reqs	854
p95 latency	1.81s
p99 latency	30.78s
max latency	31.3s
http_req_failed	0.70%
DB search query count	601
DB mean_exec_time	15.43ms
PostgreSQL CPU avg	18.5%
PostgreSQL CPU max	76.8%
Redis CPU avg	1.3%
Redis CPU max	2.0%
Keycloak CPU avg	0.8%
Keycloak CPU max	1.9%

표면적으로 보면 애매하다. p95는 이전 Redis 장애 테스트보다 낮아졌다.

이전 p95 = 2.56s
개선 후 p95 = 1.81s

하지만 p99는 오히려 크게 튀었다.

이전 p99 = 3.55s
개선 후 p99 = 30.78s

즉 timeout과 CircuitBreaker만으로 문제가 끝나지는 않았다. 다만 이 결과를 바로 실패로 판단하면 안 된다. Redis metric을 같이 봐야 한다.

Redis Cache Metric 확인

테스트 후 Micrometer pwm.stock_search.cache.* metric은 다음과 같았다.

Metric	값
pwm.stock_search.cache.hit	248
pwm.stock_search.cache.miss	129
pwm.stock_search.cache.get_error	13
pwm.stock_search.cache.set_error	9
pwm.stock_search.cache.bypassed get	459
pwm.stock_search.cache.bypassed set	345

핵심은 이 부분이다.

get_error = 13
set_error = 9
bypassed = 804

Redis 장애 이후에도 Redis를 계속 때린 것이 아니다. 초반에 소수의 get/set 실패가 발생했고, 그 뒤에는 CircuitBreaker가 열리면서 Redis 호출을 우회했다.

즉 Redis CircuitBreaker 자체는 정상 동작했다. 기존에는 Redis 장애 후 매 요청마다 Redis 실패를 계속 맞았다. 이제는 장애를 감지한 뒤 Redis 호출을 생략한다.

그런데 왜 p99는 여전히 흔들렸나?

Redis CircuitBreaker는 동작했다. DB도 병목은 아니었다. PostgreSQL 검색 쿼리는 601회 실행되었고, 평균 실행 시간은 15.43ms였다.

DB search query mean_exec_time = 15.43ms

Docker stats도 비슷한 결론을 보여준다.

pwm-postgres cpu_avg = 18.5%
pwm-postgres cpu_max = 76.8%

DB가 완전히 무너진 것은 아니다. 그런데 p99는 30초까지 튀었다. 이 말은 하나다.

Redis 장애 격리만으로는 전체 tail latency를 안정화할 수 없다.

CircuitBreaker는 Redis 호출 반복을 막았다. 하지만 단일 Redis 인스턴스가 죽는 순간 cache 계층 자체는 사라진다.
Redis가 살아 있을 때는 반복 요청을 Redis가 흡수한다. Redis가 죽으면 요청은 local DB로 내려간다.

Redis 정상
→ 반복 요청은 Redis가 흡수

Redis 장애
→ Redis 우회
→ DB fallback 증가

즉 CircuitBreaker는 Redis 장애를 빠르게 우회하게 만들지만, Redis가 제공하던 부하 흡수 능력까지 대체하지는 못한다.

이번 실험의 결론

Redis timeout은 Redis 실패 대기 시간을 줄인다. CircuitBreaker는 장애 Redis 호출 반복을 줄인다. 하지만 Redis 단일 장애 자체를 없애지는 못한다. Redis가 단일 인스턴스이면, Redis 장애 순간 cache 계층 전체가 사라진다. Redis가 죽을 때마다 DB가 직접 부하를 받아야 한다면 운영 안정성은 여전히 부족하다. 따라서 다음 단계는 Redis 자체를 단일 장애점에서 빼는 것이다.

[종목 검색 API] 3. API 부하 테스트: debounce, Redis Cache, Redis 장애

kyoulho — Fri, 22 May 2026 14:55:07 +0900

1편에서는 PostgreSQL 검색 쿼리의 실행 계획을 확인했다.

이번에는 실제 자동완성 API에 부하를 걸어봤다. 단순히 “Redis를 붙이면 빨라지는가?”를 확인하려는 실험은 아니다.

자동완성 API에서 더 중요한 질문은 따로 있다.

사용자가 검색창에 입력할 때 서버에는 어떤 요청이 발생하는가?
Redis Cache는 DB 부하를 얼마나 줄이는가?
Redis가 운영 중 내려가면 병목은 어디로 이동하는가?

결론부터 말하면, 자동완성 검색 API의 1차 방어선은 Redis가 아니라 debounce였다.

Redis는 반복 요청을 흡수한다. 하지만 잘못된 입력 패턴 자체를 줄이지는 못한다.

자동완성 API의 요청 경로는 조회 중심으로 설계했다.

Redis
→ local stock_master
→ response

자동완성 API는 사용자의 입력 과정에서 반복 호출된다. 따라서 요청 경로에는 Redis 조회와 DB 검색처럼 예측 가능한 작업만 둔다.

stock_master는 검색 요청 경로 밖에서 배치를 통해 주기적으로 갱신한다.

현재 검색 API 구조

현재 검색 API는 Redis cache-aside 구조로 동작한다. 요청 흐름은 다음과 같다.

trim
  → len < 2 → emptyList, cache/DB 미사용
  → normalize → cache key 생성
  → Redis get
      hit → return
      miss / get error / CB bypass → local stock_master search
  → non-empty → cache put (TTL 300s)
  → empty     → cache put (TTL 30s)
  → return

Cache key는 다음과 같다.

stock-search:{symbol}:{nameKo}:{nameEn}:{limit}

TTL 정책도 단순하다.

결과	조건	TTL
결과 있음	local stock_master hit	300초
결과 없음	local stock_master empty	30초
검색어 길이 < 2	요청 차단	저장 안 함

이 흐름에서 검색 API의 책임은 명확하다.

저장된 stock_master를 조회한다.
반복 요청은 Redis로 흡수한다.
Redis가 실패하면 DB로 fallback한다.

검색 요청은 stock_master를 갱신하지 않는다. stock_master는 검색 요청 경로 밖에서 주기적으로 갱신한다.

따라서 local DB 검색 결과가 없으면 짧은 TTL로 empty result를 캐시한다.

local search result exists
→ 300초 캐시

local search result empty
→ 30초 negative cache

query length < 2
→ cache/DB 모두 사용하지 않음

자동완성 API의 요청 경로는 조회 중심이어야 한다.

측정 방법

API 부하는 k6로 만들었다. k6에서 본 값은 다음이다.

지표	의미
http_reqs	API 요청 수
http_req_duration p(95)	대부분의 사용자가 체감하는 응답 시간
http_req_duration p(99)	느린 요청이 얼마나 튀는지
http_req_failed	HTTP 실패율

DB query count는 pg_stat_statements로 확인했다.

테스트 전 통계를 초기화했다.

SELECT pg_stat_statements_reset();

테스트 후 검색 쿼리 호출 수를 확인했다.

SELECT calls,
       total_exec_time,
       mean_exec_time,
       rows,
       query
FROM pg_stat_statements
WHERE query ILIKE '%stock_master%'
ORDER BY calls DESC;

여기서 가장 중요한 값은 calls다.

calls = 실제 PostgreSQL 검색 쿼리 실행 수

k6 http_reqs와 pg_stat_statements.calls는 같을 필요가 없다.

Redis hit이 발생하면 API 요청은 존재하지만 DB query는 발생하지 않는다. 그래서 다음 비율을 함께 봤다.

DB query/request 비율 = DB search query count / k6 http_reqs

DB CPU는 Docker 기준으로 확인했다.

docker stats pwm-postgres

Redis hit / miss / error / bypass는 Micrometer Counter로 확인했다.

pwm.stock_search.cache.hit
pwm.stock_search.cache.miss
pwm.stock_search.cache.get_error
pwm.stock_search.cache.set_error
pwm.stock_search.cache.bypassed

테스트 시나리오

naive 입력 패턴

첫 번째는 debounce가 없다고 가정했다. 즉 사용자가 입력하는 중간 상태가 모두 서버로 전달된다. 자동완성에서 흔히 실수하는 방식이다.

테스트 요청은 한글 종목명, 한국 숫자 티커, 미국 티커, 영문 검색어, 존재하지 않는 검색어를 섞었다.

한글 종목명/테마
삼 → 삼ㅅ → 삼서 → 삼성
반 → 반ㄷ → 반도 → 반돛 → 반도체
카 → 캌 → 카카 → 카캌 → 카카오

한국 숫자 티커
0 → 00 → 005 → 0059 → 00593 → 005930
0 → 00 → 000 → 0006 → 00066 → 000660
0 → 03 → 035 → 0357 → 03572 → 035720

미국 티커
A → AA → AAP → AAPL
T → TS → TSL → TSLA
N → NV → NVD → NVDA

영문 검색어
ap → app → appl → apple
te → tes → tesl → tesla
sa → sam → sams → samsung

없는 검색어
없 → 없는 → 없는종 → 없는종목
z → zz → zzz → zzzz → zzzznotfound
테 → 텟 → 테스 → 테스트 → 테스트검색어
1 → 12 → 123 → 1234 → 12345 → 123456

debounced 입력 패턴

두 번째는 debounce가 적용되었다고 가정했다. 중간 입력 상태는 서버로 보내지 않고 최종 검색어만 요청한다. 다만 삼성, 레버리지, AAPL만 반복하지 않았다. 그렇게 하면 Redis hit이 지나치게 잘 나오는 이상적인 테스트가 된다.

그래서 debounced 테스트도 현실적인 검색어 그룹을 섞었다.

한국 종목명/테마
삼성, 레버리지, 반도체, 현대차, 카카오

한국 숫자 티커
005930, 000660, 035420, 035720, 373220

미국 티커
AAPL, TSLA, NVDA, MSFT, GOOGL

영문 검색어
apple, tesla, samsung, semiconductor, energy

없는 검색어
없는종목, zzzznotfound, 삼성없는, 123456, 테스트검색어

운영 중 Redis 장애

세 번째는 Redis 장애 테스트다. Redis를 테스트 전에 끄지 않았다. k6 부하가 진행 중인 상태에서 Redis를 중단했다. 이 테스트의 목적은 단순히 API가 실패하는지 보는 것이 아니다. 운영 관점에서는 Redis가 내려갔을 때 병목이 어디로 이동하는지가 더 중요하다.

장애 경로는 단순하다.

Redis get 실패
→ local DB fallback
→ Redis set 실패
→ response

즉 봐야 할 것은 이것이다.

Redis 장애가 API 실패로 전파되는가?
Redis 장애 후 tail latency가 얼마나 튀는가?
DB가 fallback 부하를 감당하는가?
Redis 실패를 계속 기다리는 구조인가?

naive 입력 패턴 결과

항목	값
k6 http_reqs	4,946
p95 latency	53.8ms
p99 latency	172.98ms
http_req_failed	0.00%
DB search query count	1,065회
DB search query/request 비율	21.5%
DB mean_exec_time	27.04ms
DB CPU max	174.98%
Redis hit count	2,724
Redis miss count	1,065
Redis hit ratio	71.9%
Redis error count	0

naive 입력 패턴에서는 4,946건의 API 요청이 발생했다. 이 중 실제 검색 쿼리는 1,065회 실행되었다.

Redis hit은 2,724건, miss는 1,065건이었다. Redis hit ratio는 71.9%였다.

수치만 보면 Redis가 어느 정도 일을 했다. 하지만 naive 패턴의 문제는 여전히 남아 있었다.

사용자 입력 중간 상태가 모두 서버로 들어오기 때문이다.

debounced 입력 패턴 결과

항목	값
k6 http_reqs	1,770
p95 latency	22.93ms
p99 latency	219.35ms
http_req_failed	0.00%
DB search query count	501회
DB search query/request 비율	28.3%
DB mean_exec_time	1.26ms
DB CPU max	38%
Redis hit count	1,268
Redis miss count	501
Redis hit ratio	71.7%
Redis error count	0

naive와 비교하면 다음과 같다.

항목	naive	debounced	변화
k6 http_reqs	4,946	1,770	-64.2%
p95 latency	53.8ms	22.93ms	-57.4%
p99 latency	172.98ms	219.35ms	+26.8%
DB search query count	1,065	501	-53.0%
DB CPU max	174.98%	38%	-78.3%
Redis hit ratio	71.9%	71.7%	거의 동일

Debounce 적용 후 API 요청 수는 4,946건에서 1,770건으로 줄었다. 요청 수는 64.2% 감소했다.

DB 검색 쿼리도 1,065회에서 501회로 줄었다.

DB CPU max는 174.98%에서 38%로 낮아졌다.

중요한 점은 Redis hit ratio가 크게 올라간 것이 아니라는 점이다. naive와 debounced의 Redis hit ratio는 각각 71.9%, 71.7%로 거의 비슷했다.

이번 개선의 핵심은 hit ratio 상승이 아니었다. 요청 수 자체를 줄여서 Redis miss와 DB query의 총량을 줄인 것이다. 다만 p99는 오히려 172.98ms에서 219.35ms로 증가했다. p99는 일부 느린 요청의 존재를 보여준다. 평균이나 p95만 보고 끝내면 이런 요청을 놓친다.

정리하면 다음과 같다.

현실적인 검색 패턴에서는 debounce가 DB 부하를 크게 줄인다.
하지만 p99 문제를 완전히 제거하지는 못한다.
Redis hit ratio만 볼 것이 아니라, miss 경로와 tail latency를 함께 봐야 한다.

운영 중 Redis 장애 테스트 결과

Redis가 정상 동작하는 상태에서 debounced 입력 패턴으로 실행했다. 그 다음 테스트 중간에 Redis를 중단했다.

측정 결과는 다음과 같았다.

항목	값
k6 http_reqs	1,254
p95 latency	2.56s
p99 latency	3.55s
max latency	4.26s
http_req_failed	0.00%
DB search query count	812회
DB mean_exec_time	12.05ms
DB CPU max	103.65%
Redis error count	1,079

HTTP 실패율은 0%였다. 즉 Redis 장애가 API 5xx로 직접 전파되지는 않았다.

하지만 성능은 크게 흔들렸다. Redis 정상 상태의 debounced 테스트에서는 p95가 22.93ms였다. Redis 장애 시 p95는 2.56초까지 증가했다. 이것은 단순히 DB 쿼리가 느려져서 생긴 문제로 보기 어렵다. DB 검색 쿼리의 평균 실행 시간은 12.05ms였다.

즉 tail latency의 상당 부분은 다음 경로에서 발생했을 가능성이 높다.

Redis get 실패 대기
→ DB fallback
→ Redis set 실패 대기

로그에서도 Redis get/set error가 반복적으로 발생했다.

Lettuce는 Redis가 내려간 뒤에도 재연결을 계속 시도했다.

Cannot reconnect to localhost:6379

Redis 장애 테스트에서 확인한 것은 다음이다.

질문	결과
API가 실패했는가?	아니다. http_req_failed=0.00%
Redis 장애 후 tail latency가 튀었는가?	그렇다. p95 2.56s, p99 3.55s
DB가 완전히 병목이 되었는가?	DB CPU max 103.65%, DB mean 12.05ms로 DB만의 문제는 아니었다.
Redis timeout / 재연결 대기가 영향을 줬는가?	가능성이 높다. Redis error 1,079회와 Lettuce reconnect 로그가 반복되었다.
fallback만으로 충분한가?	아니다. 실패율은 막았지만 latency는 막지 못했다.

정리하면 다음과 같다.

현재 구조는 Redis 장애 시 API 실패는 막는다.
하지만 tail latency는 막지 못한다.
fallback만으로는 부족하고, Redis 장애를 감지한 뒤 일정 시간 Redis 호출을 우회하는 circuit breaker가 필요하다.

최종 정리

테스트	https_reqs	p95	p99	DB query count	DB cpu max	Redis hit ratio	비고
naive	4,946	53.8ms	172.98ms	1,065	174.98%	71.9%	입력마다 요청
debounced	1,770	22.93ms	219.35ms	501	38%	71.7%	최종 검색어만 요청
Redis 장애	1,254	2.56s	3.55s	812	103.65%	측정 제외	운영 중 Redis 중단

이번 실험의 결론은 세 가지다.

첫째, 자동완성 검색 API에서 가장 먼저 줄여야 할 것은 DB 쿼리가 아니라 불필요한 입력 이벤트 요청이다. 현실적인 naive 입력 패턴에서는 API 요청이 4,946건 발생했고, DB 검색 쿼리는 1,065회 실행되었다. Debounce 적용 후 API 요청은 1,770건으로 줄었고, DB 검색 쿼리도 501회로 감소했다.

둘째, Redis hit ratio만 보면 안 된다. 현실적인 시나리오에서는 naive와 debounced의 Redis hit ratio가 각각 71.9%, 71.7%로 거의 비슷했다. 하지만 요청 수 자체가 줄어들면서 DB query 총량과 DB CPU는 크게 낮아졌다.

셋째, Redis fallback만으로는 운영 안정성이 충분하지 않다. Redis 장애 시 HTTP 실패율은 0%였지만, p95는 2.56초, p99는 3.55초까지 증가했다. 즉 fallback은 API 실패를 막았지만, tail latency는 막지 못했다.

다음 병목 해결 방향

이번 실험 이후 해결해야 할 병목은 Redis 장애 시 tail latency였다.

Redis timeout 단축

Redis 장애 후 p95가 2.56초까지 튀었다.

DB 검색 쿼리 평균 실행 시간은 낮았으므로, 전체 지연의 대부분은 DB 자체보다 Redis 실패 대기와 재연결 영향일 가능성이 높았다.

따라서 Redis command timeout을 짧게 가져가야 한다.

spring:
  data:
    redis:
      timeout: 100ms

Redis circuit breaker

Redis가 죽은 상태에서도 매 요청마다 Redis get/set을 시도하면 fallback은 성공해도 p99는 계속 흔들린다.

Redis error가 반복되면 일정 시간 Redis 호출을 생략해야 한다.

Redis error 반복
→ CircuitBreaker OPEN
→ Redis get/set 우회
→ DB fallback으로 바로 진행

핵심은 Redis 장애를 매 요청마다 다시 확인하지 않는 것이다.

마무리

이번 실험은 Redis Cache를 붙인 뒤에도 자동완성 API 병목이 사라지지 않는다는 것을 보여준다. Redis는 효과가 있다.

하지만 Redis보다 먼저 입력 요청 패턴을 줄여야 한다. 그리고 Redis는 장애가 발생하면 또 다른 병목 지점이 된다.

[종목 검색 API] 2. Local DB 검색 Baseline 실험

kyoulho — Thu, 21 May 2026 19:48:04 +0900

현재 Repository 쿼리는 대략 다음 구조다.

where s.is_active = true
  and (
    s.search_symbol = :symbol
    or s.search_symbol like concat(:symbol, '%')
    or s.search_name_ko like concat('%', :nameKo, '%')
    or s.search_name_en like concat('%', :nameEn, '%')
  )
order by
  case
    when s.search_symbol = :symbol then 0
    when s.search_symbol like concat(:symbol, '%') then 1
    when s.search_name_ko like concat('%', :nameKo, '%') then 2
    when s.search_name_en like concat('%', :nameEn, '%') then 3
    else 4
  end,
  s.country asc,
  s.market asc,
  s.symbol asc

즉, 실제 검색에는 다음 요소가 함께 들어간다.

exact 검색
prefix 검색
contains 검색
OR 조건
ORDER BY CASE
LIMIT

이번 실험의 목적은 단순하다. LIKE 검색이 실제로 어떤 실행 계획을 타는지 보고, 필요한 인덱스를 결정한다.

실험 환경

PostgreSQL: 17.9
데이터 수: 300,006건

기존 인덱스는 다음과 같다.

create index ix_stock_master_search_symbol
    on stock_master (search_symbol);

create index ix_stock_master_search_name_ko
    on stock_master (search_name_ko);

create index ix_stock_master_search_name_en
    on stock_master (search_name_en);

개별 조건 Baseline

먼저 실제 API 쿼리를 구성하는 조건을 따로 떼어서 확인했다.

Query	유형	Plan	Rows	Time
search_symbol = 'AAPL'	exact	Index Scan	1	0.122 ms
search_symbol LIKE 'AAP%'	prefix	Parallel Seq Scan	1	71.175 ms
search_name_ko LIKE '%삼성%'	contains	Seq Scan	120,001	123.354 ms

exact 검색

SELECT *
FROM stock_master
WHERE search_symbol = 'AAPL';

Index Scan using ix_stock_master_search_symbol
Index Cond: search_symbol = 'AAPL'
Buffers: shared hit=2 read=2
Execution Time: 0.122 ms

정확 검색은 기존 B-Tree Index를 정상적으로 사용했다.

다만 Index Scan이라고 해서 index만 읽는 것은 아니다. PostgreSQL은 index에서 row 위치를 찾은 뒤 실제 row는 heap에서 다시 읽는다.

prefix 검색

SELECT *
FROM stock_master
WHERE search_symbol LIKE 'AAP%';

Gather
  Workers Planned: 2
  Workers Launched: 2
  -> Parallel Seq Scan on stock_master
       Filter: search_symbol LIKE 'AAP%'
       Rows Removed by Filter: 100002
Execution Time: 71.175 ms

prefix 검색이라 B-Tree Index를 사용할 것으로 예상했다. 하지만 실제로는 Parallel Seq Scan이 발생했다.

문자열은 단순 바이트 순서가 아니라 collation 규칙을 따른다. 그래서 PostgreSQL은 일반 B-Tree Index만으로 LIKE 'prefix%' 범위를 안전하게 좁히기 어렵다고 판단할 수 있다. 이때 검토할 수 있는 것이 text_pattern_ops다.

contains 검색

SELECT *
FROM stock_master
WHERE search_name_ko LIKE '%삼성%';

Seq Scan on stock_master
  Filter: search_name_ko LIKE '%삼성%'
  Rows Removed by Filter: 180005
Execution Time: 123.354 ms

LIKE '%삼성%'는 앞부분이 %로 열려 있다. B-Tree는 정렬된 구조이기 때문에 시작 지점을 잡아야 빠르게 찾을 수 있다. contains 검색은 시작 지점이 없으므로 기존 B-Tree Index와 맞지 않는다.

prefix 검색 개선: text_pattern_ops

prefix 검색을 위해 인덱스를 추가했다. 적용 후 실행 계획이 바뀌었다.

CREATE INDEX ix_stock_master_search_symbol_pattern
ON stock_master (search_symbol text_pattern_ops);

Bitmap Heap Scan on stock_master
  Heap Blocks: exact=1
  -> Bitmap Index Scan on ix_stock_master_search_symbol_pattern
       Index Cond: search_symbol >= 'AAP' AND search_symbol < 'AAQ'
Execution Time: 0.047 ms

항목	개선 전	개선 후
Plan	Parallel Seq Scan	Bitmap Heap Scan + Bitmap Index Scan
Execution Time	71.175 ms	0.047 ms
Buffers	hit=6511 read=2760	hit=4

PostgreSQL은 LIKE 'AAP%'를 AAP 이상, AAQ 미만의 범위 탐색으로 바꿨다. 즉 text_pattern_ops 적용 후 prefix 검색이 B-Tree 범위 탐색으로 처리되었다.

contains 검색 개선: pg_trgm + GIN Index

contains 검색을 위해 pg_trgm + GIN Index를 적용했다.

CREATE EXTENSION IF NOT EXISTS pg_trgm;

CREATE INDEX ix_stock_master_search_name_ko_trgm
ON stock_master
USING gin (search_name_ko gin_trgm_ops);

CREATE INDEX ix_stock_master_search_name_en_trgm
ON stock_master
USING gin (search_name_en gin_trgm_ops);

항목	개선 전	개선 후
Plan	Seq Scan	Seq Scan
Rows	120,001	120,001
Execution Time	123.354 ms	70.333 ms

처음에는 %삼성% 검색도 GIN Index를 사용할 것으로 예상했다. 하지만 결과는 여전히 Seq Scan이었다. 이유는 결과 row가 너무 많기 때문이다. 전체 300,006건 중 120,001건이 %삼성% 조건에 걸렸다.

Planner는 "GIN Index를 타더라도 결국 12만 row를 heap에서 다시 읽어야 한다. 그렇다면 차라리 Seq Scan이 더 싸다." 고 판단했다.

즉 pg_trgm + GIN Index를 만든다고 contains 검색이 무조건 index scan으로 바뀌는 것은 아니다.

planner는 statistics를 기반으로 예상 row 수를 계산하고, index 탐색 비용과 heap 접근 비용을 비교해서 실행 계획을 선택한다.

pg_trgm이 실제로 사용되는 경우

검색어를 %레버리지%로 바꿔 확인했다.

SELECT *
FROM stock_master
WHERE search_name_ko LIKE '%레버리지%';

Bitmap Heap Scan on stock_master
  Recheck Cond: search_name_ko LIKE '%레버리지%'
  Heap Blocks: exact=9271
  -> Bitmap Index Scan on ix_stock_master_search_name_ko_trgm
       Index Cond: search_name_ko LIKE '%레버리지%'
Execution Time: 53.795 ms

Query	Plan	Rows	Time
LIKE '%삼성%'	Seq Scan	120,001	70.333 ms
LIKE '%레버리지%'	Bitmap Heap Scan + Bitmap Index Scan	60,000	53.795

같은 GIN Index가 있어도 planner의 선택은 달라질 수 있다. 핵심은 index 존재 여부가 아니라 검색 조건의 선택도다.

실제 Repository 쿼리 기준 측정

개별 조건 실험은 부품 테스트에 가깝다. 실제 API 쿼리는 여러 조건이 OR로 묶이고, 결과를 다시 ORDER BY CASE로 정렬한다.

Case 1. keyword = '삼성'

Limit
  -> Gather Merge
       -> Sort
            Sort Method: top-N heapsort
            -> Parallel Seq Scan on stock_master
                 Filter: is_active AND (...)
                 Rows Removed by Filter: 60002
Execution Time: 125.647 ms

항목	값
Top Plan	Limit → Gather Merge → Sort → Parallel Seq Scan
Index	없음
OR 처리	Filter에서 직접 평가
Sort	top-N heapsort
Rows	40,000 × 3
Execution Time	125.647 ms

삼성은 결과 row가 너무 많았다. planner는 OR 조건을 BitmapOr로 조합하지 않고 Parallel Seq Scan을 선택했다. LIMIT 10이 있어도 ORDER BY CASE 때문에 정렬 단계는 필요했다.

Case 2. keyword = '레버리지'

Limit
  -> Gather Merge
       -> Sort
            Sort Method: top-N heapsort
            -> Parallel Bitmap Heap Scan on stock_master
                 -> BitmapOr
                      -> Bitmap Index Scan on ix_stock_master_search_symbol_pattern
                      -> Bitmap Index Scan on ix_stock_master_search_name_ko_trgm
                      -> Bitmap Index Scan on ix_stock_master_search_name_en_trgm
Execution Time: 76.863 ms

항목	값
Top Plan	Limit → Gather Merge → Sort → Parallel Bitmap Heap Scan
OR 처리	BitmapOr
Index	symbol pattern, name_ko trgm, name_en trgm
Rows	20,000 × 3
Execution Time	76.863 ms

레버리지 케이스에서는 planner가 OR 조건을 BitmapOr로 조합했다. 특히 search_name_ko LIKE '%레버리지%' 조건에서 ix_stock_master_search_name_ko_trgm 인덱스를 사용했다.

Case 3. keyword = 'AAPL'

Limit
  -> Sort
       Sort Method: quicksort
       -> Bitmap Heap Scan on stock_master
            Heap Blocks: exact=1
            -> BitmapOr
                 -> Bitmap Index Scan on ix_stock_master_search_symbol_pattern
                 -> Bitmap Index Scan on ix_stock_master_search_name_ko_trgm
                 -> Bitmap Index Scan on ix_stock_master_search_name_en_trgm
Execution Time: 2.566 ms

항목	값
Top Plan	Limit → Sort → Bitmap Heap Scan
OR 처리	BitmapOr
Index	symbol pattern, name_ko trgm, name_en trgm
Rows	1
Heap Blocks	exact=1
Execution Time	2.566 ms

AAPL은 선택도가 높았다. planner는 OR 조건을 BitmapOr로 조합했고, 실제 heap 접근도 1 block 수준으로 끝났다. 정렬은 발생했지만 대상 row가 1건뿐이라 비용은 거의 없었다.

실제 API 쿼리 결과 정리

keyword	Top Plan	OR 처리	Rows	Time
삼성	Parallel Seq Scan	Filter에서 직접 평가	40,000 × 3	125.647 ms
레버리지	Parallel Bitmap Heap Scan	BitmapOr	20,000 × 3	76.863 ms
AAPL	Bitmap Heap Scan	BitmapOr	1	2.566 ms

검색어의 선택도가 좋아질수록 planner는 인덱스를 더 적극적으로 사용한다. 반대로 결과 row가 너무 많은 검색어는 인덱스가 있어도 Seq Scan으로 갈 수 있다.

그리고 ORDER BY CASE 때문에 Sort는 계속 발생한다. LIMIT 10은 정렬 비용을 줄여주지만, 후보 row를 찾고 정렬하는 단계 자체를 없애지는 못한다.

최종 적용할 인덱스

이번 실험 기준으로 유지할 인덱스는 다음과 같다.

-- exact 검색용
CREATE INDEX ix_stock_master_search_symbol
ON stock_master (search_symbol);

-- prefix 검색용
CREATE INDEX ix_stock_master_search_symbol_pattern
ON stock_master (search_symbol text_pattern_ops);

-- contains 검색용
CREATE EXTENSION IF NOT EXISTS pg_trgm;

CREATE INDEX ix_stock_master_search_name_ko_trgm
ON stock_master
USING gin (search_name_ko gin_trgm_ops);

CREATE INDEX ix_stock_master_search_name_en_trgm
ON stock_master
USING gin (search_name_en gin_trgm_ops);

다만 인덱스를 만든다고 항상 사용되는 것은 아니다. planner는 검색어의 선택도, 예상 row 수, heap 접근 비용을 함께 계산한다.

다음 단계에서는 이 실제 API 쿼리를 기준으로 k6 부하 테스트를 수행한다.

p95 latency
p99 latency
DB CPU 사용률
DB shared hit/read 변화
검색어별 응답 시간 차이
동일 검색어 반복 시 Redis Cache 적용 효과

[종목 검색 API] 1. 자동완성 검색 API는 어떻게 서버를 터뜨리는가

kyoulho — Wed, 20 May 2026 18:56:05 +0900

PWM 서비스를 만들면서 종목 검색 API를 구현했다. 처음에는 단순 조회 API라고 생각했다. 하지만 자동완성 UI를 붙이는 순간 검색 API의 성격이 달라진다. 사용자는 검색창에 한 번 입력하지만, 서버는 여러 번 요청을 받는다.

삼
삼성
삼성전
삼성전자

입력이 바뀔 때마다 API를 호출하면 검색 한 번이 여러 요청으로 증폭된다.

종목 조회, 포트폴리오 편입, 관심 종목, 차트 조회, 지수 비교가 모두 검색에서 시작된다.

즉 종목 검색 API는 단순 부가 기능이 아니라 트래픽이 몰릴 수 있는 지점이다.

현재 구조

현재 검색은 PostgreSQL의 local master DB를 먼저 조회한다.

결과가 충분하면 바로 반환하고, 결과가 없으면 외부 Provider를 호출하는 구조를 고려하고 있다.

Local DB 검색
→ 결과 있으면 반환
→ 결과 없으면 KIS / Yahoo 같은 외부 Provider 호출

병목도 두 단계로 나뉜다. 첫 번째는 Local DB 검색 병목이다. 두 번째는 외부 Provider 호출 병목이다. 이번 글에서는 첫 번째 병목만 본다. 외부 Provider는 그다음 문제다.

문제 지점

현재 검색 쿼리는 대략 이런 형태다.

where is_active = true
  and (
    search_symbol = :symbol
    or search_symbol like :symbol || '%'
    or search_name_ko like '%' || :keyword || '%'
    or search_name_en like '%' || :keyword || '%'
  )

search_symbol = ? 는 괜찮다. search_symbol like 'AAP%'도문제는 이쪽이다.

search_name_ko like '%삼성%'
search_name_en like '%tesla%'

contains 검색이다. 일반적인 B-Tree Index는 이런 검색에 적합하지 않다. B-Tree는 정렬된 구조라서 시작 지점이 명확한 검색에 강하다.

예를 들어 like 'AAP%'는AAP로 시작하는 위치를 찾고 그 이후를 보면 된다. 하지만 like '% AAP%'는 앞부분이 고정되어 있지 않다.
어디에 AAP가 들어있는지 알 수 없기 때문에 많은 row를 직접 검사할 가능성이 높다. 자동완성과 결합되면 더 위험하다.

입력
→ API 호출
→ LIKE '%keyword%' 검색
→ 반복

개발 환경에서는 잘 안 보인다. 데이터도 적고 동시 요청도 거의 없기 때문이다. 하지만 데이터가 늘고 요청이 반복되면 Local DB가 첫 번째
병목이 될 수 있다.

실행 계획 확인

감으로 판단하면 안 된다. 일단 실행 계획을 봐야 한다. 예를 들어 다음 쿼리를 확인한다.

EXPLAIN ANALYZE
SELECT *
FROM stock_master
WHERE is_active = true
  AND search_name_ko LIKE '%a%'
LIMIT 10;

여기서 봐야 할 것은 단순하다.

Seq Scan이 발생하는가?
Index Scan이 발생하는가?
실제 실행 시간은 얼마인가?
읽은 row는 얼마나 되는가?

contains 검색에서 Seq Scan이 발생하면 예상했던 문제다. PostgreSQL이 인덱스로 바로 좁히지 못하고 많은 데이터를 검사하고 있다는 의미다. 물론 데이터가 적으면 실행 시간 자체는 짧게 나올 수 있다. 하지만 중요한 건 현재 시간이 아니라 증가 방향이다. 데이터가 늘고 자동완성 요청이 반복되면 이 비용은 계속 커진다.

이번 시리즈의 방향

여기서 바로 Redis를 붙이지 않을 생각이다. Redis를 먼저 붙이면 DB 병목이 가려진다. 캐시는 느린 쿼리를 숨길 수는 있지만, 쿼리 자체를 개선하지는 못한다. 먼저 Local DB 검색 병목을 확인하고 해결한다.

진행 순서는 이렇게 잡았다.

1. 현재 검색 쿼리 실행 계획 확인
2. API 부하 테스트로 병목 확인
3. pg_trgm + GIN Index 적용
4. 실행 계획과 응답 시간 재측정
5. 더 높은 부하에서 다시 테스트
6. Redis Cache 적용
7. 반복 요청 감소 효과 측정

즉 순서는 이렇다.

DB 검색 최적화
→ API 부하 확인
→ Cache 적용

먼저 DB가 기본기를 갖춰야 한다. 그다음에 Redis로 반복 요청을 줄이는 게 맞다.

다음 글에서는 실제 검색 쿼리의 실행 계획을 확인한다. 목표는 하나다. LIKE '% keyword%' 검색이 실제로 어떤 실행 계획을 타는지 확인하는 것. Seq Scan이 발생한다면 그 이유를 보고, 이후 pg_trgm + GIN Index로 어떻게 바뀌는지 비교할 예정이다.

유동성의 진화: 가격의 시대에서 '접근권'의 시대로

kyoulho — Thu, 19 Feb 2026 18:14:47 +0900

시장의 유동성을 판단하는 기준점이 이동하고 있다. 과거의 질서에서 유동성은 연준(Fed)이라는 단일 공급원이 금리라는 가격 조절 장치를 통해 전 세계에 흘려보내는 공공재에 가까웠다. 그러나 탈세계화라는 거대한 흐름 속에서 이 공급 체계 자체가 전략적 자산으로 변화하고 있다.

1. 붕괴되는 구질서: 달러 패권 유지를 위한 인위적 환경

과거 15년은 금리가 곧 유동성을 결정하는 시대였다. 이 구질서는 미국이 달러 패권을 공고히 하고 세계화의 이득을 극대화하기 위해 설계한 '유동성 무한 공급' 체계였다. 연준은 QE와 달러 스왑라인(Swap Lines)을 동원해 글로벌 소방수를 자처했으나, 이는 본질적으로 달러 시스템의 붕괴를 막아 자국의 지배력을 유지하기 위한 선택이었다. 시장 참여자들은 미국이 자국 이익을 위해 만들어놓은 이 인위적인 디폴트 세팅값 위에서 사고했다. 하지만 이제 미국이 다시 자국 우선주의를 내걸고 세계화의 판을 깨기 시작하면서, 유동성은 '보편적 복지'에서 '전략적 통제'로 이동하고 있다.

2. 케빈 워시의 비판: QE의 역설과 서민의 고통

연준의 새로운 의장 케빈 워시는 구질서의 핵심 기제였던 QE에 대해 매우 냉소적이었다. 그는 과거 QE가 자산 가격을 띄워 금융권(Wall Street)에는 막대한 수익을 안겨주었지만, 그 결과로 초래된 고물가와 이를 잡기 위한 고금리는 결국 실물 경제의 서민(Main Street)들에게 고통을 전가했다고 지적한다.

그의 지명은 연준의 정책 우선순위가 바뀔 것임을 시사한다. 단순히 자산 시장을 부양하기 위한 유동성 공급은 억제될 것이며, 달러 공급은 미국의 국가 전략과 실물 경제의 건전성을 위해 철저히 계산된 방식으로 이루어질 것이다. 유동성의 가격보다 '누가 이 라인에 접속할 자격이 있는가'라는 문제가 부각되는 이유다.

3. 유로 레포라인(EUREP)의 강화: 달러가 막힐 때를 대비한 '유로 벙커'

유럽중앙은행(ECB)이 EUREP(유로 레포 라인)를 강화한 것은 연준의 달러 스왑라인이 더 이상 '상수'가 아니라는 신호다.

EUREP는 유럽 이외의 중앙은행들이 보유한 유로화 표시 국채를 담보로 ECB에서 유로화를 빌려가는 장치다. 이게 왜 중요할까? 시장에 달러가 마르면, 달러가 급한 국가들은 현금을 만들기 위해 자기들이 들고 있던 유로화 국채부터 시장에 던지게 된다. 그러면 유로화 자산 가치가 폭락하고 유럽 금융 시스템까지 도미노처럼 무너진다.

EUREP는 이때 국채를 '매도'하는 대신 ECB에 '담보'로 맡기고 유로화를 빌려가게 함으로써, 시장의 투매를 막는 일종의 방어막 역할을 한다. 달러 부족을 직접 해결해주지는 못하지만, 달러가 막혔을 때 유로 자산이 함께 타버리는 연쇄 반응을 끊어내겠다는 계산이다. '거래적 동맹' 시대에 연준의 선의를 기다리는 대신, 스스로 방어벽을 쌓기 시작한 셈이다.

4. 탈세계화의 시그널: SWIFT 탈피와 금 비축

탈세계화의 흐름은 이제 가격 데이터에서 확인된다. 특히 달러 중심의 결제망(SWIFT)이 전략적 무기로 활용되면서, 이에 대한 의존도를 낮추려는 움직임이 가속화되고 있다. 중국이 지속적으로 금 매입을 늘리며 외환보유고 체질을 바꾸는 것은 달러 단일 체제에서 이탈하려는 실질적인 리스크 헤지다. 위안화의 강세와 원자재 가격의 버티기는 단순히 공급망 분절을 넘어, 가치 저장의 기준점 자체가 다극화되고 있음을 보여준다. 자본은 더 이상 달러라는 단일 시스템에 올인하지 않고 대안을 찾는 중이다.

5. 정치적 가변성과 구조적 변곡점

트럼프 행정부의 정책 기조가 시장을 흔들고 있지만 정치적 유효 수명도 고려할 필요가 있다. 트럼프의 지지율 하락과 다가오는 중간선거에서의 패배 가능성, 그리고 그로 인한 레임덕이 발생한다면 시장은 다시 '과거의 세계화'로 돌아갈 수 있을까?

이미 세계화의 종말을 전제한 여러 국가의 구조적 변화는 되돌리기 힘든 임계점을 넘었을 가능성이 크다. 동맹의 해체와 각자도생의 정책적 선회는 이미 글로벌 금융 질서를 바꾸어 놓았다. 일시적인 정치적 풍향에 따라 과거로의 회귀를 기대하기보다는, 이미 시작된 이 비대칭적 유동성 구조와 각국의 대응이 지속될지 여부를 주시하며 포지션을 적절히 옮기는 유연함이 필요한 시점이다.

IS-LM 곡선으로 경험한 경제학

kyoulho — Sat, 31 Jan 2026 19:37:48 +0900

투자자산운용사 공부를 하면서 가장 이해하기 힘들었던 건 IS-LM 곡선이었다. 특히 “실질 국민소득(Y)이 증가하면 이자율(R)이 증가한다"는 LM 곡선의 원리는 내 직관에 맞지 않는 것 같았다. 소득이 늘면 시중에 돈이 많아졌으니 돈의 가치가 내려가야 하는 것 아닌가? LM 곡선을 이해하려고 제미나이와 씨름하다 보니, 경제학에서 말하는 '소득'이 일반적인 의미의 수입이 아니라는 걸 깨달았다.

1. 변수 Y의 재정의: 소득은 수입이 아니다.

우리가 일상에서 쓰는 '소득'은 내 지갑에 들어오는 현금을 떠올리게 한다. 하지만 경제학에서 Y를 소득(Income)이라 부르는 건 국가 전체가 만든 가치가 결국 국민 개개인에게 분배되기 때문일 뿐이다. 공부할 때는 이를 '물리적인 생산량'이나 '거래 규모(Volume)'로 해석하는 게 훨씬 명확하다. 이 관점으로 보면 왜 Y가 늘 때 R이 오르는지 비로소 이해가 간다.

이자율과 생산량의 상관관계 분석

생산량 증가: 나라 전체에서 사고파는 물건과 서비스의 양이 많아진다. 즉, 경제의 활동 부피가 커진다.

결제 자금 수요 폭증: 거래 규모가 커지면 결제를 위해 손에 쥐고 있어야 할 '현금'이 더 많이 필요해진다. ~~이게 거래적 수요였군요. 케인즈 선생님~~

돈의 희소성 발생: 하지만 중앙은행이 시중에 푼 돈의 양(M)은 일정하게 고정되어 있다.

이자율 상승: 시중에 돈은 한정적인데, 거래를 위해 돈을 쓰려는 주체들이 많아진다. 결국 한정된 자원을 선점하려는 경쟁이 붙으면서 돈을 빌리는 가격인 이자율이 상승하게 된다.

결국 "소득이 늘면 금리가 내려가야 한다"는 생각은 '소득'이라는 단어의 뉘앙스에 속아 중앙은행이 돈을 같이 풀어준 상황과 혼동한 결과다. 공급이 고정된 상태에서 경제의 덩치(Y)만 커지면, 돈은 오히려 귀한 대접을 받으며 몸값인 금리를 올리게 된다.

2. 생산량이 곧 소득?? 그러면 GDP는?

실질 GDP는 결국 우리 경제가 1년 동안 만들어낸 '물리적 생산량'의 합계다. 그런데 왜 단순히 많이 만드는 것(Y)이 우리의 실제 풍요로움이나 소득으로 곧바로 이어지지 않는 걸까? 우리는 왜 이 숫자의 증감에 그토록 집착하고 있는 걸까?

경제학의 전제에는 '재고'라는 함정이 숨어 있다. 회계 원칙상 팔리지 않은 물건이 창고에 쌓여도, 이는 기업이 스스로의 물건을 구매한 '재고투자'로 처리되어 GDP 수치를 올려버린다. 즉, 의도치 않은 재고가 쌓일수록 지표상 GDP는 화려하게 상승하지만, 실제 경제는 속에서부터 멍들고 있는 셈이다. 이것이 바로 수요 없는 생산이 만드는 '가짜 GDP'의 실체다. 과거 중국의 유령 도시에 수요도 없는 아파트를 지어 올려서 GDP 수치를 왜곡하기도 했다. 하지만, 그것은 국민의 실제 삶을 개선하는 질 좋은 성장이 아니다.

최근 시진핑 중국 국가 주석이 무리한 수치 위주의 성장을 강하게 비판한 것도 같은 맥락이다. 2025년 12월 15일 보도된 China's Xi warns officials against chasing 'reckless' GDP expansion 기사에 따르면, 그는 '무모한 GDP 확장'과 통계 조작을 당장 멈추라고 경고했다. 이는 중국 정부가 보여주기식 GDP의 한계를 깨닫고, 경제 시스템을 근본적으로 리팩터링 하겠다는 선언과도 같다. 결국 중국조차 성장의 '질'을 따지는 방향으로 선회했다는 점은, 투자자 입장에서 가짜 지표 뒤에 숨겨진 리스크를 걸러낼 새로운 필터가 생겼음을 의미한다. ~~과거의 자신을 비판하는 남자… 멋있어…~~

3. 소비 함수 C(Y-T): 인간은 감정이 있어요

IS 곡선을 구성하는 핵심 요소인 소비 함수 C(Y-T)를 보고 나는 솔직히 많이 놀랐다. ~~먹고 싸는 기계라고 적혀있는 걸 본 기분이랄까?~~

세금(T)을 제외한 소득(Y)이 늘어나면 정해진 비율만큼 소비(C)가 증가한다는 이 공식은 인간의 복잡한 심리 기제를 완전히 무시한다. 경제학 공식 안에서 인간은 소득이라는 데이터가 입력되면 정해진 수식에 따라 소비를 출력하는 단순한 계산기처럼 묘사된다.

하지만 실제 인간의 소비 행태는 미래에 대한 불안감, 타인과의 비교를 통한 과시욕, 혹은 평생에 걸친 자산 계획에 따라 움직인다. 당장 오늘의 소득이 늘어났다고 해도 내일이 불안하다면 인간은 결코 소비를 늘리지 않는다. 경제학은 소득 증가가 다시 소비로 이어지는 선순환을 강조하지만, 인간의 심리라는 변수가 개입하는 순간 이러한 공식은 작동을 멈춘다. 인간의 경제 활동은 숫자보다 심리에 더 큰 영향을 받는다는 사실을 간과해서는 안 된다.

4. 결론

지금까지 살펴본 경제학 모델들은 현실을 담아내기에 지나치게 기계적이고 단순하다. 재고를 투자로 간주하거나 인간의 심리를 배제하는 관점은 분명 실제 삶과 큰 괴리가 존재한다. 하지만 이러한 '허상'일지도 모르는 모델을 공부해야 하는 이유는 명확하다. 우리가 마주하는 거대한 경제 시스템이 바로 이러한 논리 체계를 바탕으로 설계되고 운영되기 때문이다.

전 세계의 주요 경제 주체들이 이 모델을 신뢰하고 그에 따라 의사결정을 내린다면, 그것은 설령 이론적 한계가 있을지라도 현실을 움직이는 가장 강력한 실체가 된다. 그러니 현실과의 괴리에 냉소하기보다는, 그 로직이 시장을 어떻게 지배하고 있는지를 철저히 파악하는 것이 우선이다. 이론이 주는 찝찝함은 잠시 접어두고… 일단 공부하자.

현금은 태생이 쓰레기였다

kyoulho — Sat, 31 Jan 2026 17:14:29 +0900

유튜브를 보다 보면 심심치 않게 마주치는 영상이 있다.
5년 뒤면 네 돈은 휴지 조각 된다, 초인플레이션의 서막, 당장 이 자산으로 도망쳐라 같은 빨간 글씨와 자극적인 배경음악.
사실 이런 영상들을 본다고 해서 심장이 덜컥 내려앉지는 않는다.
다만, 이런 공포가 대중에게 소비되는 방식과 그 이면에 숨겨진 논리적 빈틈이 흥미로울 뿐이다.
정말로 내 돈의 가치가 조금씩 떨어지는 게 세상에서 가장 무서운 일일까?
경제의 구조를 뜯어보면, 진짜 비극은 돈이 귀중품이 되었을 때 시작된다는 것을 알 수 있다.

돈의 어원: 돌고 돌아야 생명이 유지된다

우리는 흔히 화폐를 돈이라고 부른다.
이 말의 어원을 찾아가 보면 흥미로운 지점이 있다.
돈은 "돌고 돈다"는 말에서 유래했다는 설이 지배적이다.
즉, 돈의 본질은 소유나 축적이 아니라 순환에 있다는 뜻이다.
경제학적으로 볼 때 돈은 유기체의 혈액과 같다.
혈액이 온몸을 구석구석 돌아야 산소와 영양분이 공급되듯, 돈도 시장을 돌아야 가치가 창출되고 경제가 숨을 쉰다.
만약 돈이 귀중품이 되어 누군가의 장롱 속에 고여버린다면 어떻게 될까?
그것은 혈관 속에서 피가 굳어버리는 혈전과 같다.
피가 돌지 않는 신체 부위가 괴사 하듯, 돈이 돌지 않는 경제는 활력을 잃고 서서히 죽어간다.
돈은 누군가에게 건네지고 다시 돌아오는 과정 속에 있을 때만 비로소 그 생명력을 유지한다.

돈이 보물이 된 나라의 비극

현금 가치가 떨어지지 않는 세상이 천국처럼 보일 수도 있다.
하지만 그 세상을 30년 넘게 직접 겪어본 일본의 사례는 전혀 다른 이야기를 들려준다.
일본의 잃어버린 30년 동안 엔화는 국민들에게 쓰레기가 아니라 가만히 있어도 가치가 오르는 보물이었다.
일본 내부에서는 물가가 오르지 않거나 오히려 떨어지는 상황이 지속되었다.
그러다 보니 사람들은 돈을 안 쓰고 갖고만 있어도 내일 더 많은 물건을 살 수 있게 되었다.
이것이 바로 돈이 귀중품대접을 받는 상황이다.
결과는 참혹했다.
사람들은 지갑을 닫았고 기업들은 투자를 멈췄다.
밖에서는 엔화가 싸다고 난리였을지 몰라도, 일본 안에서는 돈이 너무 귀해져서 아무도 쓰지 않는 현상이 벌어졌다.
돈이 쓰레기가 되지 않으려고 버티는 순간, 그 경제라는 유기체는 서서히 말라죽어간다는 것을 일본이 증명한 셈이다.

돈이 보물일 때 미소 짓는 수혜자들

돈이 쓰레기가 되는 것을 극도로 경계하고, 반대로 돈이 보물처럼 대접받기를 원하는 이들은 누구일까?
우선, 대규모 채권 자산이나 고정 금리 예금을 보유한 사람들이다.
채권은 미래에 정해진 금액을 받기로 한 약속이다.
물가가 오르면 내가 미래에 받을 돈의 실제 구매력은 떨어진다.
반대로 물가가 정체되거나 떨어져서 돈이 보물이 되면, 가만히 앉아 있어도 자산의 실질적인 힘은 강해진다.
인플레이션은 이들의 자산을 갉아먹는 존재인 것이다.
또한, 돈이 귀중품이 되는 세상은 자산가들에게 위험이 존재하지 않는 수익을 안겨준다.
새로운 기술을 개발하거나 공장을 짓는 등의 리스크를 감수하지 않아도, 돈 가치가 알아서 오르기 때문에 투자할 이유가 사라진다.
결국 현금은 쓰레기다라며 공포를 조장하는 목소리의 이면에는, 자신들의 부가 유지되거나 오히려 높아지기를 바라는 열망이 담겨 있을 가능성이 크다.

돈은 적당히 쓰레기여야 세상을 구른다

전 세계 중앙은행이 연 2% 수준의 인플레이션을 목표로 삼는 이유는 명확하다.
돈을 아주 조금씩 타들어가게 만들기 위해서다.
들고 있으면 조금씩 손해를 본다는 느낌이 있어야 비로소 돈이 세상 밖으로 나온다.
그래야 누군가는 물건을 사서 기업의 매출을 올리고, 그 매출이 다시 노동자의 월급으로 돌아가는 선순환이 일어난다.
현금은 태생적으로 흐르는 쓰레기가 될 숙명을 타고났다.
그래야만 우리 손을 떠나 세상을 풍요롭게 만들 수 있기 때문이다.
현금이 귀중품이 되어 장롱 속으로 들어가는 순간, 그 사회의 청년들은 일자리를 잃고 성장은 멈춘다.
우리가 이런 경제적 전체 맥락과 구조를 이해하지 못한다면, 자극적인 썸네일 뒤에 숨겨진 누군가의 의도에 따라 생각하고 행동하게 될지도 모른다.
공포는 가장 강력한 통제 수단이다.
"돈이 휴지가 된다"는 말에 떨기보다는, 왜 세상이 돈을 계속 흐르게 하려고 설계되었는지 그 구조를 들여다보는 눈이 필요하다.
결국 현금의 가치가 조금씩 닳아 없어지는 것은 경제가 살아있다는 신호다.
진짜 두려워해야 할 것은 돈이 고여서 썩어가는 세상, 즉 돈이 사람보다 더 귀해지는 차가운 세상이다.