나만의 코딩기록

DB Lock

chanyoun — Mon, 20 Jul 2026 11:02:37 +0900

DB Lock

여러 사용자가 재고 1개인 상품을 동시에 구매하려고 하면, 재고를 확인하고 차감하는 사이에 서로의 작업이 겹칠 수 있습니다. 이러한 상황을 Race Condition 이 발생했다 라고 합니다. Lock은 이런 상황에서 데이터가 틀어지지 않도록 접근 순서를 지키게 하는 장치입니다.

이 글은 MySQL 8.0 InnoDB, 격리 수준은 기본값인 REPEATABLE READ를 전제로 합니다. 격리 수준이 READ COMMITTED이면 뒤에서 설명할 Gap Lock의 동작이 달라지므로, 재현이 되지 않는다면 먼저 격리 수준을 확인하는 것을 추천드립니다.

-- 격리수준을 확인할수 있는 명령어
SELECT @@transaction_isolation;

Shared Lock (S Lock)

Shared Lock은 여러 트랜잭션이 함께 읽을 수 있게 하는 잠금입니다. S Lock을 사용하는 이유는, 읽은 값이 트랜잭션이 끝날 때까지 다른 트랜잭션에 의해 바뀌지 않도록 고정하기 위함입니다.

잠금 없는 일반 SELECT와의 차이는 아래 쿼리에서 확인할수 있습니다.

-- [A]
START TRANSACTION;
SELECT * FROM child WHERE id = 10;        -- name 확인, 스냅샷 생성

-- [B]
START TRANSACTION;
UPDATE child SET name = 'changed' WHERE id = 10;
COMMIT;

-- [A]
SELECT * FROM child WHERE id = 10;            -- 예전 값
SELECT * FROM child WHERE id = 10 FOR SHARE;  -- 'changed'

마지막 A 트랜잭션의 두 SELECT가 서로 다른 값을 반환하는 것을 확인할 수 있습니다.

MySQL InnoDB 기준, 하나의 트랜잭션 안에서 일반 SELECT은 MVCC를 통해 최초 스냅샷의 정보를 그대로 가져옵니다. 이는 REPEATABLE READ (Mysql InnoDB 의 기본값 격리수준), 즉 하나의 트랜잭션에서 한 번 읽은 값은 계속 같은 값으로 보인다는 격리 수준의 특성입니다.

그러나 S Lock을 사용해 SELECT 하는 순간, 스냅샷이 아닌 미커밋 변경이 있으면 기다린 뒤 가장 최근 커밋 상태를 읽어, 트랜잭션 B가 변경한 changed를 가져오게 됩니다. 그리고 그 시점부터 다른 트랜잭션의 X Lock을 막으므로, 방금 읽은 값은 커밋할 때까지 유효하다는 것이 보장됩니다.

결론적으로 S Lock으로 읽은 데이터는 읽는 시점의 최신값이며, 해당 트랜잭션이 커밋될 때까지 그 값이 유지됩니다.

-- [A] S Lock 획득
START TRANSACTION;

SELECT * FROM child
WHERE id = 10
FOR SHARE;


-- [B] 다른 세션에서 실행

START TRANSACTION;

SELECT * FROM child
WHERE id = 10; -- 즉시 성공: 일반 SELECT는 잠금을 요청하지 않음

SELECT * FROM child
WHERE id = 10
FOR SHARE; -- 즉시 성공: S Lock끼리는 함께 획득 가능

SELECT * FROM child
WHERE id = 10
FOR UPDATE; -- 대기: X Lock은 S Lock과 충돌

UPDATE child
SET name = 'blocked'
WHERE id = 10; -- 대기: UPDATE는 X Lock이 필요

위 쿼리를 통해 다른 트랜잭션도 같은 데이터에 S Lock을 획득해 함께 읽을 수 있지만, X Lock을 획득해 수정하려 하면 대기하는것을 확인할 수 있습니다.

Exclusive Lock (X Lock)

Exclusive Lock은 한 트랜잭션이 행을 수정할 수 있게 하는 배타 잠금입니다. SELECT ... FOR UPDATE로 직접 요청할 수도 있고, UPDATE와 DELETE를 실행하면 자동으로 획득됩니다.

S Lock과 X Lock의 차이는 읽기 보호인지, 수정 독점인지에 있습니다.
S Lock은 읽은 데이터를 기준으로 작업하는 동안 값이 변경되지 않도록 보호하는 잠금입니다. 따라서 다른 트랜잭션도 함께 읽을 수 있지만, 수정은 할 수 없습니다.
X Lock은 해당 데이터를 직접 수정하기 위해 획득하는 잠금입니다. 수정 중인 데이터에 다른 트랜잭션이 잠금 읽기하거나 수정하는 것까지 막아, 수정 작업을 한 트랜잭션만 수행하도록 보장합니다.

S Lock이 여러 트랜잭션에 공유되는 것과 달리, X Lock은 한 트랜잭션만 가질 수 있습니다. 다만 모든 접근을 막는 것은 아니고, 무엇이 막히고 무엇이 통과하는지는 아래 쿼리에서 확인할 수 있습니다.

-- [A] X Lock 획득

START TRANSACTION;
SELECT * FROM child WHERE id = 10 FOR UPDATE;


-- [B]

START TRANSACTION;
SELECT * FROM child WHERE id = 10; -- 즉시 성공
SELECT * FROM child WHERE id = 10 FOR SHARE; -- 대기
SELECT * FROM child WHERE id = 10 FOR UPDATE; -- 대기
UPDATE child SET name = 'blocked' WHERE id = 10; -- 대기

-- dbeaver 의 서로다른 스크립트 작성 페이지를 열어 테스트하면 대기 하는것을 확인할 수 있습니다.

B의 네 문장 중 첫 번째만 통과하고 나머지 세 개는 A가 커밋할 때까지 대기합니다. 즉 X Lock이 걸린 행에 대해 다른 트랜잭션의 S Lock과 X Lock은 모두 불가능하지만, 잠금 없는 일반 SELECT는 영향을 받지 않습니다.

잠금 없는 SELECT가 통과하는 것은 MVCC 덕분입니다. 잠긴 행을 기다리는 대신 최초 스냅샷의 값을 읽기 때문에, A가 무엇을 하고 있든 상관없이 즉시 결과를 반환합니다. 앞서 S Lock에서 본 것과 같은 원리입니다.

결론적으로 X Lock은 수정할 행을 다른 트랜잭션이 수정하거나, S Lock, X Lock 하는 것을 커밋 시점까지 차단합니다.

Intention Lock (IS Lock, IX Lock)

Intention Lock은 행에 S Lock 또는 X Lock을 잡으려는 의도를 테이블 수준에 표시하는 잠금입니다. 쿼리를 따로 직접 요청하는 것이 아니라 InnoDB가 자동으로 획득합니다. SELECT ... FOR SHARE는 IS Lock을, SELECT ... FOR UPDATE는 IX Lock을 설정합니다.

행에 S Lock을 얻으려면 먼저 테이블에 IS Lock 을 획득해야 하고, 행에 X Lock을 얻으려면 먼저 IX Lock을 획득해야 합니다. 즉 모든 행 잠금 앞에는 반드시 테이블 수준의 의도 표시가 먼저 붙습니다.

Intention Lock 이 필요한 이유는 테이블 전체를 잠그려는 트랜잭션 때문입니다. Intention Lock이 없다면, 테이블을 잠그려는 트랜잭션은 그 테이블의 모든 행을 하나씩 확인해서 잠긴 행이 있는지 검사해야 합니다. 테이블 수준에 IS, IX 표시를 남겨두면 이 검사가 한 번으로 끝납니다.

주의할 점은 Intention Lock 자체가 무언가를 막는 잠금이 아니라는 것입니다. Intention lock은 LOCK TABLES ... WRITE 같은 테이블 전체 요청 외에는 아무것도 막지 않습니다. 따라서 IS Lock끼리는 서로 충돌하지 않고, IX Lock끼리도 서로 충돌하지 않습니다. IX는 이 테이블의 어떤 행을 잠글 것이라는 사실만 담고 있을 뿐, 그것이 어느 행인지에 대한 정보는 없기 때문입니다. 만약 IX끼리 충돌한다면 서로 다른 행을 수정하는 트랜잭션들이 전부 대기하게 되어(락 전에 IX Lock 을 하므로), 행 수준 잠금이 존재할 이유가 사라집니다. 실제 충돌 판정은 다음 단계인 행 수준 잠금에서 일어납니다.

결과적으로 Intention Lock은 평소에 아무것도 막지 않고 기록만 남기다가, 테이블 전체를 잠그려는 요청이 들어왔을 때 빠르게 판정하는 역할을 합니다.

다음과 같은 쿼리를 통해 IS , IX Lock 을 확인해볼수있습니다.

START TRANSACTION;
SELECT * FROM child WHERE id = 10 FOR SHARE;

-- 서로다른 세션에서 (dbeaver 라면 서로 다른 스크립트 창에서 진행하면 됩니다.)

SELECT OBJECT_NAME, LOCK_TYPE, LOCK_MODE, LOCK_DATA
FROM performance_schema.data_locks
WHERE OBJECT_NAME = 'child';

해당 결과를 통해 TABLE, RECORD 에 락이 걸렸고 저희는 FOR SHARE 즉 S LOCK 을 획득했기에 IS Lock 이 걸린것을 확인할수 있습니다.

Record Lock

Record Lock은 인덱스 레코드 하나를 잠그는 잠금입니다.

SELECT id FROM product WHERE id = 10 FOR UPDATE;

이 쿼리는 id = 10인 행에 대해 다른 트랜잭션의 수정, 삭제, lock 을 막습니다.

여기서 중요한 점은 Record Lock이 행이 아니라 인덱스 레코드를 잠근다는 것입니다. InnoDB는 내부적으로는 항상 클러스터드 인덱스를 사용해 행을 관리합니다.

Record locks always lock index records, even if a table is defined with no indexes.

기본 키가 있으면 기본 키가 클러스터드 인덱스가 됩니다. 기본 키와 적절한 유니크 인덱스도 없다면, InnoDB는 행을 관리하기 위한 숨겨진 클러스터드 인덱스를 내부적으로 만듭니다. 따라서 사용자가 만든 인덱스가 없어도 Record Lock이 잠글 인덱스 레코드는 항상 존재합니다.

위의 인덱스를 만든다는 말이 WHERE 조건에 사용한 컬럼의 인덱스를 자동으로 만든다는 말은 아닙니다. 예를 들어 name 컬럼에 인덱스가 없다면, WHERE name = 'A'를 실행해도 InnoDB는 name 인덱스를 새로 만들지 않습니다. 대신 기존 클러스터드 인덱스를 처음부터 스캔하며 조건을 확인합니다.

REPEATABLE READ에서 이런 잠금 읽기나 수정 쿼리를 실행하면, 스캔한 인덱스 레코드와 그 사이의 gap까지 넓게 잠길 수 있습니다. 겉으로는 테이블 전체가 막힌 것처럼 보이지만, 많은 Record Lock과 Gap Lock, 즉 Next-Key Lock이 잡힌 것입니다.

If you have no indexes suitable for your statement and MySQL must scan the entire table to process the statement, every row of the table becomes locked, which in turn blocks all inserts by other users to the table."

-- name 컬럼에 인덱스가 없다면
UPDATE product SET stock = stock - 1 WHERE name = 'A';

의도는 한 행을 수정하는 것이지만, 인덱스가 없으면 스캔 과정에서 다른 행들까지 잠기게 됩니다.

Gap Lock

Gap Lock은 이미 존재하는 행이 아니라, 인덱스 레코드 사이의 아직 없는 값이 들어올 자리를 잠급니다.

SELECT * FROM child WHERE id BETWEEN 10 AND 20 FOR UPDATE;

이 잠금은 다른 트랜잭션이 10과 20 사이에 새 값을 INSERT 하는 것을 막습니다. 같은 조건으로 두 번 조회했을 때 없던 행이 생기는 팬텀 현상을 막기 위한 장치입니다.

Gap Lock은 X Lock, S Lock 에서만 걸립니다. SELECT ... FOR UPDATE, SELECT ... FOR SHARE, UPDATE, DELETE가 대상이며, 일반 SELECT는 애초에 Gap Lock도 없습니다.

Gap Lock이 걸리는 기준

