스프링 서버에서 커넥션 풀(Connection Pool) 확인하고 조절하는 방법 (HikariCP/Actuator)

0. 3줄 요약

1. Actuator 의존성 추가

dependencies {implementation 'org.springframework.boot:spring-boot-starter-actuator'}

2. 서버 재시작 후 터미널에 명령어 치고 커넥션 상태 확인

curl.exe -s http://localhost:8080/actuator/metrics/hikaricp.connections

3. application.properties 기준

# 최대 커넥션 수 조절
spring.datasource.hikari.maximum-pool-size=20

1. 왜 커넥션 풀을 볼까

저는 서버에 부하 테스트를 하였고 RPS가 올라감에 따라 응답속도가 증가하는 경험을 하였습니다.

응답속도가 높아져 timeout이 발생했고, 원인 후보 중 하나로 DB 커넥션 풀 포화를 의심했습니다. 커넥션 풀이 부족하면 요청이 커넥션을 얻기까지 대기하게 되고(pending 증가), 그 대기가 길어지면 결국 timeout으로 이어질 수 있습니다. 그래서 Actuator 메트릭으로 현재 커넥션 풀 상태를 확인한 뒤, 필요하다면 최대 풀 크기를 조절해 보기로 했습니다.

DB 커넥션은 무겁고 비싼 자원입니다.
커넥션 풀이 너무 작으면 요청이 몰릴 때 커넥션을 못 구해서 대기(pending) 증가 → 응답 지연/타임아웃이 나고,
너무 크면 DB가 감당 못해서 DB CPU/메모리/스레드 폭증, 락 경합 증가, 전체가 느려질 수 있습니다.

---

2. 현재 커넥션 풀 상태 확인하기

2-1. Actuator 의존성 추가

Gradle

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

2-2. metrics 엔드포인트 노출

application.properties

management.endpoints.web.exposure.include=health,info,metrics,threaddump
management.endpoint.health.show-details=always

서버 재시작후

curl.exe http://localhost:8080/actuator

이런식으로 mertrics가 잘 보이면 Actuator 엔드포인트 노출이 제대로 된 상태입니다.

---

3. HikariCP 커넥션 풀 메트릭 조회하기

3-1. Total 커넥션 수 확인하기

curl.exe -s http://localhost:8080/actuator/metrics/hikaricp.connections

value: 10 이라고 나와있습니다. 이는 현재 풀에 존재하는 전체 커넥션 수가 10이라는 것입니다. 보통 active + idle의 합입니다. (최대치는 아님)

3-2. active/idle/pending/max

무슨 메트릭이 있는지 목록을 확인할 수 있습니다. 아래 사진을 잘 보시면 connections.active, .pending , .timeout, idle등 여러가지를 확인할 수 있습니다.

curl.exe -s http://localhost:8080/actuator/metrics | findstr /i hikaricp

• hikaricp.connections.active : 사용 중 커넥션 수
• hikaricp.connections.idle : 유휴 커넥션 수
• hikaricp.connections.pending : 커넥션을 못 구해 대기 중인 스레드 수(병목 신호)
• hikaricp.connections.max : 풀 최대치
• hikaricp.connections.min : 풀 최소치

curl.exe -s "http://localhost:8080/actuator/metrics/hikaricp.connections.active?tag=pool:HikariPool-1"
curl.exe -s "http://localhost:8080/actuator/metrics/hikaricp.connections.idle?tag=pool:HikariPool-1"
curl.exe -s "http://localhost:8080/actuator/metrics/hikaricp.connections.pending?tag=pool:HikariPool-1"
curl.exe -s "http://localhost:8080/actuator/metrics/hikaricp.connections.max?tag=pool:HikariPool-1"

현재 풀 최대 커넥션 수가 10입니다.(maximum-pool-size:10)

현재 유휴상태 커넥션이 10개입니다.

현재 DB에 붙어서 실제로 사용중인 커넥션이 0개입니다.

커넥션을 못구해서 기다리는 스레드가 0개입니다.

---

4. 커넥션 풀 설정 변경(HikariCP)

properties기준

# 최대 커넥션 수
spring.datasource.hikari.maximum-pool-size=20

# 최소 유휴 커넥션
spring.datasource.hikari.minimum-idle=10

# 커넥션을 못 구했을 때 기다리는 최대 시간(ms)
spring.datasource.hikari.connection-timeout=30000

# 유휴 커넥션 제거 기준(ms)
spring.datasource.hikari.idle-timeout=600000

# 커넥션 최대 생존시간(ms)
spring.datasource.hikari.max-lifetime=1800000

---

5. 코드로 커넥션 풀 상태 출력하기

import com.zaxxer.hikari.HikariDataSource;
import com.zaxxer.hikari.pool.HikariPoolMXBean;
import javax.sql.DataSource;

public class PoolLogger {
    public static void print(DataSource dataSource) {
        HikariDataSource hikari = (HikariDataSource) dataSource;
        HikariPoolMXBean mx = hikari.getHikariPoolMXBean();

        System.out.println("최대 풀 개수 =" + hikari.getMaximumPoolSize());
        System.out.println("최소 Idle=" + hikari.getMinimumIdle());
        System.out.println("전체 풀=" + mx.getTotalConnections()
                + ", active=" + mx.getActiveConnections()
                + ", idle=" + mx.getIdleConnections()
                + ", awaiting=" + mx.getThreadsAwaitingConnection());
    }
}

---