Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Permalink Blame History

title, source_type, status, confidence, url, archive_url, tags, related_branches, related_projects, created, last_reviewed

title

source_type

status

confidence

url

archive_url

HikariCP — About Pool Sizing & MBean Monitoring

Layer: raw/official-docs/ — HikariCP GitHub Wiki ("About Pool Sizing" + "MBean (JMX) Monitoring and Management") verbatim 발췌. ca-tmpl persistence baseline 의 Hikari pool 크기 결정과 alert threshold 의 1차 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-persistence-failure-baseline	"pool 은 크게 둘수록 좋다" 직관을 거부하는 공식 근거 → connection pool 크기를 작게 유지하는 default 결정의 baseline
raw/branch-notes/feature-metrics-alerting-contract	Hikari alert threshold (`pool wait p99 > 100ms 5분`, `pool exhaustion > 1m`) 를 MBean / Micrometer metric 으로 측정 가능하다는 사실 근거

특정 branch 없이 foundational 조사로 수집한 경우:

raw/project-notes/ca-skeleton-operational-contract — ca-tmpl operational contract 의 persistence failure / metrics 계약 초기 조사

컨텍스트 / 왜 저장했는지

ca-tmpl persistence baseline 의 Hikari pool wait p99 / pool exhaustion alert threshold 정의 근거. pool 크기 결정과 metric 노출 기준을 공식 wiki 에서 인용. 또한 "pool 은 크다고 좋은 것이 아니다" 라는 직관 반박을 공식 출처로 확보.

출처 / Source

원본 URL: https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing
보조 URL: https://github.com/brettwooldridge/HikariCP/wiki/MBean-(JMX)-Monitoring-and-Management
아카이브 URL: (미수집)
저자 / 조직: Brett Wooldridge (HikariCP maintainer)
발행일: rolling wiki
마지막 확인일: 2026-05-27 (WebFetch 검증 완료 — About Pool Sizing + MBean 페이지)
보조 자료: PgBouncer documentation, Oracle "Real-World Performance" pool sizing talk (별도 raw 미수집)

핵심 인용 / Key quotes (verbatim)

[§Axiom: You want a small pool, saturated with threads waiting for connections.] "You want a small pool, saturated with threads waiting for connections."

[§The Formula] "The formula below is provided by the PostgreSQL project as a starting point, but we believe it will be largely applicable across databases. You should test your application, i.e. simulate expected load, and try different pool settings around this starting point: connections = ((core_count * 2) + effective_spindle_count)"

[§10,000 Simultaneous Front-End Users] "If you have 10,000 front-end users, having a connection pool of 10,000 would be shear insanity. 1000 still horrible. Even 100 connections, overkill."

[§10,000 Simultaneous Front-End Users] "You want a small pool of a few dozen connections at most, and you want the rest of the application threads blocked on the pool awaiting connections."

[§Pool-locking] "pool size = Tn x (Cm - 1) + 1" (where Tn = maximum number of threads, Cm = maximum simultaneous connections held by a single thread — "minimum required to avoid deadlock")

[§MBean — Accessible Attributes] "IdleConnections, ActiveConnections, TotalConnections, ThreadsAwaitingConnection"