Gap Lock 이 걸리는 기준은 같은 조건의 결과가 나중에 늘어날 수 있는가입니다. 늘어날 수 있으면 그 자리를 막아야 하므로 Gap Lock이 걸리고, 늘어날 수 없으면 걸리지 않습니다.

늘어날 수 없는 경우는 하나뿐입니다. 유니크 인덱스를 = 로 조회했고, 그 값의 행이 실제로 존재할 때입니다.

SELECT * FROM child WHERE id = 11 FOR UPDATE;

id가 기본 키이고 값이 11인 행이 존재한다면, 유니크 제약 때문에 11이 하나 더 생길 수 없습니다. 결과가 이미 확정되어 있으므로 레코드 하나에만 잠금이 걸립니다.

그외의 대부분 경우 Gap Lock이 걸립니다. 범위 조회, 논유니크 인덱스, 인덱스를 타지 못하는 조건, 기본 키로 조회했더라도 해당 행이 없으면 걸립니다. 이 섹션 첫 쿼리 WHERE id BETWEEN 10 AND 20 FOR UPDATE 예시가 기본 키인데도 Gap Lock이 걸리는 이유도 범위 조회이기 때문입니다.

여기서 기준이 되는 것은 테이블에 인덱스가 있는지가 아니라 WHERE 조건이 어떤 인덱스를 타는지입니다. 기본 키가 있는 테이블이라도 인덱스 없는 컬럼으로 조회하면 전체 스캔이 발생하고, 그 과정에서 만난 레코드와 gap이 모두 잠깁니다. 인덱스가 있더라도 옵티마이저가 전체 스캔을 선택하면 마찬가지입니다. 실제 잠금 범위가 궁금하다면 EXPLAIN으로 실행 계획을 확인하는 것이 명확한 락의 범위를 파악할수 있습니다.

READ COMMITTED로 격리 수준을 낮추면 검색과 인덱스 스캔에서 Gap Lock이 비활성화됩니다. 이 경우 Gap Lock은 외래 키 제약 검사와 중복 키 검사에만 사용됩니다.

Next-Key Lock

Next-Key Lock은 인덱스 레코드에 대한 Record Lock과, 그 레코드 앞의 Gap Lock을 합친 잠금입니다. REPEATABLE READ에서 InnoDB가 검색과 인덱스 스캔에 사용하는 기본 잠금 방식이며, 이를 통해 팬텀 현상을 방지합니다.

공식 문서의 예시를 그대로 가져오면, 인덱스에 10, 11, 13, 20 값이 있을 때 잠금 구간은 다음과 같이 나뉩니다.

(negative infinity, 10]
(10, 11]
(11, 13]
(13, 20]
(20, positive infinity)

구간 표기가 (이전 값, 현재 값] 형태인데, 즉 왼쪽은 열려 있고 오른쪽은 닫혀 있습니다. ((10, 11]은 10은 포함하지 않고 11은 포함한다는 뜻입니다.) 이것이 "레코드 + 그 앞의 gap"이라는 정의를 그대로 나타낸 것입니다. ( 인덱스 11 을 기준으로 보면 10 초과 11이하를 막으므로 레코드 + 그앞 gap 을 막는걸 확인할수 있습니다.)

공식 문서는 이를 다음과 같이 설명합니다.

If one session has a shared or exclusive lock on record R in an index, another session cannot insert a new index record in the gap immediately before R in the index order.

마지막 구간에는 supremum이라는 개념이 등장합니다. 인덱스의 가장 큰 값보다 위쪽 구간을 잠글 때 사용하는 가상의 레코드입니다. supremum은 실제 인덱스 레코드가 아니므로, 이 next-key lock은 사실상 가장 큰 값 이후의 gap만 잠그는 효과를 냅니다. 위 구간에서 마지막 줄만 양쪽이 열려 있는 이유입니다 (20, positive infinity).

기본은 Next-Key Lock이고, 나머지는 축소된 형태입니다

공식 문서는 REPEATABLE READ에서 InnoDB가 검색과 인덱스 스캔에 next-key lock을 사용한다고 설명합니다. 즉 이것이 기본값이고, 앞서 본 Record Lock만 걸리는 경우가 오히려 예외입니다.

문서에 명시된 축소 조건은 두 가지입니다.

유니크 인덱스로 단일 행을 검색해 잠그는 경우에는 gap locking이 필요하지 않습니다
격리 수준을 READ COMMITTED로 낮추면 검색과 인덱스 스캔에서 gap locking이 비활성화됩니다

정리하면 InnoDB는 일단 레코드와 그 앞의 gap을 함께 잠그고, 팬텀이 발생할 수 없다는 것이 보장될 때만 gap을 떼어냅니다. 앞의 Gap Lock 섹션에서 정리한 기준이 곧 이 축소 조건입니다.

기본                          → Next-Key Lock (레코드 + 앞 gap)
  ├─ 유니크 인덱스 = 조회로 단일 행 특정  → Record Lock (gap lock 생략)
  └─ READ COMMITTED                    → Record Lock (gap lock 생략)

Insert Intention Lock

Insert Intention Lock은 INSERT가 행을 넣기 직전에 잡는 특수한 형태의 Gap Lock입니다. 같은 gap에 INSERT 하려는 여러 트랜잭션이, 서로 다른 위치에 넣는 것이라면 굳이 기다리지 않아도 되도록 의도를 표시하는 역할을 합니다.

먼저 이 잠금이 왜 필요한지 보겠습니다. 레코드가 10과 20만 있고 그 사이가 비어 있다고 하겠습니다.

-- [A]
START TRANSACTION;
INSERT INTO child (id) VALUES (12);

-- [B]
START TRANSACTION;
INSERT INTO child (id) VALUES (15);   -- 대기 없이 성공

둘 다 같은 gap에 INSERT 하지만 넣으려는 위치가 다르므로 서로 기다릴 이유가 없습니다. Insert Intention Lock끼리는 충돌하지 않기 때문에 이렇게 동시에 통과할 수 있습니다. 만약 INSERT가 해당 구간을 배타적으로 잡아버렸다면 뒤에 오는 INSERT가 모두 대기하게 됩니다.

반대로 이미 다른 트랜잭션이 그 구간에 Gap Lock을 잡고 있다면 대기합니다. 공식 문서의 예시를 보면, 먼저 클라이언트 A가 범위 조회로 gap에 잠금을 잡습니다.

-- child 테이블에 id 값 90, 102가 존재
-- 클라이언트 A
START TRANSACTION;
SELECT * FROM child WHERE id > 100 FOR UPDATE;

이 상태에서 클라이언트 B가 그 구간에 INSERT를 시도하면, INSERT 전 Insert Intention Gap Lock을 요청, A의 Gap Lock과 충돌해서 대기하게 됩니다.

-- 클라이언트 B
START TRANSACTION;
INSERT INTO child (id) VALUES (101);

정리하면 Insert Intention Lock끼리는 서로 막지 않고, 다른 트랜잭션이 잡아둔 Gap Lock에 의해서만 막힙니다. Gap Lock의 목적이 해당 구간으로의 INSERT를 막는 것이므로, 사실상 Insert Intention Lock이 Gap Lock에 걸리는 유일한 대상입니다.

이 잠금을 알아둬야 하는 실질적인 이유는 데드락 로그에서 보일수 있기 때문입니다.

-- 데드락 예시

-- [A]
SELECT * FROM child WHERE id BETWEEN 10 AND 20 FOR UPDATE;

-- [B]
SELECT * FROM child WHERE id BETWEEN 10 AND 20 FOR UPDATE; -- 통과! gap lock끼리 충돌 안 함

-- [A]
INSERT INTO child (id) VALUES (12); -- B의 gap lock에 막혀 대기

-- [B]
INSERT INTO child (id) VALUES (15); -- A의 gap lock에 막혀 대기 → 데드락

SHOW ENGINE INNODB STATUS의 출력에 아래와 같은 문구가 있다면, 다른 트랜잭션이 잡고 있는 gap에 INSERT를 시도하다 대기에 걸린 상황입니다.

lock_mode X locks gap before rec insert intention waiting

참조

Mysql 공식문서

Clustering, Replication, Sharding

chanyoun — Thu, 16 Jul 2026 13:14:08 +0900

Clustering, Replication, Sharding

단일 DB 서버로 구성된 상황에서 트래픽이 몰리거나, 더 이상 단일 서버로 운영하기 어려워질 수 있습니다. 상황에 따라 필요한 방법은 다르지만, 대표적으로 쓰이는 Clustering, Replication, Sharding에 대해 설명합니다.

Clustering

클러스터링은 하나가 아닌 여러 개의 서버로 구성하는 것을 말합니다.

주목적: 가용성 + 부하 분산 예시: 서버 A가 죽어도 B가 요청을 이어받아 서비스가 멈추지 않고(가용성), 평소에는 두 서버가 요청을 나눠 처리한다(부하 분산).

위 상황은 단일 DB 서버를 통해 DB 스토리지에서 원하는 데이터를 서빙하는 상황입니다. 이때 DB 서버에 문제가 생길 경우, 해당 문제는 곧 서비스 전체 장애로 이어질 수 있습니다.

따라서 위와 같은 상황을 막기 위해 단일 DB 서버가 아닌, 2개 이상의 DB 서버를 사용할 수 있습니다.

Active & Active

2개 이상의 DB 서버를 동시에 운영한다면, A 서버에 장애가 발생해도 B 서버가 요청을 처리하여 서비스를 이어갈 수 있습니다.

또한 두 서버가 요청을 나누어 처리하므로, 기존 하나의 DB 서버가 받던 부하를 분산시킬 수 있습니다.

단점 또한 존재합니다.

두 서버를 동시에 운영하는 만큼 서버 비용이 증가합니다.
그림처럼 A 서버와 B 서버가 하나의 DB 스토리지를 공유한다면, 두 서버를 운영하더라도 같은 데이터에 대한 Lock 경합과 스토리지 부하가 남아 있을 수 있습니다. 즉 DB 서버를 늘려도 공유 스토리지가 병목 지점이 될 수 있습니다.

Active & Stand-By

Active & Stand-By는 평소에는 하나의 서버만 요청을 처리하고, 다른 서버는 장애에 대비해 준비해 두는 방식입니다. Active & Active처럼 두 서버가 동시에 트래픽을 나누어 처리하지는 못하지만, Active 서버에 장애가 발생하면 Stand-By 서버로 Failover하여 서비스를 이어갈 수 있습니다.

A 서버가 정상적으로 운영 중일 때는 B 서버가 사용자 요청을 처리하지 않습니다. A 서버에 문제가 생기면 Failover하여 B 서버가 Active 역할을 맡을 수 있습니다.

다만 Stand-By 서버가 항상 꺼져 있다는 뜻은 아닙니다. 장애를 얼마나 빨리 넘길지에 따라 준비 방식이 나뉩니다.

Cold Standby: B 서버를 꺼 두거나 즉시 요청을 처리할 준비가 되지 않은 상태로 둡니다. A 서버에 문제가 생긴 뒤 B 서버를 시작하고 필요한 준비를 해야 하므로, 그 시간만큼 서비스가 중단될 수 있습니다.
Hot Standby: B 서버를 이미 실행해 두고, 장애 발생 시 빠르게 Active 역할로 전환할 수 있도록 준비합니다. 전환 시간은 짧아지지만, B 서버를 계속 운영하는 비용이 필요합니다.

즉 Cold Standby는 비용을 줄이는 대신 장애 전환 시간이 길어질 수 있고, Hot Standby는 빠른 전환을 위해 비용을 더 지불하는 방식입니다.

또한 Active & Stand-By에서는 Stand-By 서버가 평소 사용자 요청을 처리하지 않으므로, 트래픽을 분산하는 목적으로는 사용할 수 없습니다.

Replication

Replication은 말 그대로 데이터를 복제하는 것을 의미합니다. 일반적으로 Master(Primary) 서버의 변경 데이터를 Slave(Replica) 서버에 전달하여, 여러 DB가 같은 데이터 사본을 유지하도록 합니다.

주목적: 읽기 확장 (부수적으로 가용성) 예시: 쓰기는 Master가, 조회는 여러 Slave가 나눠 맡아 조회 트래픽이 몰려도 견딤!

위 그림과 같이 쓰기를 처리하는 Master 서버와, Master 서버의 데이터를 복제한 Slave 서버로 나뉘게 됩니다.

