문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
9.7 KiB
9.7 KiB
06. 성능·최적화 기준
핵심
숫자 없이 최적화하지 않는다. 같은 조건에서 전과 후를 잰다. 바꾼 것 외의 변수가 같아야 두 숫자를 비교할 수 있다.
이 템플릿에는 지연·처리량 목표가 없다. 그래서 "빠르다/느리다" 대신 요청당 비용(SQL 수, 지연, 처리량, CPU)과 그 비용이
데이터 수에 비례해 늘어나는지로 판정한다(1101/09-performance-measurement.md 1절 「규모 목표」).
기준선 측정 ──> 원인 좁히기 ──> 변경 하나 ──> 같은 조건 재측정 ──> 회귀 테스트로 고정 ──> lane 단계 지정
(2·3절) (3절) (7절) (5절) (6절) (07장)
1. 무엇을 재나
| 지표 | 재는 법 | 결함 신호 | 지난 예 |
|---|---|---|---|
| 아티팩트 | bootJar 크기, BOOT-INF/lib jar 목록 |
운영 jar에 테스트용·중복 라이브러리 | 1101/09-09(H2), 1101/09-11(Jackson 2·3) |
| 기동 | Started … in 시간, 기동 3초 뒤 RSS·heap, 빈 수, 스레드 수 |
빈 수에 비해 긴 공백 한 곳 | 1101/09-performance-measurement.md 3.1절(공백이 한 곳에 몰리지 않아 결함 아님) |
| 요청당 SQL 수 | PG log_statement='all'로 요청 하나 전후의 문장 수 |
페이지 크기에 비례(N+1) | 1101/09-01(20건 46개, 100건 206개) |
| 지연·처리량 | 닫힌 루프 부하, p50·p95·p99·rps | 단건 대비 목록 처리량이 SQL 수 비율만큼 떨어짐 | 1101/09-performance-measurement.md 3.3절 |
| 요청당 CPU | JFR settings=profile, 상위 프레임 소유자 |
한 라이브러리가 CPU의 큰 몫 | 같은 문서 3.5절(목록에서 Hibernate 31%) |
| 데이터 증가에 따른 변화 | 같은 요청을 행 수를 늘려 반복 | 행 수에 비례해 느려짐(순차 스캔) | 1101/09-02 |
| 게이트·테스트 시간 | 게이트별 rc·초, 테스트 결과 XML 합계 | 바뀐 것이 없는데 매번 다시 도는 lane | 1101/08-02 |
2. 측정 위치와 조건
측정은 무거운 실행이다. 위치는 07장 「소유자 환경」을 따른다. 조건은 1101/09-performance-measurement.md 「측정 조건」을
기준으로 한다.
| 조건 | 기준 | 이유 |
|---|---|---|
| 머신 | 다른 빌드가 돌지 않는 머신. 측정 직전 load average(1분)를 회차마다 적는다. 15를 넘은 회차는 "부하 높음"으로 표시하고 비교에 쓰지 않는다 | 기동 시간이 머신 부하에 따라 ±20% 움직였다(같은 문서 3.1절) |
| JVM | 옵션을 고정하고 적는다. 예: -Xmx1g -XX:+ExitOnOutOfMemoryError, G1 기본 |
호스트에서 MaxRAMPercentage=75는 22 GiB 힙이 된다. 1 GiB 컨테이너에 가까운 값을 골랐다 |
| DB | 자원을 제한한 컨테이너(예: postgres:16-alpine, --cpus 4 --memory 1g), 튜닝 없음 |
DB 자원이 달라지면 앱 변경 효과를 가린다 |
| 데이터 | 행 수를 정해 적는다(예: work_log 10,000행). 측정 중 늘어나는 테이블은 행 수를 함께 적는다 |
poster가 측정 중 23,071행까지 늘어 처리량이 회차마다 떨어졌다(같은 문서 3.3절) |
| 부하 생성 | 닫힌 루프 N 스레드, 앞 20% 워밍업 버림, 생성기가 같은 호스트면 한계로 적는다 | wrk·hey가 없어 JDK HttpClient로 만든 생성기를 썼다 |
| 반복 | 3회 반복, 중앙값. 튀는 회차는 이유와 함께 적고 비교에서 뺀다 | 같은 문서 3.3절(334 rps로 튄 회차를 비교에 쓰지 않음) |
| 캐시 | 애플리케이션 캐시 상태, DB 버퍼 캐시 상태(워밍업 뒤)를 적는다 |
3. 측정 방법
다시 재는 명령은 1101/09-performance-measurement.md 「측정 명령 (다시 돌리는 법)」에 있다. 요약:
- SQL 수: PG에서
alter system set log_statement='all'→ 요청 하나 → 로그의statement·execute줄 수 → 측정 뒤'none'으로 되돌림. 앱 설정을 바꾸지 않는다. - 부하: 같은 요청을 동시성 N으로 15초, 앞 3초 버림.
- CPU: 부하 중
jcmd <pid> JFR.start … duration=20s→jfr print --events jdk.ExecutionSample로 상위 프레임 집계. - 설정만 바꾼 실험: 코드는 그대로 두고 시스템 프로퍼티 하나만 바꾼다. 예:
-Dspring.jpa.properties.hibernate.default_batch_fetch_size=100만으로 목록 처리량이 2.9배가 됐다(같은 문서 3.4절). 코드를 바꾸기 전에 설정으로 원인을 확인한다.
측정 스크립트(run-app.sh, Load.java, sqlcount.sh)는 그때 scratchpad에 두었고 repo에는 없다. 다시 재려면 위 문서의 명령으로
다시 만든다. [제안] 다음 성능 라운드에서 스크립트를 scripts/perf/로 넣을지 소유자가 정한다.
4. 기준선
기준선은 잰 커밋과 함께만 쓴다. 아래 숫자는 현재 HEAD에서 다시 잰 값이 아니다. 성능 작업을 시작하면 현재 커밋에서 다시 재고 이 표와 비교한다.
| 측정 | 값 | 커밋·출처 |
|---|---|---|
| 기본 조합 bootJar / 기동 중앙값 / 빈 수 | 41.4 MB / 3.44 s / 407 | 01a8a2a70, 1101/09-performance-measurement.md 3.1절 |
| 샘플 bootJar / 기동 중앙값 / 빈 수 | 99.0 MB / 8.05 s / 603 | 같음 |
| 필터 체인만 지나는 요청 | 27,130 rps, p50 0.51 ms | 같은 문서 3.4절 (d) |
| 샘플 단건 조회 | 5,521 rps, p50 2.70 ms, SQL 7개 | 같은 문서 3.2·3.3절 |
| 샘플 목록 20건 | 829 rps, p50 15.54 ms, SQL 46개 | 같음(수정 전) |
| 샘플 목록 20건(09-01 수정 뒤) | SQL 46 → 6, 765 → 2,528 rps | 1101 README 14절 r2-09(묶음 보고 — E0, 다시 재지 않음) |
| 관측 기능 비용 | 처리량 약 3% | 같은 문서 3.4절 (b) |
| 가상 스레드 | 처리량 차이 없음(병목은 커넥션 10개와 DB 왕복) | 같은 문서 3.3절 |
| 게이트 시간(desktop, 12코어·31GB) | ci+verifyDependencyLocks 5분 42초, mainCheck 8분 8초, integrationCheck 17분 10초 |
2c692554, 1103 README 17.2절 |
5. 결과를 믿을 조건
- 커밋 외 변수가 하나다. 전후 측정이 같은 머신·JVM 옵션·DB 자원·데이터·동시성에서 나왔다.
- 반복과 중앙값이 있다. 1회 측정은 비교 근거가 아니다.
- 부하가 기록돼 있다. 회차마다 직전 load average.
- 측정은 E3다. 실험실 결과이고 운영 증거가 아니다(02장 4절). "운영에서 N배 빨라진다"고 쓰지 않는다.
- 성능 단언을 켠 상태로 돌렸다. 일부 performance lane은 시간 단언을
performance.assertions.enabled속성으로 켠다. workflow는 이 값을true로 준다(.github/workflows/integration-main.yml:198). leaf마다 기본값이 다르다: httpclient lane은false(src/adapter/outbound/httpclient/build.gradle:196-197), persistence-mongo lane은true(src/adapter/outbound/persistence-mongo/build.gradle:243-244). desktop에서performanceCheck를 돌릴 때는 workflow와 같게-Pperformance.assertions.enabled=true를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다. - 꼬리 지연의 원인을 확인하지 않았으면 그렇게 적는다. 예: SQL을 46 → 8로 줄여도 p95가 그대로였고, TCP delayed ACK가 의심되지만 확인하지 않았다(같은 문서 3.4절 — 미검증으로 기록).
6. 회귀를 막는 법
숫자는 다음 변경에서 다시 나빠진다. 고친 비용은 테스트로 고정한다.
| 장치 | 무엇을 고정하나 | 단계 |
|---|---|---|
| 요청당 SQL 수 단언 | 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 — src/sample-portfolio/src/systemTest/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/WorkLogStatementCostSystemTest.java |
sample systemTest(mainCheck) |
| 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료(adapter/inbound/web performanceTest, webJettyPerformanceTest), HTTP client 풀·스트리밍·재시도(httpClientPerformanceTest), Hikari 풀(jpaPlatformPoolContractTest) |
performanceCheck(main·nightly) |
| 마이크로 벤치마크 | JMH source set(src/messaging/messaging-kafka/src/jmh, src/messaging/messaging-testkit/src/jmh, src/adapter/outbound/httpclient/src/jmh) |
명시 실행 |
- 시간 단언은 다른 빌드가 돌지 않는 머신에서만 의미가 있다. 그래서 performance lane은 PR·main 단계가 아니라
performanceCheck에 있다(src/build.gradleperformanceCheck위 주석). - SQL 수·호출 수처럼 머신과 무관한 숫자를 먼저 고정한다. 시간보다 덜 흔들린다.
7. 최적화를 고르는 순서
비용이 작은 개선부터 비교한다(가이드 31절 「비용이 작은 개선부터 비교」).
- 설정: 이미 열린 설정 키로 해결되는지 본다(
default_batch_fetch_size처럼). - DB: 인덱스·유일 제약·쿼리 모양. 순차 스캔은 인덱스로(
1101/09-02). 중복 규칙은 DB 유일 제약 하나로 느린 검사 쿼리와 동시 중복을 함께 없앤다. - 매핑·쿼리 코드: N+1, 불필요한 컬렉션 재작성(
1101/09-06), 트랜잭션마다 생기는 왕복(1101/09-05). - 구조: 캐시·비동기·새 인프라는 마지막이다. 캐시를 넣으면 무효화·경합을 함께 검증해야 한다(
1101/05-04).
지금 이해하면 되는 것
- 목표가 없는 템플릿이라 "요청당 비용"과 "데이터 수 비례"로 판정한다.
- 기준선은 잰 커밋과 함께만 쓰고, 측정 조건(부하·JVM·DB·데이터·반복)을 같이 적는다.
- 고친 비용은 SQL 수 같은 머신 무관 숫자로 먼저 고정한다. performance lane은 단언 속성을 켜고 돌린다.