9. 모니터링 API

DataAPI는 운영 상태를 확인하기 위한 모니터링 API를 제공한다. 모니터링 API는 SQL API와 별도의 권한으로 접근할 수 있으며, DATA_API_MONITORING role이 필요하다. 자세한 권한 설정 방법은 3장 DB role과 권한 준비를 참고한다.

9.1 Connection Pool 상태 조회

엔드포인트 :

GET /dataapi/actuator/connectionpools

동적 커넥션 풀의 현재 상태를 스냅샷 형태로 반환한다.

현재 생성되어 있는 JWT 및 Basic Connection Pool의 상태를 조회한다. 응답에는 Connection Pool 개수, draining Pool 개수, 활성화 커넥션 수, 유휴 커넥션 수 등의 정보가 포함된다.

응답 예시:

{
  "summary": {
    "jwtPoolCount": 3,
    "basicPoolCount": 2,
    "drainingPoolCount": 1,
    "activeBorrowCount": 4,
    "createFlightCount": 1
  },
  "jwtPools": [
    {
      "poolKey": "sqlUserA",
      "username": "sqlUserA",
      "draining": false,
      "activeBorrowCount": 2,
      "activeConnections": 2,
      "idleConnections": 1,
      "totalConnections": 3,
      "threadsAwaitingConnection": 0
    }
  ],
  "basicPools": [
    {
      "poolKey": "basicUser:...",
      "username": "basicUser",
      "draining": true,
      "activeBorrowCount": 0,
      "activeConnections": 0,
      "idleConnections": 0,
      "totalConnections": 0,
      "threadsAwaitingConnection": 0
    }
  ]
}

응답 필드의 의미는 다음과 같다.

필드	설명
summary.jwtPoolCount	현재 생성된 JWT Bearer 커넥션 풀 개수
summary.basicPoolCount	현재 생성된 Basic 커넥션 풀 개수
summary.drainingPoolCount	Draining 상태1인 커넥션 풀 수
summary.activeBorrowCount	모든 JWT Bearer 및 Basic 커넥션 풀에서 현재 대여중인 커넥션 수의 합
summary.createFlightCount	생성 작업이 진행 중인(생성이 완료되지 않은) 풀의 개수. 현재 진행 중인 커넥션 풀 생성 작업 수
jwtPools	JWT Bearer 커넥션 풀별 상세 목록
basicPools	Basic 풀별 상세 목록
poolKey	커넥션 풀 식별자
username	해당 풀의 사용자명
draining	Draining 상태 여부
activeBorrowCount	해당 풀에서 현재 대여 중인 커넥션 수
activeConnections	Hikari 풀에서 현재 사용중인 커넥션 수
idleConnections	Hikari 풀에서 현재 유휴 상태인 커넥션 수
totalConnections	Hikari 풀의 전체 커넥션 수
threadsAwaitingConnection	커넥션 할당을 기다리는 스레드 수

9.2 메트릭 조회

엔드포인트 :

GET /dataapi/actuator/metrics

Micrometer에 등록된 개별 메트릭 값을 조회한다. 대표 조회 대상은 아래와 같다.

• dataapi.pool.count
• dataapi.pool.draining.count
• dataapi.pool.borrow.active

9.3 Prometheus 메트릭 조회

엔드포인트 :

GET /dataapi/actuator/prometheus

/actuator/prometheus는 Prometheus가 수집할 수 있는 형식으로 DataAPI의 메트릭을 제공한다. Prometheus와 같은 모니터링 시스템은 이 엔드포인트를 주기적으로 수집(scrape)하여 DataAPI의 운영 상태를 모니터링할 수 있다.

장기간 메트릭을 수집하는 환경에서는 JWT 인증보다 DATA_API_MONITORING role이 부여된 Basic 인증 계정을 사용하는 것을 권장한다. JWT 인증은 Access 토큰 만료, 로그아웃, 세션 초기화 또는 서버 재시작 등의 이유로 인증이 실패할 수 있기 때문이다.

---

1. Draining 상태는 새로운 요청은 받지 않고, 사용 중인 커넥션이 반환될 때까지 종료를 진행하는 상태를 의미한다. ↩