대부분의 서비스는 글 작성보다 글 조회가 훨씬 많습니다. 따라서 Master가 모든 쓰기와 조회를 처리하는 대신, Slave에게 조회를 맡기면 Master는 데이터 변경에 집중할 수 있습니다.

또한 Master DB에 문제가 생겼을 때 Slave DB를 새로운 Master로 승격하여 Failover할 수 있도록 구성할 수 있습니다. 다만 승격과 애플리케이션의 연결 전환은 별도로 준비해야 합니다.

비동기로 복제하는 경우 Master의 변경 내용이 Slave에 반영되기까지 시간이 걸릴 수 있습니다. 이를 Replication Lag 라고 부릅니다.

즉 Replication은 조회 성능과 읽기 확장에는 좋지만, Slave에서 조회한 데이터가 항상 가장 최신 데이터는 아닐 수 있다는 점을 고려해야 합니다.

Sharding

Sharding은 데이터를 복사하는 것이 아니라, 여러 DB에 나누어 저장하는 방식입니다. 어떤 DB에 저장할지는 userId와 같은 Sharding Key를 기준으로 결정합니다.

주목적: 쓰기·저장 용량 확장 예시: 회원 200만 명 데이터를 한 DB가 감당 못 할 때, userId 기준으로 Shard 1·2에 나눠 저장합니다.

위 예시에서는 userId가 1부터 1,000,000까지인 데이터는 Shard 1에, 1,000,001부터 2,000,000까지인 데이터는 Shard 2에 저장합니다.

앞서 다룬 Replication에서는 Master와 Slave가 같은 회원 정보 전체를 들고 있지만, Sharding에서는 각 DB가 자기 몫의 데이터만 들고 있습니다. 따라서 데이터가 커, 하나의 DB 저장 공간이나 쓰기 처리량만으로 감당하기 어려울 때 Sharding을 고려할 수 있습니다.

다만 Sharding에도 단점이 존재합니다. 애플리케이션은 어떤 사용자의 데이터가 어느 Shard에 있는지 알아야 하며, 서로 분리된 Shard의 데이터를 함께 조회하거나 Join해야 하면 처리가 복잡하고 비용이 커집니다.

Partitioning

Partitioning도 데이터를 나누는 방법이지만, 하나의 DB 서버 안에서 테이블을 여러 조각으로 나누는 방식입니다. 반면 Sharding은 데이터를 물리적으로 여러 DB 서버에 나누어 저장합니다.

따라서 하나의 DB 서버 자원으로 감당 가능하고, 파티션 키를 기준으로 조회 범위를 줄일 수 있다면 Partitioning을 고려할 수 있습니다. 반면 저장 용량이나 쓰기 처리량 자체가 서버 한계에 도달했다면 Sharding을 고려해야 합니다.

결론

결론적으로 Clustering은 서버 장애·부하, Replication은 읽기 부하, Sharding은 쓰기·용량 한계를 담당합니다.

상황	더 어울리는 방법
조회 요청이 너무 많음	Replication
데이터 용량, 쓰기 요청이 한 DB 한계를 넘음	Sharding
서버 장애에도 서비스를 유지하고 싶음	Active & Stand-By 또는 Active & Active
Shard 하나가 장애 나도 대비하고 싶음	각 Shard에 Replication 적용

다중 인스턴스 환경에 ShedLock 적용하기

chanyoun — Mon, 13 Jul 2026 18:03:05 +0900

ᅵ

상황

@Scheduled가 붙은 메서드는 애플리케이션 인스턴스마다 등록됩니다. 따라서 다중 인스턴스 환경에서는 같은 스케줄러가 여러 번 실행되어 기대했던 동작과 다른 결과를 만들 수 있습니다.

서버가 한 대일 때는 문제가 없지만, 무중단 배포를 위한 blue/green 환경, 오토 스케일링, 이중화 구성으로 애플리케이션 인스턴스가 둘 이상이 되면 모든 서버가 같은 시각에 같은 작업을 실행합니다.

00:00

서버 A: @Scheduled 작업 실행
서버 B: @Scheduled 작업 실행
서버 C: @Scheduled 작업 실행

이러한 중복 실행을 막기 위해 ShedLock을 사용할 수 있습니다.

ShedLock 이란?

ShedLock은 여러 인스턴스가 같은 스케줄러를 동시에 실행하지 않도록 돕는 분산 락 라이브러리입니다.

DB, Redis 같은 외부 저장소에 락 정보를 기록하고, 스케줄러 메서드를 실행하기 전에 락 획득을 시도합니다.

서버 A ─┐
서버 B ─┼─ "daily-batch" 락 획득 시도 ─ 공유 DB의 shedlock 테이블
서버 C ─┘

락 획득 성공: 메서드 본문 실행
락 획득 실패: 메서드 본문을 실행하지 않고 이번 주기 스킵

락을 획득한 인스턴스만 스케줄러 본문을 실행하고, 나머지 인스턴스는 대기하지 않고 이번 실행을 건너뜁니다.

설정

1. 의존성을 추가합니다

ShedLock은 Spring 연동 모듈과 락 저장소별 Provider를 함께 추가합니다. DB를 공유 저장소로 사용할 경우 JDBC Provider를 사용합니다.

dependencies {
    implementation "net.javacrumbs.shedlock:shedlock-spring:5.16.0"
    implementation "net.javacrumbs.shedlock:shedlock-provider-jdbc-template:5.16.0"
}

두 라이브러리의 버전은 반드시 동일하게 맞춰야 합니다.

현재 프로젝트는 Spring Boot 3.2를 사용하므로, 공식 호환표에서 Spring Boot 3.2 대상인 ShedLock 5.x 중 5.16.0을 사용했습니다.

2. 락 테이블을 생성합니다

CREATE TABLE shedlock (
    name VARCHAR(64) NOT NULL,
    lock_until TIMESTAMP(3) NOT NULL,
    locked_at TIMESTAMP(3) NOT NULL,
    locked_by VARCHAR(255) NOT NULL,
    PRIMARY KEY (name)
);

ShedLock은 이 테이블의 한 행으로 락을 관리합니다. 각 필드의 역할은 다음과 같습니다.

name: 락의 식별자입니다. 같은 이름의 작업끼리만 경쟁하므로 PK여야 합니다. 여러 인스턴스가 동시에 같은 락을 만들려 해도 DB는 한 행만 보장합니다.
lock_until: 이 시각 전까지 다른 인스턴스는 같은 락을 얻을 수 없습니다.
locked_at: 락을 획득한 시각입니다. 락이 언제부터 유지됐는지 확인할 때 사용합니다.
locked_by: 락을 획득한 인스턴스 식별자입니다. 어떤 서버가 현재 작업을 실행 중인지 운영 환경에서 확인할 수 있습니다.

예를 들어 서버 A가 shed-lock-example-scheduler 락을 얻으면 lock_until을 미래 시각으로 갱신합니다. 서버 B는 같은 이름의 락을 시도하지만 아직 만료 전이므로 획득하지 못하고, 메서드 본문을 실행하지 않습니다.

3. Scheduler Lock을 활성화하고 LockProvider를 등록합니다

@Configuration
@EnableSchedulerLock(defaultLockAtMostFor = "1h")
public class ShedLockConfig {

    @Bean
    public LockProvider lockProvider(DataSource dataSource) {
        return new JdbcTemplateLockProvider(
            JdbcTemplateLockProvider.Configuration.builder()
                .withJdbcTemplate(new JdbcTemplate(dataSource))
                .usingDbTime()
                .build()
        );
    }
}

@EnableSchedulerLock(defaultLockAtMostFor = "1h")의 defaultLockAtMostFor는 각 @SchedulerLock에서 값을 따로 주지 않았을 때 사용할 최대 락 유지 시간입니다. 서버가 작업 중 종료되더라도 이 시간이 지나면 락이 만료되어 다른 서버가 작업을 시작할 수 있습니다.

lockAtMostFor는 락을 반드시 그 시간만큼 유지한다는 뜻이 아닙니다. 작업이 정상 종료되면 락은 바로 해제됩니다. 이 값은 서버 장애 시 락이 영구히 남지 않도록 하는 최대 만료 시간이며, 실제 작업의 최장 실행 시간보다 충분히 길어야 합니다. 작업이 끝나기 전에 시간이 만료되면 다른 서버도 락을 획득해 중복 실행될 수 있습니다.

usingDbTime()은 앱 서버 시간이 아닌 DB 시간을 기준으로 락을 판단하게 합니다. 여러 서버의 시스템 시간이 다른 경우가 있을수 있기에, DB 의 시간을 기준으로 사용합니다.

4. 중복 실행을 막을 메서드에 락 이름을 부여합니다

@Component
@RequiredArgsConstructor
public class ShedLockExampleScheduler {

    private final SchedulerLoggerProvider schedulerLoggerProvider;
    private final Environment environment;

    @Scheduled(fixedRate = 60000)
    @SchedulerLock(
        name = "shed-lock-example-scheduler",
        lockAtMostFor = "1m",
        lockAtLeastFor = "59s"
    )
    public void logLockAcquisition() {
		 // 로직
    }
}

name은 프로젝트 전체에서 고유해야 합니다. 서로 다른 스케줄러가 같은 이름을 쓰면 의도치 않게 서로의 실행을 막습니다.

lockAtMostFor = "1m"은 이 예시 작업에만 적용하는 최대 락 유지 시간입니다. 서버가 작업 중 종료되면 최대 1분 뒤 다른 서버가 락을 얻을 수 있습니다.

lockAtLeastFor = "59s"는 락을 획득한 시점부터 락을 최소로 유지할 시간입니다. 작업이 바로 끝나도 ShedLock은 lock_until을 59초 미래로 설정하여 작업이 끝나더라도 다른 스케줄러가 중복해서 스케줄러를 실행하지 않도록 막습니다.

따라서 lockAtLeastFor는 “정확히 1분마다 실행”을 보장하기보다, 같은 락 이름의 작업이 최소 59초 동안 다시 실행되지 않도록 보장합니다. 어느 인스턴스가 락을 먼저 얻을지는 실행 타이밍에 따라 달라질 수 있지만, 같은 주기에 두 인스턴스가 모두 실행되는 문제는 막을 수 있습니다.

검증

@Component
@RequiredArgsConstructor
public class ShedLockExampleScheduler {

    private final SchedulerLoggerProvider schedulerLoggerProvider;
    private final Environment environment;

    @Scheduled(fixedRate = 60000)
    @SchedulerLock(
        name = "shed-lock-example-scheduler",
        lockAtMostFor = "1m",
        lockAtLeastFor = "59s"
    )
    public void logLockAcquisition() {
        long startTime = System.currentTimeMillis();
        String serverPort = environment.getProperty("server.port");

        schedulerLoggerProvider.getLogger()
            .info("[ShedLock Example] Lock acquired. serverPort: {}, activeProfiles: {}", serverPort,
                String.join(",", environment.getActiveProfiles()));

        long endTime = System.currentTimeMillis();
        schedulerLoggerProvider.getLogger()
            .info("[ShedLock Example] Finished in {} ms", endTime - startTime);
    }
}

intelljj 에서 compound 를 활용하여 2개의 서버를 띄워 실제로 하나의 서버에서만 스케줄러가 돌아가는지 검증해보겠습니다.

결과를 보면 2개의 Application이 동시에 떳지만, 9002 번포트를 사용한 Application 에서만 스케줄러 lock 이 실행된것을 확인할 수 있습니다.

usingDbTime()을 사용하는 MySQL ShedLock은 UTC_TIMESTAMP(3)을 기준으로 락 시간을 계산합니다. 아래 조회는 DB 세션이 UTC인 상태에서 CONVERT_TZ를 사용해, 조회 결과만 KST로 변환한 것입니다.

SELECT
    name,
    CONVERT_TZ(locked_at, '+00:00', '+09:00') AS locked_at_kst,
    CONVERT_TZ(lock_until, '+00:00', '+09:00') AS lock_until_kst,
    locked_by
FROM shedlock;

조회 결과에서 lockAtLeastFor = "59s"에 따라 17:34:50에 락이 시작됐고, 59초 뒤인 17:35:49까지 lock_until이 적용된 것을 확인할 수 있습니다.

Reference

앱 본인인증에서 전용 쿠키를 따로 만든 이유

chanyoun — Mon, 29 Jun 2026 13:18:53 +0900

앱 본인인증에서 전용 쿠키를 따로 만든 이유