[§MBean — Invocable Actions] softEvictConnections(), suspendPool(), resumePool()

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
HIKARI-POOL-C1	HikariCP 의 axiom: pool 은 작게 유지하고, 나머지 application thread 는 connection 대기에서 block 시킨다	[§Axiom] "You want a small pool, saturated with threads waiting for connections."	`official-vendor-doc`	HikariCP 사용 환경 일반	"작은 pool" 의 정확한 크기 (특정 절대값) 를 정의하지는 않음 — formula 와 별도
HIKARI-POOL-C2	PostgreSQL project 가 제공하는 starting-point formula: `connections = ((core_count * 2) + effective_spindle_count)`. 단, 어디까지나 starting point 이며 실제 부하 테스트로 조정 권고	[§The Formula] "...starting point: connections = ((core_count * 2) + effective_spindle_count)" + "You should test your application, i.e. simulate expected load, and try different pool settings around this starting point"	`official-vendor-doc`	디스크 IO-bound DB 워크로드 starting point	모든 워크로드(특히 SSD/NVMe, in-memory)에 그대로 적용된다는 뜻은 아님 — "starting point" 명시. spinning disk 가정
HIKARI-POOL-C3	10,000 front-end user 에게 10,000 connection pool 은 "shear insanity"; 1,000 도 horrible; 100 조차 overkill. "a few dozen connections at most" 권고	[§10,000 Simultaneous Front-End Users] "If you have 10,000 front-end users, having a connection pool of 10,000 would be shear insanity. 1000 still horrible. Even 100 connections, overkill." + "You want a small pool of a few dozen connections at most"	`official-vendor-doc`	high-concurrency web application sizing 직관 반박	모든 application 에 "수십 개" 가 충분하다는 절대값 보증은 아님 — formula + 부하테스트 필요. ("just trust me" 같은 paraphrase 는 페이지에 verbatim 없음)
HIKARI-POOL-C4	Pool-locking 방지 minimum 공식: `pool size = Tn × (Cm − 1) + 1` (Tn=max threads, Cm=max simultaneous connections per thread)	[§Pool-locking] "pool size = Tn x (Cm - 1) + 1"	`official-vendor-doc`	한 thread 가 동시에 다수 connection 을 점유할 수 있는 워크로드	이 값이 최적 (optimal) 이라는 뜻 아님 — "minimum required to avoid deadlock"
HIKARI-POOL-C5	HikariPool MBean 은 다음 attribute 노출: `IdleConnections`, `ActiveConnections`, `TotalConnections`, `ThreadsAwaitingConnection`. Invocable: `softEvictConnections()`, `suspendPool()`, `resumePool()`	[§MBean — Accessible Attributes] "IdleConnections, ActiveConnections, TotalConnections, ThreadsAwaitingConnection"	`official-vendor-doc`	JMX / MBean 직접 조회 환경	snapshot 값이며 page warning: "values are extremely ephemeral and reflect a snapshot in time when measured" — programmatic 결정 근거로 직접 사용 비권장
HIKARI-POOL-C6	Micrometer 통합이 제공하는 metric 이름 (`hikaricp.connections.active`, `.idle`, `.pending`, `.acquire` timer, `.usage` timer 등)	(원본 frontmatter 발췌 — HikariCP 측 wiki 가 아닌 Micrometer / Spring Boot Actuator 통합 문서에서 유래)	`needs-confirmation`	Spring Boot + Micrometer 환경	HikariCP 공식 wiki 페이지 자체가 이 metric 명을 직접 정의하지는 않음 — Micrometer / Spring Boot 측 별도 출처 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- HIKARI-POOL-C1 ~ C5: pool 크기 axiom, formula, pool-locking 공식, MBean attribute/action 이름
- "작은 pool + 대기 thread" 가 throughput 측면에서 합리적이라는 정성적 근거
이 자료가 증명하지 않는 것:
- 정확한 SLA 수치 (예: "p99 acquire > 100ms 가 위험 임계") 는 HikariCP 가 직접 말하지 않음 — 운영자가 정해야 하는 SLO
- hikaricp.connections.acquire 같은 Micrometer metric 이름 은 HikariCP wiki 본문에 직접 등장하지 않음 (HIKARI-POOL-C6 참조 — Micrometer / Spring Boot Actuator 측 별도 검증 필요)
- SSD/NVMe 또는 PgBouncer transaction pooling 환경에서의 formula 보정값은 본 페이지 범위 밖
- "just trust me" 같은 paraphrase 는 현재 페이지에 verbatim 없음 — 원본 frontmatter 의 해당 인용은 paraphrase 임을 명시
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 pool wait p99 > 100ms 5분 threshold 는 우리 SLA 기준이지 HikariCP 권고가 아님 — 별도 SLO 근거 문서 필요
- Micrometer metric 이름 (hikaricp.connections.acquire, .pending, .timeout, .creation) 의 정확한 정의는 Spring Boot Actuator / Micrometer 측 raw 자료 추가 필요
- PgBouncer 와 결합 시 application-side Hikari pool 크기의 의미 (별도 자료)

메모 / Notes (내 프로젝트 해석 — 검증 전 추론)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

핵심 의미:
- pool 은 크게 둘수록 좋다는 직관이 틀렸다 (HIKARI-POOL-C1, C3). DB 의 동시 작업 처리량은 core 수에 묶임. pool 이 커지면 context switch overhead 로 throughput 감소.
- pool 대기 시간 (hikaricp.connections.acquire) 이 진짜 SLA signal. 단순 active/max 비율이 아님 (HikariCP wiki 가 권고하는 axiom 의 해석).
ca-tmpl alert threshold 매핑 (해석):
- pool wait p99 > 100ms 5분 → hikaricp.connections.acquire p99 로 측정 가정 (Micrometer metric 명 확인 필요)
- pool exhaustion (active = max) > 1분 → hikaricp.connections.pending > 0 지속
추가 권장 metric (Micrometer 측 확인 후):
- hikaricp.connections.timeout — connectionTimeout 초과 누적
- hikaricp.connections.creation — 신규 connection 생성 시간 (DB/network 이슈 signal)
한계: 공식 (cores*2 + spindles) 은 spinning disk 기준. SSD/NVMe 면 보정 필요. PgBouncer transaction pooling 을 쓰면 application pool size 의미가 달라짐 (HIKARI-POOL-C2 가 "starting point" 로 명시).

같은 주제 다른 official-doc / company-tech-blog: (Micrometer + Spring Boot Actuator 의 Hikari metric 정의는 별도 raw 후속 수집 필요)
인용하는 branch:
- raw/branch-notes/feature-persistence-failure-baseline
- raw/branch-notes/feature-metrics-alerting-contract
인용하는 wiki: (미작성 — /ingest 시 wiki/concepts/connection-pooling 또는 wiki/concepts/hikaricp-tuning 후보)
대안 그룹 (ca-tmpl 결정 컨텍스트): Group G-C — Persistence failure (Hikari 단일 pool / PgBouncer 사이드카 / DataSource proxy 측정 / per-tenant separate pool)

10 KiB Raw Permalink Blame History Unescape Escape