앱 본인인증에서 전용 쿠키를 따로 만든 이유

외부 본인인증 서비스를 앱 및 웹(WebView) 방식으로 연동하면서, 앱 방식에서만 전용 쿠키(CERT_SESSION_KEY)를 별도로 두게 된 이유와, 그 과정에서 CORS와 SameSite가 어떻게 맞물리는지 실제로 검증한 기록입니다.

현재 저희 서버는 앱, 웹 방식을 모두 지원하고 있으며, 앱 및 웹 모두 하나의 웹뷰를 통해 구현이 되어있는 상태입니다. 또한 회원은 cookie 에 존재하는 jwt 토큰을 통해 식별합니다.

한 줄 결론: 앱 방식의 콜백은 외부 도메인에서 오기 때문에 JWT(SameSite=Lax)가 실리지 않습니다. 그래서 SameSite=None으로 설정한 전용 임시 토큰 쿠키를 별도로 두게 됐습니다.

그리고 이 콜백이 실제로 서버에 도달하려면 CORS allowlist도 함께 필요합니다.

배경: 앱 방식 vs 웹 방식 본인인증

본인인증 결과(data)를 누가 저희 서버로 가져오느냐가 두 방식의 핵심 차이입니다.

웹 방식 (SPA/브라우저)

FE가 인증된 상태로 토큰 발급 API 호출 → @AuthenticationPrincipal로 memberId 식별
FE가 표준창을 띄우고 인증 결과를 FE가 직접 받음
FE가 다시 인증된 상태로 결과 처리 API 호출 → JWT로 식별

여기서 "JWT를 붙인다"는 건 헤더 토큰이 아니라 쿠키입니다. 웹 클라이언트는 로그인 시 JWT(accessToken/refreshToken)를 Set-Cookie로 받고, 이후 모든 API 호출에서 이 쿠키가 자동으로 실려갑니다. 핵심은 이 호출들이 저희 FE → 저희 API, 즉 same-site라는 점입니다. same-site 요청엔 SameSite=Lax 쿠키도 항상 실리므로 별도 처리가 필요 없습니다.

앱 방식 (WebView)

앱 방식에서는 인증 완료 후 외부 인증 도메인이 직접 저희 서버 콜백으로 POST합니다. 즉, 결과를 가져오는 주체가 저희 FE가 아닌 외부 도메인입니다.

이 콜백은 cross-site 요청이므로 SameSite=Lax로 설정된 JWT 쿠키는 실리지 않습니다. JWT로 회원을 식별하는 웹 방식과 달리, 앱 방식에서는 JWT를 사용할 수 없습니다.

따라서 임시 토큰 발급 패턴을 사용합니다. 인증 시작 시점에 임시 토큰을 발급해 SameSite=None 쿠키로 미리 심어두고, 콜백에서 그 토큰으로 Redis를 역조회해 memberId를 식별하는 방식입니다.

흐름은 다음과 같습니다.

WebView가 view 엔드포인트 호출 → 서버가 Redis에 임시토큰·memberId 매핑 저장 + CERT_SESSION_KEY 쿠키를 Set-Cookie로 내려줌
표준창에서 본인인증 진행
인증 완료 후 표준창(cert.example.com)이 returnUrl로 직접 POST
그 콜백에서 @CookieValue CERT_SESSION_KEY로 memberId 역조회

이 쿠키는 cross-site POST에도 실려올 수 있도록 의도적으로 아래와 같이 설정되어 있습니다.

ResponseCookie.from(CERT_SESSION_KEY, tempToken)
    .httpOnly(true)
    .secure(true)
    .path("/api/cert/authentication")
    .sameSite("None")   // cross-site로도 따라오게
    .build();

콜백 핸들러는 대략 이렇게 생겼습니다.

@PostMapping("/cert/authentication")
public ResponseEntity<Void> getCertResultForApp(
        @RequestParam(DATA) String data,
        @CookieValue(value = CERT_SESSION_KEY, required = false) String token) {
    certFacade.processCertResultForApp(token, data);
    return ResponseEntity.status(HttpStatus.FOUND)   // 302 redirect
        .location(...)
        .build();
}

처음엔 이렇게 추론했습니다.

"이건 표준창이 저희 returnUrl로 보내는 top-level form POST navigation이다. 브라우저 스펙상 navigation은 CORS의 응답검사 대상이 아니다(폼은 cross-origin으로 자유롭게 POST된다 — 그래서 CSRF가 존재한다). 따라서 CORS와 무관하고, 동작하는 진짜 이유는 SameSite=None 쿠키다."

이 추론의 앞부분(브라우저 레벨)은 맞지만, 결론은 틀렸습니다. 빠뜨린 게 있었습니다.

Spring CorsFilter는 브라우저 CORS와 별개의 서버측 게이트입니다.

CorsFilter는 보안 필터 체인 앞단에 걸려 있고, 요청에 Origin 헤더가 있고 그 값이 allowlist에 없으면 navigation이든 XHR이든 상관없이 컨트롤러 도달 전에 403으로 잘라버립니다. Spring은 Sec-Fetch-Mode 같은 값을 보지 않습니다. 오직 Origin 헤더 + allowlist만 확인합니다.

즉 "브라우저가 navigation을 안 막는다"와 "저희 서버 CorsFilter가 Origin을 보고 막는다"는 완전히 다른 층위의 이야기였습니다.

검증 1 (T1): 콜백 요청의 실체 관측

위 사항을 확인하기 위해 콜백 진입 시 실제 요청 헤더를 로깅했습니다.

method=POST
origin=https://cert.example.com      ← Origin 헤더가 실제로 붙어 옴
referer=https://cert.example.com/
secFetchSite=cross-site
secFetchMode=navigate                    ← XHR(cors)이 아니라 top-level navigation
contentType=application/x-www-form-urlencoded
cookiePresent=true
cookieHeader=certSessionKey=...;
responseStatus=302 (성공)

읽어낸 사실들입니다.

Origin 헤더가 붙습니다. POST form 제출은 스펙상 Origin을 포함합니다. Spring CorsFilter가 관여할 수밖에 없습니다.
navigation입니다. Sec-Fetch-Mode: navigate + Content-Type: x-www-form-urlencoded
simple request라 preflight가 없습니다. form-urlencoded POST는 preflight 대상이 아니므로 본 요청이 바로 서버에 닿습니다.
이 시점엔 cert.example.com이 allowlist에 있었기 때문에 302로 통과했습니다.

검증 2 (T2): CORS를 빼면 정말 막히는가

T1에서 "Origin 헤더가 붙는다"는 걸 확인했으므로, CorsFilter가 게이트라는 건 거의 확실했습니다. 못 박기 위해 dev allowlist에서 cert.example.com만 제거하고 동일하게 본인인증을 돌렸습니다.

요청	결과	해석
`/cert/web/authentication` (웹)	200 정상	호출 주체가 저희 FE → allowlist에 있음 → 통과
`/cert/authentication` (앱 콜백)	403 "Invalid CORS request"	호출 주체가 `cert.example.com` → allowlist에서 빠짐 → 차단

결정적 증거 두 가지입니다.

T1 로깅이 안 찍혔다 + requestBody가 비어있었습니다 → 컨트롤러 진입 자체를 못 했습니다. CorsFilter가 앞단에서 잘랐다는 직접 증거입니다.
같은 흐름에서 웹은 멀쩡히 200, 앱만 403 → 차이는 오직 호출 Origin이 allowlist에 있느냐 하나뿐입니다.

최종 정리

cross-site POST 콜백이 동작하려면 두 조건이 동시에 필요합니다. 하나라도 빠지면 실패하지만, 실패 양상이 다릅니다.

메커니즘	역할	빠지면
CORS allowlist (`cert.example.com`)	요청이 컨트롤러까지 도달	403 — 컨트롤러 진입조차 못 함
SameSite=None 쿠키 (`CERT_SESSION_KEY`)	회원 식별 쿠키가 요청에 실려옴	도달은 하나 `token=null` → 식별 실패

작동 메커니즘 요약입니다.

외부 표준창이 결과를 저희 returnUrl로 cross-site form POST(navigate) 합니다.
그 요청엔 Origin: ...cert.com 헤더가 붙습니다.
Spring CorsFilter가 Origin을 검사합니다 → allowlist에 있어야 통과(없으면 403). ← CORS 필요
통과한 요청엔 SameSite=None 쿠키만 실려옵니다(Lax 쿠키는 cross-site POST에 미전송). ← None 쿠키 필요
컨트롤러가 쿠키 토큰으로 Redis에서 memberId를 역조회해 처리합니다.

결론

웹 방식은 저희 FE가 인증 결과를 받아 API를 호출하므로 same-site 요청입니다. SameSite=Lax JWT 쿠키가 그대로 실려오기 때문에 별도 처리가 필요 없습니다.

앱 방식은 외부 인증 도메인이 콜백을 직접 POST하므로 cross-site 요청입니다. SameSite=Lax 쿠키는 cross-site POST에 실리지 않기 때문에 JWT로 회원을 식별할 수 없습니다. 그래서 인증 시작 시점에 임시 토큰을 발급해 SameSite=None 쿠키로 미리 심어두는 전용 쿠키가 필요했습니다.

여기에 더해, 그 콜백이 서버에 도달하려면 Spring CorsFilter allowlist에 외부 인증 도메인이 등록돼 있어야 합니다. 브라우저는 form navigation을 막지 않지만, 서버 CorsFilter는 Origin 헤더만 보고 막기 때문입니다.

Grafana 커스텀 대시보드 구축

chanyoun — Fri, 17 Apr 2026 16:14:39 +0900

Grafana 커스텀 대시보드 구축

Grafana 커스텀 대시보드 구축

Grafana + Prometheus + Spring Boot Actuator를 함께 사용하고 있었습니다. Grafana에서 Spring Boot를 모니터링할 때 많이 쓰는 JVM (Micrometer) 대시보드를 가져와서 쓰고 있었는데, 이 대시보드는 JVM 내부 메트릭에 집중되어 있어서 정작 궁금한 것들에 대한 답을 주지 못했습니다.

어떤 API가 느린지
5xx 에러가 어디서 발생하는지
DB 커넥션 풀은 괜찮은지

이런 질문들에 답하려면 매번 Explore에서 쿼리를 직접 날려야 했고, 문제가 발생했을 때 한눈에 파악이 안 되는 게 가장 불편한 점이었습니다.

그래서 직접 커스텀 대시보드를 만들었습니다.

전제 조건

구성 요소	상태
Grafana v11.1.0	설치 및 접속 가능
Prometheus	Docker 네트워크 내부에서 동작
Spring Boot 3.2.x	Actuator + Micrometer로 `/management/prometheus` 엔드포인트 노출
Prometheus → Spring Boot 스크래핑	설정 완료

1. 수집 중인 메트릭 확인

대시보드를 만들려면 Prometheus가 어떤 메트릭을 수집하고 있는지부터 알아야 합니다. Grafana의 Explore에서 확인할 수 있습니다. Explore에 들어가서 데이터소스를 Prometheus로 선택하고, 쿼리 입력 영역 왼쪽의 Metrics browser를 클릭합니다.

1단계 - 메트릭 선택: 수집 중인 전체 메트릭 목록이 나옵니다. 검색창에 http_server_requests를 입력하면 관련 메트릭만 남습니다. 여기서 사용할 메트릭을 하나 클릭합니다.

2단계 - 라벨 선택: 메트릭을 클릭하면, 해당 메트릭에 붙어있는 라벨만 필터링되어 표시됩니다. 예를 들어 http_server_requests_seconds_count를 클릭하면 다음 라벨들이 나타납니다.

라벨	값 수	설명
`error`	3	에러 종류
`exception`	3	예외 클래스명
`instance`	1	서버 인스턴스
`job`	1	Prometheus job 이름
`method`	6	HTTP 메서드 (GET, POST, PUT 등)
`outcome`	4	결과 (SUCCESS, CLIENT_ERROR, SERVER_ERROR 등)
`status`	9	HTTP 상태코드 (200, 400, 500 등)
`uri`	100	API 엔드포인트 경로

괄호 안 숫자는 해당 라벨의 고유 값 개수입니다. uri (100)이면 100개 엔드포인트가 기록되어 있다는 뜻입니다.

3단계 - 라벨 값 선택: 라벨을 클릭하면 실제 값을 선택할 수 있습니다. 예를 들어 status를 선택하면 200, 400, 500 등이 나타나고, 원하는 값을 골라 필터를 만들 수 있습니다.

아래 4. Resulting selector에 완성된 쿼리가 표시됩니다. Use query를 누르면 바로 결과를 볼 수 있습니다.

1.1 주요 메트릭 카테고리

Spring Boot Actuator + Micrometer가 자동으로 노출하는 메트릭 중, 대시보드에서 활용할 항목입니다.

카테고리	대표 메트릭	설명
HTTP 요청	`http_server_requests_seconds_*`	요청 수, 응답 시간, 상태 코드
JVM 메모리	`jvm_memory_used_bytes`, `jvm_memory_max_bytes`	Heap/Non-Heap 메모리 사용량
GC	`jvm_gc_pause_seconds_*`	GC 일시 정지 시간
JVM 스레드	`jvm_threads_live_threads`, `jvm_threads_daemon_threads`	스레드 수
HikariCP	`hikaricp_connections_*`	DB 커넥션 풀 상태
디스크	`disk_free_bytes`, `disk_total_bytes`	디스크 용량
프로세스	`process_cpu_usage`, `system_cpu_usage`	CPU 사용률

테이블의 _* 표기는 편의상 공통 접두사를 묶어 쓴 것입니다. 실제 Prometheus에는 개별 메트릭이 따로 존재합니다. 예를 들어 http_server_requests_seconds_*는 하나의 히스토그램 메트릭에서 자동 생성된 _count(요청 횟수), _sum(응답 시간 합계), _bucket(구간별 분포) 세 개를 의미합니다.

2. 대시보드 설계

2.1 구성 목표

대시보드를 통해 다음 질문에 답할 수 있어야 합니다.

어떤 API가 느린가? - 비즈니스 로직 최적화 대상 선정
에러가 얼마나 발생하는가? - 5xx 에러율 추적
서버 리소스는 괜찮은가? - JVM 메모리, CPU, 커넥션 풀
DB 커넥션은 부족하지 않은가? - HikariCP 상태 확인

2.2 패널 구성

대시보드를 열었을 때 위에서부터 아래로 자연스럽게 훑을 수 있도록 4개 Row로 나눴습니다.

Row 1은 지금 서비스가 괜찮은지 아닌지를 5초 안에 판단하는 요약 줄입니다. Uptime, 5xx 에러율, 평균 응답시간, Heap 사용률, DB 커넥션 사용률, 디스크 사용률 — 6개 숫자가 한 줄에 나란히 있고, 정상이면 초록, 문제면 빨간색입니다. 여기서 빨간색이 보이면 아래 Row로 내려가서 원인을 찾는 흐름입니다.

Row 2는 HTTP 요청에 대한 상세 지표입니다. 느린 엔드포인트 Top 10 테이블, 전체 RPS, 현재 처리 중인 요청 수, 5xx 에러 누적 건수, 에러가 발생한 엔드포인트 테이블, 에러 추이 그래프, 느린 API 응답시간 추이, 상태코드별/method별 요청 분포를 배치했습니다. "어떤 API가 느리고, 어디서 에러가 나는지"를 이 Row에서 전부 확인할 수 있습니다.

Row 3은 JVM 상태입니다. Heap 메모리 추이, GC 일시정지 시간, CPU 사용률, 스레드 수와 상태별 분포, 로그 이벤트 빈도를 넣었습니다. Row 1에서 Heap 사용률이 높으면 여기로 내려와서 메모리 누수인지, GC 문제인지를 확인합니다.

Row 4는 HikariCP 커넥션 풀입니다. Active/Idle/Pending/Max 상태, 커넥션 획득 시간, 사용 시간, 타임아웃 누적을 모아뒀습니다. 느린 API가 커넥션을 오래 물고 있으면 여기서 먼저 징후가 보입니다.

3. 대시보드 생성 방법

Grafana UI에서 패널을 하나씩 추가할 수도 있지만, JSON으로 전체 대시보드를 한 번에 import하는 방법이 더 편리합니다.

Dashboards > New > Import dashboard 페이지에서 3가지 방법을 제공합니다.

방법	설명
Upload dashboard JSON file	JSON 파일을 드래그 앤 드롭으로 업로드
grafana.com dashboard URL or ID	커뮤니티 대시보드 ID를 입력하여 가져오기
Import via dashboard JSON model	JSON을 직접 텍스트로 붙여넣기

커스텀 대시보드는 세 번째 방법을 사용합니다. JSON을 작성해서 텍스트 영역에 붙여넣고 Load 버튼을 누르면 됩니다.

3.1 대시보드 JSON 기본 구조

{
  "title": "{서비스명} Spring Boot Overview",
  "tags": ["spring-boot"],
  "timezone": "Asia/Seoul",
  "refresh": "30s",
  "panels": [ ]
}

3.2 패널 JSON 구조

각 패널은 아래와 같은 형식을 따릅니다.

{
  "type": "timeseries",
  "title": "Request Rate (req/s)",
  "gridPos": { "h": 8, "w": 8, "x": 0, "y": 1 },
  "datasource": { "type": "prometheus", "uid": "<DATASOURCE_UID>" },
  "targets": [
    {
      "expr": "<PromQL 쿼리>",
      "legendFormat": "{{method}}"
    }
  ],
  "fieldConfig": {
    "defaults": { "unit": "reqps" }
  }
}

type: 패널 종류. timeseries(시계열 그래프), stat(숫자 하나), table(테이블) 등
gridPos: 대시보드 내 위치와 크기. w는 너비(최대 24), h는 높이
targets.expr: 이 패널에서 사용할 PromQL 쿼리
datasource.uid: Prometheus 데이터소스의 UID

<DATASOURCE_UID>는 Grafana > Connections > Data Sources에서 Prometheus를 클릭하면 URL에서 확인할 수 있습니다.

4. 대시보드 UX 커스터마이징

패널을 다 만들고 나서 기본 설정 그대로 두니까 정상인지 이상인지 구분이 잘 안 됐습니다. 몇 가지 설정을 바꿔서 해결했습니다.

4.1 Stat 패널 색상 모드

Grafana Stat 패널의 colorMode는 두 가지가 있습니다.

"value": 배경은 어둡게, 숫자 텍스트에만 색상 적용
"background": 패널 전체 배경에 색상

colorMode를 "value"로 설정하고, thresholds에 임계값을 지정하면 값에 따라 텍스트 색상이 바뀝니다.

{
  "options": { "colorMode": "value" },
  "fieldConfig": {
    "defaults": {
      "color": { "mode": "thresholds" },
      "thresholds": {
        "mode": "absolute",
        "steps": [
          { "color": "green", "value": null },
          { "color": "red", "value": 80 }
        ]
      }
    }
  }
}

배경 전체에 색상을 채우려면 "background"로 변경합니다.

{
  "options": { "colorMode": "background" }
}

4.2 패널 Description 활용

각 패널의 (i) 아이콘에 마우스를 올리면 설명이 표시됩니다. 여기에 임계값의 의미와 문제 발생 시 확인할 항목을 적어두면, 대시보드 자체가 런북(Runbook) 역할을 합니다.

예시 (5xx 에러율 패널의 Description):

최근 5분간 전체 HTTP 요청 대비 5xx 응답 비율 (rate 기반).

빨간색 (1% 초과): 서버 에러가 유의미하게 발생 중.
- 확인: 아래 '5xx 에러 발생 엔드포인트' 테이블에서 어떤 API인지 확인
- 확인: 서버 로그에서 해당 시간대 Exception 스택트레이스
- 확인: DB 커넥션 풀 고갈, 외부 API 타임아웃 여부
- 확인: 최근 배포 이후 발생했는지 (롤백 필요 여부)

4.3 테이블 패널 노이즈 제거

느린 엔드포인트, 5xx 에러 발생 엔드포인트 테이블은 다음과 같이 조정했습니다.

기본 셀 색상을 transparent로 설정하여 배경과 동일하게 만들고, 빨간색/노란색 행만 눈에 띄게 했습니다.
5xx 에러 테이블에서 Value가 0인 행을 제거하여, 에러가 실제로 발생한 엔드포인트만 표시합니다.

# 변경 전: 0건인 엔드포인트도 모두 표시
sum(increase(http_server_requests_seconds_count{status=~"5.."}[1h])) by (uri, method, status)

# 변경 후: 에러가 1건 이상인 것만 표시
sum(increase(http_server_requests_seconds_count{status=~"5.."}[1h])) by (uri, method, status) > 0

4.4 rate와 increase를 함께 배치

대시보드에는 에러 관련 패널이 두 개 있습니다.

5xx 에러율 (Row 1): rate 기반. 최근 5분간 초당 에러 비율을 계산합니다.
5xx 에러 (Row 2): increase 기반. 최근 1시간 동안 에러가 총 몇 건 발생했는지를 누적합니다.

이 두 패널을 함께 배치하는 이유가 있습니다. 5xx 에러율이 0%인데 5xx 에러가 30건인 상황이 실제로 발생합니다. 30분 전에 에러가 집중 발생했지만 지금은 멈춘 상태라면, rate 기반 지표는 0이 됩니다. 반면 increase 기반 누적 지표는 1시간 동안의 총량을 보여줍니다.

rate는 "지금 에러가 나고 있는가?", increase는 "최근에 에러가 있었는가?"를 보는 것입니다. 둘 다 있어야 상황 파악이 됩니다.

완성된 대시보드

Row 1을 훑으면 지금 서비스가 괜찮은지 5초 안에 알 수 있고, 빨간색이 보이면 아래 Row로 내려가서 어떤 API가 느린지, 어디서 에러가 나는지, 커넥션 풀은 괜찮은지를 바로 확인할 수 있습니다. 기존 JVM (Micrometer) 대시보드에서는 매번 Explore를 열어야 했던 질문들에 이제 대시보드 하나로 답할 수 있게 됐습니다.

전체 대시보드 JSON은 첨부된 dashboard.json 파일을 Grafana Import로 가져오면 동일하게 구성할 수 있습니다.

다음 글에서는 Grafana Alerting을 활용해서 임계값 초과 시 Slack으로 자동 알림을 보내는 방법을 다룹니다.

dashboard.json

63.4 kB

Blue-Green 배포 시 Graceful Shutdown 적용기

chanyoun — Mon, 6 Apr 2026 14:49:21 +0900

Blue-Green 배포 시 Graceful Shutdown 적용기-refactor-v1

Blue-Green 배포 시 기존 컨테이너를 즉시 내리면 안 되는 이유 — Graceful Shutdown 적용기

배포 구조

EC2 한 대에 Docker Compose로 Nginx + Spring Boot 앱을 올려서 사용하고 있습니다. 배포는 Blue-Green 방식이고, 흐름은 아래와 같습니다.

Blue 컨테이너가 트래픽을 받고 있는 상태에서
Green 컨테이너를 새로 띄우고
Nginx upstream을 Green으로 전환하고
Blue를 내립니다

┌─────────────────────────────────────────┐
│                  EC2                    │
│                                         │
│  ┌───────┐     ┌──────┐    ┌──────┐     │
│  │ Nginx │────▶│ Blue │ or │Green │     │
│  └───────┘     └──────┘    └──────┘     │
│           (Docker Compose)              │
└─────────────────────────────────────────┘

GitHub Actions에서 이미지를 빌드해서 Docker Hub에 올리고, EC2에 SSH로 접속해서 deploy.sh를 실행하는 구조입니다.

문제: Blue를 즉시 내리면 요청이 유실됩니다

배포할 때 Nginx를 Green으로 전환하자마자 Blue를 docker-compose down으로 즉시 종료하고 있었습니다. 평소에는 별 문제가 없었는데, Blue에서 처리 시간이 좀 걸리는 요청이 진행 중일 때 배포가 되면 문제가 생겼습니다.

구체적으로는 @Async로 비동기 처리를 처리한 뒤 트랜잭션이 커밋되기 전에 컨테이너가 죽어버리는 상황이었습니다. 비동기 로직 자체는 실행됐는데, 정작 DB에는 반영이 안 되는 불일치가 발생했습니다.

기대하는 동작은 단순합니다. Nginx 전환 이후 새 요청은 Green으로 가되, Blue에서 이미 처리 중인 요청은 끝까지 완료된 다음에 컨테이너가 내려가야 합니다.

해결 방향: Graceful Shutdown

결국 문제는 Blue 컨테이너가 "지금 처리 중인 요청이 있는지"를 신경 쓰지 않고 바로 꺼진다는 것입니다. 그러면 컨테이너를 종료할 때 "처리 중인 요청이 있으면 기다렸다가 꺼지게" 만들면 됩니다. 이게 Graceful Shutdown입니다.

Spring Boot는 2.3부터 server.shutdown=graceful 설정을 제공합니다. SIGTERM을 받으면 새 요청은 거부하고, 이미 처리 중인 요청은 완료될 때까지 대기한 뒤 종료합니다.

그리고 Docker의 docker stop 명령은 컨테이너에 SIGTERM을 보낸 뒤 일정 시간 기다려주는 구조입니다. 이 두 가지를 조합하면 배포 스크립트에 별도 sleep을 넣지 않고도, Blue가 진행 중인 요청을 마무리한 뒤 알아서 종료되도록 만들 수 있습니다.

정리하면 이런 흐름입니다:

Nginx 전환 — 새 요청은 Green으로 라우팅
docker stop -t로 Blue에 SIGTERM 전송 — Spring Boot가 진행 중인 요청을 마저 처리
요청 완료 후 Blue 자동 종료 — 처리가 끝나면 바로 꺼지고, 최대 대기 시간이 지나면 강제 종료

`docker stop -t`의 동작 방식

docker stop -t이 구체적으로 어떻게 동작하는지 살펴보겠습니다.

docker stop -t 150 app-blue
         │
         ▼
   1) SIGTERM 전송
         │
         ▼
   2) Spring Boot가 SIGTERM을 받으면
      └─ server.shutdown=graceful 설정이 있을 때:
         - 새 요청 수신을 거부 (서버 소켓을 닫음)
         - 이미 처리 중인 요청은 계속 처리
         │
         ▼
   3) 처리가 다 끝나면 → 바로 종료
      150초가 지나도 안 끝나면 → SIGKILL로 강제 종료

여기서 중요한 건 -t 150이 "150초 동안 sleep 한다"가 아니라 "최대 150초까지 기다린다"는 점입니다. 처리가 3초면 3초 만에, 30초면 30초 만에 컨테이너가 내려갑니다. 배포 스크립트에서 sleep 60 같은 걸 넣을 필요가 없습니다.

Nginx reload 후 기존 요청은 어떻게 되나?

nginx -s reload를 하면 새로운 worker를 띄우고, 기존 worker는 처리 중인 커넥션을 다 끝낸 다음에 종료됩니다. Blue로 이미 프록시된 요청은 TCP 커넥션이 유지되는 한 응답이 클라이언트까지 전달됩니다.

[클라이언트] ←─ TCP 유지 ─→ [Nginx old worker] ←─ 커넥션 유지 ─→ [Blue]
                              │ reload 이후에도 이 파이프라인 유지
                              │ 응답 완료 후 old worker 종료

[새 클라이언트] ───────────→ [Nginx new worker] ──→ [Green]

단, Blue 컨테이너가 먼저 종료되면 old worker가 upstream 연결을 잃으면서 502를 반환합니다. 그래서 반드시 Nginx 전환 → Blue graceful stop 순서를 지켜야 합니다.

적용한 설정

Spring Boot — `application.yml`

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 60s  # SIGTERM 후 최대 60초간 기존 HTTP 요청 처리 대기
  task:
    execution:
      shutdown:
        await-termination: true
        await-termination-period: 60s  # @Async 작업 완료 대기
    scheduling:
      shutdown:
        await-termination: true
        await-termination-period: 60s  # @Scheduled 작업 완료 대기

server.shutdown=graceful만 넣으면 HTTP 요청만 기다려줍니다. @Async로 돌고 있는 비동기 작업이나 @Scheduled 스케줄러는 SIGTERM과 동시에 스레드풀이 바로 꺼져버립니다. 조회수 동기화 같은 스케줄러도 돌고 있어서 spring.task 쪽 설정도 같이 추가했습니다.

Docker Compose — `stop_grace_period`

services:
  app-blue:
    image: app:blue
    stop_grace_period: 150s  # SIGTERM → 150초 대기 → SIGKILL

  app-green:
    image: app:green
    stop_grace_period: 150s

stop_grace_period는 Spring Boot의 전체 shutdown 시간보다 넉넉하게 잡아야 합니다.

Spring Boot의 shutdown은 순차적으로 진행됩니다:

SIGTERM
  │
  ▼
1) Tomcat graceful shutdown (timeout-per-shutdown-phase: 60s)
   - 처리 중인 HTTP 요청 완료 대기
  │
  ▼
2) Spring Context 종료 → Bean destruction
   - TaskExecutor 종료 (await-termination-period: 60s)
   - TaskScheduler 종료 (await-termination-period: 60s)
  │
  ▼
3) JPA EntityManager, HikariPool 종료

최악의 경우 60s(HTTP 대기) + 60s(Task 정리) = 120s가 필요합니다. stop_grace_period가 이보다 짧으면 Spring Boot가 아직 정리 중인데 Docker가 SIGKILL을 보내서 graceful shutdown이 의미가 없어집니다. 여유를 두고 150s로 설정했습니다.

배포 스크립트 — `deploy.sh`

Blue → Green 전환 부분만 발췌하면 이런 흐름입니다.

#!/bin/bash

IS_GREEN=$(sudo docker ps | grep green)

if [ -z "$IS_GREEN" ]; then
    echo "### BLUE => GREEN ###"

    echo "1. get green image"
    sudo docker compose -f /home/ubuntu/docker-compose.yml pull dev-green

    echo "2. green container up"
    sudo docker compose -f /home/ubuntu/docker-compose.yml up -d dev-green

    while [ 1 = 1 ]; do
        echo "3. green health check..."
        sleep 5
        REQUEST=$(curl -s http://127.0.0.1:8082/health)
        if [ "$REQUEST" = "Service is up" ]; then
            echo "health check success"
            break
        fi
    done;

    echo "4. reload nginx"
    sudo cp ./nginx/constant/service-container-green.inc ./nginx/conf.d/service-container.inc
    sudo docker exec nginx nginx -s reload

    echo "5. blue container down (Background Graceful Shutdown)"
    nohup bash -c 'sudo docker compose -f /home/ubuntu/docker-compose.yml stop dev-blue && sudo docker compose -f /home/ubuntu/docker-compose.yml rm -f dev-blue' > /dev/null 2>&1 &
    echo "Deployment completed. Blue container is shutting down in the background."
fi

몇 가지 포인트:

nohup으로 백그라운드 프로세스 보호: GitHub Actions에서 SSH로 deploy.sh를 실행하는 구조이기 때문에, 스크립트가 끝나면 SSH 세션이 종료됩니다. 이때 백그라운드 프로세스에 SIGHUP이 날아가면서 docker compose stop이 중간에 끊길 수 있습니다. nohup을 붙이면 SSH 세션이 끝나도 프로세스가 유지됩니다.

배포 스크립트의 책임은 Green 시작 → 헬스체크 → Nginx 전환까지입니다. 이 시점에서 새 요청은 이미 Green으로만 가고 있으니, Blue 종료를 블로킹하면서 기다릴 이유가 없습니다. 백그라운드로 넘기면 워크플로우는 바로 끝나고, Blue는 진행 중인 요청을 마친 뒤 알아서 내려갑니다.

시간 흐름

시간 ──────────────────────────────────────────────────────────────▶

Green 시작     헬스체크 OK       Nginx 전환       워크플로우 종료
   │               │              │               │
   ▼               ▼              ▼               ▼
[Green 부팅중] [Green Ready] [새 요청→Green]      [배포 끝]
                              │
                              │  (백그라운드)
                              ▼
                         [Blue SIGTERM]
                         [진행 중 요청 처리 완료]
                         [Blue 종료]

검증

실제로 동작하는지 확인하기 위해 30초짜리 느린 API를 하나 만들었습니다.

@GetMapping("/api/health/slow")
public String checkHealthSlow() throws InterruptedException {
    Thread.sleep(30000);
    return "Slow response completed";
}

Blue가 떠있는 상태에서 이 API를 호출하고, 응답이 오기 전에 배포를 실행합니다.

# 1. Blue에 30초짜리 요청을 보냄
curl https://<SERVER>/api/health/slow &

# 2. 배포 실행 (Green 시작 → 헬스체크 → Nginx 전환 → Blue SIGTERM)
./deploy.sh

이 요청은 Nginx를 경유하기 때문에, Nginx reload 이후에도 old worker가 Blue와의 커넥션을 유지한 채 응답을 전달해주는지까지 함께 검증됩니다.

Blue 컨테이너 로그를 보면 SIGTERM을 받은 시점에 아래 로그가 먼저 뜹니다.

INFO  --- [tomcat-shutdown] --- [o.s.b.w.e.tomcat.GracefulShutdown]: Commencing graceful shutdown. Waiting for active requests to complete

Tomcat이 처리 중인 요청이 있다는 걸 감지하고, 새 요청은 거부하면서 기존 요청이 끝나기를 대기하는 상태입니다. 30초짜리 요청이 완료되면 아래 로그가 뜨면서 컨테이너가 종료됩니다.

INFO  --- [tomcat-shutdown] --- [o.s.b.w.e.tomcat.GracefulShutdown]: Graceful shutdown complete
INFO  --- [SpringApplicationShutdownHook] --- [o.s.o.j.LocalContainerEntityManagerFactoryBean]: Closing JPA EntityManagerFactory for persistence unit 'default'
INFO  --- [SpringApplicationShutdownHook] --- [com.zaxxer.hikari.HikariDataSource]: HikariPool-1 - Shutdown initiated...
INFO  --- [SpringApplicationShutdownHook] --- [com.zaxxer.hikari.HikariDataSource]: HikariPool-1 - Shutdown completed.

Graceful shutdown complete 이후에 JPA EntityManager → HikariPool 순서로 리소스가 정리되는 걸 확인할 수 있습니다. curl 응답도 200 OK로 정상 수신됩니다.

반대로, 처리 중인 요청이 없는 상태에서 SIGTERM을 받으면 Commencing graceful shutdown 로그 없이 바로 종료됩니다. 대기할 요청이 없으니 즉시 꺼지는 것이 정상입니다.

Reference

Spring Boot CI/CD 빌드 시간 단축하기 - Gradle 최적화 전략

chanyoun — Mon, 9 Feb 2026 14:30:10 +0900

CI-CD 빌드 시간 단축

Spring Boot CI/CD 빌드 시간 단축하기 - Gradle 최적화 전략

Spring Boot 프로젝트의 CI/CD 파이프라인에서 빌드와 테스트 단계가 과도하게 오래 걸리는 문제를 해결한 경험을 공유합니다.

특히 RestDocs, Swagger 문서 생성을 포함한 복잡한 빌드 프로세스에서 6~7분 걸리던 CI/CD 시간을 절반 이하로 단축할 수 있었습니다.

1. 문제상황

CI/CD 파이프라인에서 다음과 같은 문제들이 발생했습니다.

GitHub Actions에서 빌드 완료까지 6~7분 이상 소요됩니다.
특히 test 단계와 build 단계에서 대부분의 시간이 소비됩니다.
코드 변경이 없어도 매번 전체 빌드를 새로 실행합니다.
Docker 이미지 빌드도 매번 처음부터 다시 시작됩니다.

2. 원인

2.1 과도한 태스크 의존성

build.gradle 파일을 분석한 결과, build 태스크가 11개의 의존 태스크를 순차적으로 실행하고 있었습니다.

tasks.named("build") {
    dependsOn "ensureDocsDir", "cleanDocs", "test",
              "asciidoctorMember", "asciidoctorAdmin", "asciidoctorDirector",
              "generateExceptionDocs", "openapi3", "generateSwaggerUI",
              "copyDocs", "bootJar", "patchSwaggerUI"
}

이 중 일부 태스크는 병렬로 실행 가능한데도 순차적으로 실행되고 있었습니다.

2.2 불필요한 clean 작업

CI/CD 환경에서는 매번 새로운 환경에서 빌드가 실행되는데, ./gradlew clean build 명령어로 인해 이전 빌드 결과를 삭제하는 불필요한 작업이 수행되고 있었습니다.

# 기존 설정
- name: Build with Gradle
  run: ./gradlew clean build

2.3 Gradle 빌드 캐시 미사용

Gradle은 빌드 캐시 기능을 제공하지만, 활성화되지 않아 의존성 다운로드와 컴파일을 매번 반복하고 있었습니다.

2.4 Docker 레이어 캐싱 미사용

Docker 이미지를 빌드할 때도 레이어 캐싱을 사용하지 않아, 변경되지 않은 레이어까지 매번 다시 빌드하고 있었습니다.

3. 원인 검증

최적화 전략을 세우기 위해 먼저 로컬 환경에서 빌드 프로세스를 분석했습니다.

3.1 빌드 태스크 분석

./gradlew build --dry-run

./gradlew build --dry-run: 실제로 빌드를 실행하지 않고, 어떤 태스크들이 어떤 순서로 실행될지만 보여줍니다.

위 명령어로 태스크 실행 순서를 확인한 결과, 다음과 같이 순차 실행되는 것을 확인했습니다.

:compileJava SKIPPED
:processResources SKIPPED
:classes SKIPPED
:jar SKIPPED
:ensureDocsDir SKIPPED
:cleanDocs SKIPPED
:compileTestJava SKIPPED
:processTestResources SKIPPED
:testClasses SKIPPED
:test SKIPPED
:asciidoctorAdmin SKIPPED
:asciidoctorDirector SKIPPED
:asciidoctorMember SKIPPED
:generateExceptionMarkdown SKIPPED
:generateExceptionDocs SKIPPED
:check SKIPPED
:openapi3 SKIPPED
:generateSwaggerUISample SKIPPED
:generateSwaggerUI SKIPPED
:patchSwaggerUI SKIPPED
:copyDocs SKIPPED
:resolveMainClassName SKIPPED
:bootJar SKIPPED
:assemble SKIPPED
:build SKIPPED

asciidoctorMember, asciidoctorAdmin, asciidoctorDirector 세 태스크는 서로 독립적이므로 병렬 실행이 가능합니다.

3.2 빌드 시간 프로파일링

./gradlew build --profile

./gradlew build --profile: 빌드를 실행하면서 각 태스크가 얼마나 시간이 걸렸는지 상세한 리포트를 생성합니다.

빌드가 완료되면 be/build/reports/profile/profile-<timestamp>.html 파일이 생성됩니다.

# 리포트 열기
open be/build/reports/profile/profile-*.html

프로파일링 결과:

test: 전체 시간의 68.2%
asciidoctor* 태스크들: 전체 시간의 9.9%
의존성 다운로드: 전체 시간의 1%

따라서 의존성 다운로드 부분은 로컬에서는 큰 문제가 아닌 것을 확인했습니다. 먼저 asciidoctor 태스크들을 병렬 실행하여 해당 부분을 최적화합니다.

4. 해결방법

4.1 Gradle 빌드 캐시 활성화

로컬에서 먼저 테스트

최적화 옵션을 로컬에서 먼저 테스트합니다.

기존 빌드 시간은 대략 1분 2.83초 정도 걸렸으니, 캐시 및 병렬 실행 시 얼마나 줄어드는지 확인합니다.

# 최적화된 빌드 시간 측정
time ./gradlew build --build-cache --parallel

--build-cache 옵션으로 빌드 캐시를 활성화하고, --parallel 옵션으로 독립적인 태스크들을 병렬 실행합니다.

병렬 실행 시 대략 6~7초 정도 줄어든 것을 확인할 수 있습니다.

GitHub Actions에 적용

로컬 테스트에서 효과가 확인되었으니, GitHub Actions workflow 파일에 Gradle 캐싱을 추가합니다.

- name: Setup Gradle
  uses: gradle/gradle-build-action@v2
  with:
    cache-read-only: false  # dev 브랜치에서도 캐시 쓰기 허용

- name: Build with Gradle
  run: ./gradlew build --build-cache --parallel

cache-read-only: false: 기본적으로 main/master 브랜치가 아닌 경우 캐시를 읽기만 가능합니다. cache-read-only: false를 설정하면 현재 브랜치에서도 캐시를 저장할 수 있어, 다음 빌드 시 활용할 수 있습니다.

4.2 clean 작업 제거

CI 환경에서는 매번 새로운 환경이므로 clean이 불필요합니다.

# 변경 전
- name: Build with Gradle
  run: ./gradlew clean build

# 변경 후
- name: Build with Gradle
  run: ./gradlew build --build-cache --parallel

4.3 Docker 레이어 캐싱 활성화

GitHub Actions의 캐시 기능을 활용하여 Docker 빌드를 최적화합니다.

# 4. docker hub로 build & push
- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v2

- name: Login to Docker Hub
  uses: docker/login-action@v2
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_PASSWORD }}

- name: Docker build and push
  uses: docker/build-push-action@v4
  with:
    context: ${{ env.BE_WORKING_DIR }}      # ./be
    file: ${{ env.BE_WORKING_DIR }}/Dockerfile  # ./be/Dockerfile
    push: true
    tags: ${{ secrets.DOCKER_USERNAME }}/motd-dev-be:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

cache-from과 cache-to 옵션으로 GitHub Actions 캐시를 활용합니다.

5. 검증

5.1 로컬 빌드 시간 비교

# 최적화 전
time ./gradlew clean build
# 결과: 약 1분 5초

# 최적화 후 (첫 실행 - 캐시 생성)
time ./gradlew build --build-cache --parallel
# 결과: 약 59초

# 최적화 후 (두 번째 실행 - 캐시 히트)
time ./gradlew build --build-cache --parallel
# 결과: 약 57초

5.2 CI/CD 파이프라인 실행 시간

로컬 테스트에서 효과가 확인되어, GitHub Actions에도 동일한 최적화를 적용했습니다.

최적화 전: 6분 10초
최적화 후: 2분 31초

위 summary에서 확인할 수 있듯이, Gradle Build Action이 자동으로 캐시를 관리하고 있습니다.

캐시 동작 분석

복원 단계 (Entries Restored)

6개 항목, 511 MB를 18.8초에 복원
이전 빌드에서 저장한 다음 항목들을 재사용합니다:
- 다운로드한 의존성 (dependencies)
- 컴파일된 클래스 파일
- Gradle wrapper
- Build cache (이전 빌드 결과)

저장 단계 (Entries Saved)

4개 항목, 324 MB를 10.9초에 저장
변경된 부분만 업데이트하여 다음 빌드를 위해 저장합니다
Cache cleanup 효과: 511 MB → 324 MB (37% 감소)
- 오래된 버전의 라이브러리 제거
- 더 이상 사용하지 않는 build cache 정리

5.3 로컬 vs CI/CD 개선 효과 차이 분석

로컬에서는 보통 ./gradlew clean build만 수행하고(배포 Job처럼 Docker build/push를 하지 않음),

~/.gradle/caches가 유지되기 때문에 의존성 다운로드 시간은 대부분 이미 상수에 가깝습니다.

또한 clean은 프로젝트 빌드 산출물만 지우고, Gradle 의존성 캐시까지 매번 비우진 않기 때문에 --build-cache의 체감이 크지 않을 수 있습니다.

그래서 로컬에서의 개선은 주로 --parallel로 독립 태스크를 병렬 실행한 만큼(약 6~7초)만 나타났습니다.

반면 CI/CD 환경은 매 실행이 거의 “새 환경”에서 시작하므로, 캐시가 없으면 의존성/Gradle 관련 파일을 다시 받거나 빌드 결과물을 매번 새로 만들게 됩니다.

여기서 Gradle 캐시(의존성/빌드 캐시) 복원 + Docker 레이어 캐시(cache-from/to: gha)를 적용하면 의존성 준비 시간과 Docker 빌드 시간이 함께 줄어들어, 전체 실행 시간이 6분 10초 → 2분 31초(약 59%)로 크게 감소할 수 있습니다.

DBeaver에서 MySQL Dump 시 소켓 연결 오류 해결

chanyoun — Thu, 29 Jan 2026 17:07:46 +0900

DBeaver에서 MySQL Dump 시 소켓 연결 오류 해결

DBeaver에서 MySQL Dump 시 소켓 연결 오류 해결

DBeaver에서 SSH 터널링으로 Docker 위에서 동작하는 MySQL에 접속해 쿼리는 정상 작동하는데, Dump(Data Transfer/Export)만 실행하면 Can't connect to local MySQL server through socket 오류가 발생하는 경우의 해결 방법을 정리합니다.

원인

DBeaver가 AWS EC2에 있는 MySQL에 접속할 때, 직접 접속(3306 포트 개방)이 막혀 있다면 SSH 터널링을 사용합니다.

이때 데이터의 흐름은 다음과 같습니다.

DBeaver가 SSH 접속을 통해 EC2와 연결을 맺습니다.
DBeaver는 로컬 Mac의 특정 포트(예: 37492)를 리스닝(Listening) 상태로 엽니다.
사용자가 쿼리를 날리면, DBeaver는 이 요청을 localhost:37492로 보냅니다.
이 신호는 SSH 터널을 타고 EC2로 넘어갑니다.
EC2 내부에서 이 신호가 해독되어 localhost:3306(MySQL)으로 전달됩니다.

즉, 로컬 Mac의 37492 포트는 원격지 MySQL로 통하는 입구 역할을 합니다.

Dump 할 때만 오류가 나는 이유

평소 쿼리 실행(SELECT 등)은 DBeaver를 통해 이 터널을 잘 이용합니다. 하지만 Dump는 다릅니다.

Dump를 수행할 때 DBeaver는 로컬 Mac에 설치된 외부 프로그램인 mysqldump 바이너리 파일을 실행시킵니다. 이때 문제가 발생합니다.

문제의 상황

DBeaver가 mysqldump에게 명령을 내릴 때 대략 이렇게 명령합니다.

"localhost의 37492 포트에 DB 있으니까 거기로 접속해서 데이터 가져와!"

그런데 MySQL 계열의 클라이언트 프로그램(mysql, mysqldump)은 다음과 같이 작동합니다.

호스트가 IP(127.0.0.1)로 주어지면 TCP/IP(네트워크) 연결을 시도합니다.
호스트가 명칭(localhost)으로 주어지면 Unix Socket 파일 연결을 시도합니다.

오류의 원인: DBeaver가 터널링을 통해 열어둔 37492는 TCP 포트입니다. 하지만 mysqldump는 localhost라는 말을 듣고 로컬에 설치된 MySQL이라고 착각하여 /tmp/mysql.sock 같은 소켓 파일을 찾다가 연결을 못 하고 실패합니다.

MySQL 클라이언트 연결 방식 확인

실제로 localhost와 127.0.0.1의 동작 차이를 확인할 수 있습니다.

localhost 사용 시 (Unix Socket 시도):

$ mysql -h localhost -P 37492 -u test
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)

포트를 명시했음에도 socket 파일을 찾으려고 시도합니다.

127.0.0.1 사용 시 (TCP/IP 시도):

$ mysql -h 127.0.0.1 -P 37492 -u test
ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1:37492' (61)

TCP/IP 연결을 시도하며, 에러 메시지에 포트 번호(37492)가 포함됩니다.

해결 절차

DBeaver의 Dump 설정에서 호스트 설정을 명확하게 TCP로 강제해주면 해결됩니다.

DBeaver에서 해당 DB 커넥션 우클릭 → Edit Connection을 선택합니다.

기존 localhost였던 Server Host 설정을 127.0.0.1로 변경합니다.

설정 변경 후 Dump를 다시 실행하면 성공적으로 완료되는 것을 확인할 수 있습니다.

bluegreen-배포-환경에서-prometheus-메트릭이-끊겨-보이던-이유와-해결-방법

chanyoun — Fri, 2 Jan 2026 13:14:54 +0900

Blue:Green 배포 환경에서 Prometheus 메트릭이 끊겨 보이던 이유와 해결 방법

Blue/Green 배포 환경에서 Prometheus 메트릭이 끊겨 보이던 이유와 해결 방법

Blue/Green 배포 환경에서 Prometheus의 target을 인스턴스 기준으로 설정한 상태에서 모니터링을 하다 보니, Grafana 그래프가 배포 시점마다 끊겨 보이는 문제가 발생했습니다.

현재 Spring Boot + Actuator를 사용해 메트릭을 노출하고, Prometheus와 Grafana를 통해 이를 모니터링하고 있습니다.

서비스는 Blue/Green 배포 방식으로 운영 중이며, 배포 시점에 따라 Spring Boot 인스턴스가 blue 또는 green으로 전환되는 구조입니다.

문제는 Prometheus가 특정 시점에는 dev-blue 인스턴스를 바라보다가, 배포 이후에는 dev-green 인스턴스를 바라보도록 설정이 변경된다는 점이었습니다.

Prometheus 입장에서는 blue와 green을 서로 다른 서버로 인식하게 되고, 이로 인해 Grafana에서는 동일한 서비스임에도 불구하고 메트릭이 연속되지 않는 것처럼 보이게 됩니다.

이를 해결하기 위해 Prometheus가 개별 인스턴스(blue/green)를 직접 바라보는 방식이 아니라,현재 서비스 중인 엔드포인트 하나만을 바라보도록 구조를 변경하기로 했습니다.

현재 서비스 앞단에는 ELB(Application Load Balancer)가 존재하며, ELB가 blue 또는 green 중 실제로 트래픽을 처리하고 있는 인스턴스로 요청을 라우팅하고 있는 상태입니다.

따라서 Prometheus가 개별 인스턴스가 아닌, ELB가 바라보고 있는 서비스 엔드포인트를 기준으로 메트릭을 수집하도록 변경하면, Blue/Green 전환으로 인해 모니터링 그래프가 끊겨 보이는 문제를 해결할 수 있다고 판단했습니다.

아래 순서로 변경을 진행해 보겠습니다.

Spring Boot Actuator의 Prometheus endpoint 경로 변경
변경된 endpoint가 ELB를 통해 blue/green 인스턴스로 라우팅되도록 리스너 규칙 추가
Prometheus 설정에서 scrape target을 인스턴스가 아닌 ELB DNS로 변경

1. Spring Boot Actuator의 Prometheus endpoint 경로 변경

기존 actuator.yml

management:
  endpoints:
    web:
      base-path: /management
      exposure:
        include: prometheus

기존에는 /management 경로를 통해 Actuator 메트릭을 수집하고 있었습니다.

이번 변경에서는 Actuator의 base path를 /management에서 /internal/metrics으로 변경하여, Prometheus 전용 메트릭 엔드포인트를 별도로 분리해보겠습니다.

변경후 actuator.yml

management:
  endpoints:
    web:
      base-path: /internal/metrics
      exposure:
        include: prometheus

이제 /internal/metrics/prometheus 경로를 통해 Prometheus가 메트릭을 수집할 수 있도록 변경되었습니다.

2. 변경된 endpoint가 ELB를 통해 blue/green 인스턴스로 라우팅되도록 리스너 규칙 추가

현재 ELB 의 리스너 규칙은 아래와 같습니다.

기존 BE 트래픽은 /api/*, /ws* 경로를 기준으로 be-rule을 통해 blue/green 인스턴스로 라우팅되고 있습니다.

이번에 추가한 /internal/metrics/prometheus 엔드포인트 역시 동일한 BE 애플리케이션에서 제공되기 때문에, 우선은 별도의 리스너 규칙을 추가하지 않고 기존 be-rule에 /internal* 경로를 함께 포함하도록 구성해보겠습니다.

사진처럼 구성하게 되면 Prometheus가 /internal/metrics/prometheus로 요청하더라도, 기존 BE 트래픽과 동일하게 현재 서비스 중인 blue 또는 green 인스턴스로 자동 라우팅됩니다.

다만 /internal/* 경로는 비즈니스 API와 성격이 다른 운영/관측용 엔드포인트이기 때문에, 운영 환경에서는 별도의 리스너 규칙으로 분리하거나, IP 제한 등의 추가적인 보안 설정을 적용하는 것이 더 적절할 수 있습니다.

3. Prometheus 설정에서 target을 인스턴스가 아닌 ELB DNS로 변경

마지막으로 Prometheus 설정에서 scrape target을 개별 인스턴스가 아닌, ELB의 DNS를 바라보도록 변경합니다.

기존 prometheus.yml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    metrics_path: "/management/prometheus"
    static_configs:
      - targets: ["dev-green:8082"]

변경후 prometheus.yml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    scheme: https
    metrics_path: "/internal/metrics/prometheus"
    static_configs:
      - targets: ["로드 밸런서의 DNS 이름"]

이 변경을 통해 Prometheus는 더 이상 dev-blue 또는 dev-green 인스턴스를 직접 바라보지 않고, 항상 동일한 ELB DNS를 기준으로 메트릭을 수집하게 됩니다.

따라서 Blue/Green 배포로 인해 인스턴스가 교체되더라도, Prometheus 설정을 다시 수정할 필요가 없게 됩니다.

4. 테스트

Prometheus가 정상적으로 연결되어 메트릭을 수집하고 있다면, Grafana 대시보드에서 아래와 같이 메트릭이 정상적으로 표시되는 것을 확인할 수 있습니다.

보다 빠르게 확인하고 싶다면, Prometheus의 Targets 페이지를 통해 메트릭 수집 상태를 직접 확인할 수 있습니다.

http://<prometheus-host>:9090/targets

이 페이지에서 대상(target)의 상태가 UP으로 표시된다면, Prometheus가 해당 엔드포인트로부터 정상적으로 메트릭을 수집하고 있다는 의미입니다.

4.1 TLS 인증서 오류 발생

저의 경우, 위 Targets 페이지에서 아래와 같은 오류를 확인할 수 있었습니다.

해당 오류는 Prometheus가 ELB의 DNS 주소로 HTTPS 요청을 시도하면서 발생했습니다.

ELB에는 제 서비스 도메인에 대한 TLS 인증서만 적용되어 있었고, ELB 고유의 DNS 주소에 대한 인증서는 존재하지 않았기 때문입니다.

즉,

도메인(example.com) → ELB → 정상
ELB DNS(xxx.elb.amazonaws.com) → 인증서 불일치 → 오류 발생

이라는 상황이었습니다.

해결 방법

이를 해결하기 위해 Prometheus 설정에서 target을 ELB의 DNS 주소가 아닌, TLS 인증서가 적용된 서비스 도메인으로 변경했습니다.

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    scheme: https
    metrics_path: "/internal/metrics/prometheus"
    static_configs:
      - targets: ["도메인명 ex) example.com"]

이렇게 설정하면 TLS 인증서 검증 문제 없이 정상적으로 메트릭을 수집할 수 있으며, Blue/Green 배포 환경에서도 Prometheus 설정을 변경할 필요가 없어집니다.

Grafana 및 prometheus 활용 #2

chanyoun — Wed, 31 Dec 2025 20:47:25 +0900

Grafana 및 prometheus 활용 #2

Grafana 및 prometheus 활용 #2

본 글에서는 Grafana와 Prometheus를 연결하는 방법과, 실제 모니터링에 바로 사용할 수 있는 대시보드 템플릿 적용 방법에 대해 다뤄보겠습니다.

1. Prometheus 데이터 소스 추가

Grafana에서 Prometheus 메트릭을 조회하려면, 먼저 Prometheus를 Data Source로 등록해야 합니다.

Grafana에 접속한 후 아래 메뉴로 이동합니다.

Connections → Data sources

1.1 Prometheus 컨테이너 이름 확인

현재 docker-compose를 통해 실행 중인 컨테이너는 다음과 같습니다.

docker-compose를 사용하는 경우, 같은 네트워크에 속한 컨테이너들은 서비스 이름을 hostname으로 사용할 수 있습니다.

따라서 Prometheus 컨테이너의 이름이 prometheus라면, Grafana에서는 해당 이름을 그대로 사용해 연결할 수 있습니다.

1.2 Data Source 설정

Data Source 추가 화면에서 Prometheus를 선택한 뒤, Connection(URL)을 다음과 같이 설정합니다.

나머지 옵션은 기본값을 사용하거나, 각자의 환경에 맞게 조정해도 무방합니다.

설정이 끝나면 Save & test 버튼을 클릭합니다.

아래와 같이 정상적으로 연결되었다는 메시지가 표시되면, Grafana와 Prometheus 간의 연동이 완료된 상태입니다.

2. 대시보드 설정

Prometheus 데이터 소스를 연결했다면, 이제 해당 데이터를 시각화할 Grafana Dashboard를 선택해야 합니다.

Grafana는 공식적으로 다양한 대시보드를 제공하고 있으며, 아래 사이트에서 원하는 대시보드를 검색하고 사용할 수 있습니다.

https://grafana.com/grafana/dashboards/

2.1 사용할 대시보드 선택

본 글에서는 JVM 및 Micrometer 기반 메트릭을 확인할 수 있는다음 대시보드를 사용하여 모니터링을 구성해보겠습니다.

https://grafana.com/grafana/dashboards/4701-jvm-micrometer/

해당 페이지에 접속한 후, Copy ID to Clipboard 버튼을 눌러 대시보드 ID를 복사합니다.

2.2 Grafana에서 대시보드 Import

복사한 대시보드 ID를 사용하여 Grafana로 돌아온후 아래 경로로 이동합니다.

Dashboards → Create dashboard → Import a dashboard

Import 화면에서 복사한 Dashboard ID를 입력합니다.

2.3 Data Source 선택 및 Import

대시보드 정보를 불러오면, 사용할 Data Source를 선택하는 화면이 표시됩니다.

여기서 앞 단계에서 생성한 Prometheus Data Source를 선택한 후 Import 버튼을 클릭합니다.

Import가 완료되면, 아래와 같이 JVM 및 애플리케이션 메트릭을 확인할 수 있는 대시보드가 생성됩니다.

나만의 코딩기록

DB Lock

DB Lock

Shared Lock (S Lock)

Exclusive Lock (X Lock)

Intention Lock (IS Lock, IX Lock)

Record Lock

Gap Lock

Gap Lock이 걸리는 기준

Next-Key Lock

기본은 Next-Key Lock이고, 나머지는 축소된 형태입니다

Insert Intention Lock

참조

Clustering, Replication, Sharding

Clustering

Active & Active

Active & Stand-By

Replication

Sharding

Partitioning

결론

다중 인스턴스 환경에 ShedLock 적용하기

상황

ShedLock 이란?

설정

1. 의존성을 추가합니다

2. 락 테이블을 생성합니다

3. Scheduler Lock을 활성화하고 LockProvider를 등록합니다

4. 중복 실행을 막을 메서드에 락 이름을 부여합니다

검증

Reference

앱 본인인증에서 전용 쿠키를 따로 만든 이유

앱 본인인증에서 전용 쿠키를 따로 만든 이유

배경: 앱 방식 vs 웹 방식 본인인증

웹 방식 (SPA/브라우저)

앱 방식 (WebView)

처음의 오판: "navigation은 CORS 대상이 아니다"

검증 1 (T1): 콜백 요청의 실체 관측

검증 2 (T2): CORS를 빼면 정말 막히는가

최종 정리

결론

Grafana 커스텀 대시보드 구축

Grafana 커스텀 대시보드 구축

전제 조건

1. 수집 중인 메트릭 확인

1.1 주요 메트릭 카테고리

2. 대시보드 설계

2.1 구성 목표

2.2 패널 구성

3. 대시보드 생성 방법

3.1 대시보드 JSON 기본 구조

3.2 패널 JSON 구조

4. 대시보드 UX 커스터마이징

4.1 Stat 패널 색상 모드

4.2 패널 Description 활용

4.3 테이블 패널 노이즈 제거

4.4 rate와 increase를 함께 배치

완성된 대시보드

Blue-Green 배포 시 Graceful Shutdown 적용기

Blue-Green 배포 시 기존 컨테이너를 즉시 내리면 안 되는 이유 — Graceful Shutdown 적용기

배포 구조

문제: Blue를 즉시 내리면 요청이 유실됩니다

해결 방향: Graceful Shutdown

docker stop -t의 동작 방식

Nginx reload 후 기존 요청은 어떻게 되나?

적용한 설정

Spring Boot — application.yml

Docker Compose — stop_grace_period

배포 스크립트 — deploy.sh

시간 흐름

검증

Reference

Spring Boot CI/CD 빌드 시간 단축하기 - Gradle 최적화 전략

Spring Boot CI/CD 빌드 시간 단축하기 - Gradle 최적화 전략

1. 문제상황

2. 원인

2.1 과도한 태스크 의존성

2.2 불필요한 clean 작업

2.3 Gradle 빌드 캐시 미사용

2.4 Docker 레이어 캐싱 미사용

`docker stop -t`의 동작 방식

Spring Boot — `application.yml`

Docker Compose — `stop_grace_period`

배포 스크립트 — `deploy.sh`