Skip to content

About

Kafka 기반 알림 시스템을 단계별로 만드는 Java/Spring 학습 프로젝트

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Notification Lab

Kafka 기반 알림 시스템을 단계별로 만드는 Java/Spring 학습 프로젝트. 현재 v0.3(S3)는 요청과 Outbox를 MySQL에 함께 저장하고 Kafka Worker가 Mock을 호출하는 비동기 API이다. S4에서 선택적 Idempotency-Key 접수 중복 방지, 발송 작업/시도 이력, 일시 실패의 유한 지연 재시도, Retry 토픽/DLQ, 선택 재발행을 추가했다. 실제 푸시나 단말 도착을 의미하지 않는다.

아키텍처

현재 구현 중 역할 분리·Redis quota·HTTP Mock 옵션을 켠 로컬 실험 구성이다. 기본 실행은 단일 REALTIME 역할과 인메모리 Mock을 사용한다.

Notification Lab 아키텍처: API와 명시적 Batch가 MySQL에 저장하고 Outbox Relay, Kafka, Worker를 거쳐 Mock을 호출한다. Redis는 호출 예산을 제한하고 결과와 재시도·DLQ Outbox는 MySQL에 저장한다.
  • 실시간 API는 알림·발송 작업·Outbox를 한 트랜잭션으로 저장하고 접수 응답을 반환한다.
  • 캠페인 API는 정의와 시작 의도를 저장한다. 별도 Batch 명령이 대상별 알림과 checkpoint를 저장하며, API 시작 요청만으로 자동 실행하지 않는다.
  • Relay는 DB 트랜잭션 밖에서 Kafka ACK를 확인하고, Worker는 외부 호출 후 DB 결과를 저장한 다음 offset을 커밋한다.

구성요소·코드 근거·보장 범위 · 확대 이미지 · 어두운 테마

실행

Java 21, Docker(Compose 포함), 인터넷 연결이 필요하다. Gradle은 Wrapper가 설치한다. AWS/FCM 키는 필요하지 않다. 비밀번호는 로컬 실험용 값을 쓴다.

test -f .env || cp .env.example .env
# .env의 MYSQL_PASSWORD / MYSQL_ROOT_PASSWORD를 각각 채운 뒤 실행
docker compose up -d --wait
set -a
. ./.env
set +a
./gradlew bootRun

Compose는 MySQL 8.4.8(127.0.0.1:13316), Kafka 4.0.2(127.0.0.1:19092)를 시작한다. Kafka는 KRaft 단일 브로커다. 앱이 notification.requested.v1, notification.requested.v1.retry, notification.requested.v1.dlq를 각각 파티션 3개, 복제본 1개로 생성한다. 앱은 127.0.0.1:8080에서 실행한다. 인증과 TLS가 없는 로컬 실험이므로 외부에 공개하지 않는다.

Compose는 .env를 자동으로 읽지만 Spring Boot는 읽지 않으므로 위 환경변수 로딩이 필요하다. bash/zsh 외 환경에서는 같은 값을 환경변수로 설정한다. Windows에서는 gradlew.bat을 사용한다. MYSQL_PORT, KAFKA_PORT를 바꾸면 Compose와 앱에 함께 반영된다. 별도 로컬 주소는 DB_URL, KAFKA_BOOTSTRAP_SERVERS로 설정한다.

MySQL/Kafka는 각각 named volume을 사용한다. docker compose down은 데이터를 보존하며 docker compose down -v는 실험 데이터를 삭제한다(Redis 프로필 사용 시 해당 volume도 포함). 의도한 초기화에만 사용한다. 서로 다른 시점의 DB/토픽/consumer offset을 임의로 섞으면 재처리 또는 추적 불일치가 생긴다.

API와 상태

curl -i http://127.0.0.1:8080/notifications \
  -H 'Content-Type: application/json' \
  -d '{"recipientId":"user-100","title":"테스트 알림","body":"알림 처리 확인"}'

curl http://127.0.0.1:8080/notifications/응답에서_받은_UUID
curl http://127.0.0.1:8080/notifications/응답에서_받은_UUID/delivery
curl http://127.0.0.1:8080/actuator/health
curl http://127.0.0.1:8080/actuator/prometheus

POST의 202 Accepted와 Location은 요청/발송 작업/Outbox가 DB에 커밋되었다는 뜻이다. 응답 스냅샷은 QUEUED이며 실제 진행 상황은 GET으로 조회한다. 기동 후 브로커 장애 중에도 DB 접수는 가능하다. 브로커 없이 처음 기동해 토픽이 생성되지 않았다면 복구 후 앱을 재시작한다.

기동 후 Kafka 컨테이너를 실제 중단하고 복구하는 S5 실험에서 장애 중 5건의 202 접수와 앱 재시작 없는 후속 처리를 확인했다. 단, Outbox 발행 상한을 소진한 FAILED는 복구 후에도 자동 처리하지 않는다. Kafka lag가 0이어도 이 미발행 요청은 남을 수 있다.

상태/응답 의미
QUEUED 접수 완료, Worker 처리 대기
PROCESSING Worker가 선점하고 처리 중
WAITING_RETRY 일시 실패 후 다음 시도 예약. completedAt은 null
PROVIDER_ACCEPTED Mock 공급자 수락. 단말 도착 아님
RETRYABLE_FAILURE 일시 실패로 종료. 새 비동기 작업은 전체 시도 상한 소진, 과거 결과/비교 프로필은 한 번의 결과
PERMANENT_FAILURE 영구 공급자 실패
INTERNAL_FAILURE 예상 밖 공급자 오류 또는 복구 시도 상한 소진
400 / 404 잘못된 요청 또는 UUID / 알림 없음
503 DB 접근 또는 트랜잭션 오류 (memory에서는 용량 초과 포함)

응답 유실이나 DB 오류 후 같은 알림의 중복 접수를 막으려면 Idempotency-Key를 보낸다. 처음 접수는 202, 같은 키·같은 필드 재요청은 기존 알림의 현재 상태와 같은 Location을 200으로 반환한다. 같은 키에 recipientId/title/body 중 하나라도 다르거나 접수 역할이 다르면 409이다. 200은 처리 성공을 뜻하지 않는다. 키가 없으면 기존처럼 요청마다 새로운 ID가 생긴다.

curl -i http://127.0.0.1:8080/notifications \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-request-001' \
  -d '{"recipientId":"user-100","title":"테스트 알림","body":"알림 처리 확인"}'

키는 대소문자 구분 [A-Za-z0-9._:-] 1~128자이며 복수 헤더/잘못된 값은 400이다. 키는 알림 행과 함께 보관하고 만료하지 않는다. 현재 범위는 이 DB의 알림 접수 API 전체다. sync/memory 비교 프로필은 이 헤더를 지원하지 않아 전달 시 400을 반환한다. 상세 계약과 트랜잭션은 S4 멱등성 문서를 참고한다.

처리 흐름과 복구

  1. API: notification(QUEUED), delivery_task, Outbox(PENDING)를 한 DB 트랜잭션으로 저장한다.
  2. Relay: 짧은 트랜잭션으로 한 이벤트를 선점하고 커밋한다. DB 트랜잭션 밖에서 Kafka publish future 성공을 기다린 뒤 PUBLISHED를 저장한다.
  3. Worker: 레코드를 하나씩 처리한다. 짧은 DB 선점 후 트랜잭션 밖에서 Mock을 호출하고, 최종 결과 또는 이력/재시도 예약/Outbox를 함께 커밋한 후 offset을 커밋한다.

Relay는 30초 lease/token으로 오래된 소유자의 상태 덮어쓰기를 막는다. 실패하면 1~60초 지수 backoff, 최대 10회 시도 후 FAILED로 보관한다. FAILED는 자동 재발행하지 않으며 Outbox 지표/DB로 조사한다. 이때 알림은 QUEUED 또는 WAITING_RETRY일 수 있다. GET은 알림 결과이고 Relay의 상세 상태는 아니다.

ACK 직후 Relay 종료 실험에서는 Kafka에 기록했지만 Outbox는 PROCESSING인 상태에서 Relay JVM을 강제 종료했다. 실제 lease 만료 후 같은 이벤트가 재발행되어 Kafka 레코드는 2개가 되었고, 살아 있는 Worker는 이미 완료된 DB 결과를 확인해 공급자 호출을 1회로 유지했다.

DB 완료 후 Worker 종료 실험에서는 offset 커밋 직전 Worker JVM을 강제 종료했다. 같은 group의 새 Worker가 기존 Kafka 레코드 1개를 재소비했고, DB 완료 상태를 확인해 추가 공급자 호출 없이 offset을 커밋했다.

재시작·리밸런스 실험에서는 처리 중 Worker 합류와 1 → 2 → 1 → 2대 전환을 검증했다. Relay 중단 중 접수된 요청도 기존 ID로 복구했으며, 단계마다 접수/호출/레코드 수와 파티션별 offset을 대조했다.

SIGTERM 종료 시 HTTP 신규 접수를 먼저 중지한 뒤 현재 Kafka 레코드의 완료를 기다린다. Relay도 종료 신호 이후 다음 선점 루프를 진행하지 않는다. 유예는 phase마다 10초이며 전체 프로세스의 10초 제한은 아니다. 종료 실험과 복구 절차에서 정상 완료와 유예 초과를 각각 검증했다.

Worker DB/이벤트 오류는 컨슈머를 멈춘다. 오류를 해결하고 진행 중 lease(30초)가 만료된 후 앱을 재시작한다. 그 전에는 미완료 offset을 넘기지 않는다. 완료된 DB 결과를 다시 읽으면 공급자를 호출하지 않고 offset만 처리한다. 공급자 성공 직후 DB 저장 전 종료되면 재호출이 가능하다. 외부 발송 exactly-once는 보장하지 않는다. UNKNOWN/상한 소진은 미발송 확정이 아니다. 불확실한 결과의 확인·복구 정책을 따른다.

발송 작업은 요청당 가상 대상 하나이며 taskId와 시도 이력을 /notifications/{id}/delivery로 조회한다. 만료된 시도는 다음 복구에서 UNKNOWN으로 기록한다. 선점은 최초 포함 기본 3회(설정 범위 110)이며, 마지막 선점의 lease까지 만료되면 추가 호출 없이 INTERNAL_FAILURE / ATTEMPTS_EXHAUSTED로 보관한다. 공급자 실패 확정을 뜻하지 않는다. 일반 일시 실패도 같은 횟수 상한 안에서 자동 재시도한다. 기본 대기는 5001000ms, 1000~2000ms이며 지수 backoff와 equal jitter를 적용한다. 예약 시각은 DB에 저장하고 delivery 조회의 nextAttemptAt으로 확인한다. 재시도는 due 이후 별도 Retry 토픽으로 보내고, 최종 실패는 결과와 함께 DLQ Outbox를 저장한다. 원본 offset은 이 영속 인계 후 처리하며, Relay는 Kafka ACK를 확인한 후 PUBLISHED로 바꾼다. DLQ는 자동 소비/재발송하지 않는다. 선택한 PUBLISHED DLQ는 사유와 중복 가능성 확인을 입력해 POST /dead-letters/{eventId}/redrive로 재접수할 수 있다. 최초 202/동일 요청 200이며 원본을 보존하고 새 작업을 만든다. 같은 DLQ는 한 번, 원본 기준 계보 전체는 최대 3회 재발행한다. 선택 재발행 API와 토픽·DLQ 정책을 참고한다. 작업/복구 정책과 재시도 정책을 참고한다. 기존 앱을 모두 종료한 뒤 새 버전을 실행한다. V9 DB를 사용하며 실시간/캠페인 역할을 모르는 이전 앱·Relay와 혼합 실행하지 않는다. 기존 행은 REALTIME으로 보존한다.

기본 Mock 지연은 100ms(허용 0~5000ms), SUCCESS다. 앱 재시작으로 설정한다.

./gradlew bootRun --args='--app.mock.outcome=TRANSIENT_FAILURE'
./gradlew bootRun --args='--app.mock.outcome=PERMANENT_FAILURE'
./gradlew bootRun --args='--app.mock.delay-ms=1000'

DB 풀은 최대 8개, Relay 기본값은 한 번에 한 publish/한 주기 최대 50건, Worker 기본 소비 스레드 1/처리 1/poll 1건이다. 단일 브로커 고가용성, 다중 인스턴스의 모든 장애 조합, 운영 성능을 입증한 구성이 아니다.

HTTP Mock과 Worker 연동 (S6)

독립 HTTP Mock을 DB/Kafka 없이 127.0.0.1:18081에서 실행할 수 있다. 기본 Worker는 기존 내부 Mock을 사용하며 app.provider.mode=HTTP로 실제 HTTP 호출을 선택한다. HTTP 모드도 알림 앱에는 기존 MySQL/Kafka와 DB 환경변수가 필요하다.

# Mock 실행 예시 중 하나를 선택
./gradlew mockServer
./gradlew mockServer --args='--mock.http.mode=SERVER_ERROR'
./gradlew mockServer --args='--mock.http.response-delay-ms=2000'
# 별도 터미널에서 알림 앱 실행
./gradlew bootRun --args='--app.provider.mode=HTTP'

POST /pushes로 수락/429/500/영구 실패와 클라이언트 timeout을 재현하고 /mock/stats에서 집계를 확인한다. 요청 한도와 동시 처리 상한이 있으며, timeout 뒤에도 수락 기록이 남을 수 있다. Mock 서버 설정과 HTTP 연동·timeout·연결 풀을 참고한다. HTTP 클라이언트 기본값은 연결 2개/추가 호출 4개, 풀 대기 200ms/연결 500ms/응답 1000ms/전체 deadline 3000ms다. 자동 HTTP 재시도는 끄며 기존 DB 재시도 최대 3회를 사용한다. timeout 후 중복 수락 가능성과 429 Retry-After 미반영 한계가 있다.

Worker 처리/대기 상한 (S6)

app.worker.consumers(기본 1, 최대 3)과 max-active(기본 1)로 소비 스레드와 실제 처리 수를 구분한다. 처리 자리가 없으면 DB 선점 전 FIFO에서 기다린다. queue-capacity 기본 2(0~3), queue-wait-ms 기본 1000(최대 5000)이다. 대기열 포화/timeout은 해당 offset을 넘기지 않고 소비를 멈추며 원인 해결 후 명시적으로 재시작한다.

./gradlew bootRun --args='--app.provider.mode=HTTP --app.worker.consumers=3 --app.worker.max-active=2 --app.worker.queue-capacity=1 --app.worker.queue-wait-ms=5000'

파티션별 순차 처리와 DB 완료 후 RECORD offset 커밋을 유지한다. 처리/대기 상한은 프로세스별이다. 문제·대안·선택 이유·종료 정책·검증 결과를 참고한다.

Redis 전역 요청 한도와 Worker 연동 (S6)

여러 클라이언트가 같은 Redis 키에서 토큰을 공유하는 Lua 제한기를 추가했다. 기본 정책은 초당 10개 보충 / 최대 버스트 10개이며, Redis 서버 시간으로 보충·확인·차감을 원자적으로 수행한다. ALLOWED, LIMITED(재확인 대기 시간), UNAVAILABLE(오류/포화/설정 충돌/예산 부재)을 구분하며 오류 시 허용하지 않는다. 최초 설치도 명시적인 빈 예산 초기화가 필요하다. 키 삭제·TTL·예산 유실에서 자동 버스트를 만들지 않는다.

app.rate-limit.client-enabled=true이면 비동기 Worker의 최초 발송과 재시도 모두 같은 quota를 사용한다. 완료된 메시지 재소비는 quota 없이 처리한다. 발송이 필요하면 DB 트랜잭션을 끝낸 뒤 허가를 기다리고, 허가 후 새 트랜잭션에서 상태를 재확인하여 시도 횟수/lease를 만든다. memory/sync 비교 프로필은 적용 대상이 아니다.

docker compose --profile redis up -d --wait redis
# 최초 설치, 모든 참여 앱을 실행하기 전 한 번만 초기화
docker compose exec -T redis redis-cli -e --eval /dev/stdin \
  notification-lab:provider:mock:quota , 10 10 \
  < src/main/resources/redis/initialize-provider-quota.lua
./gradlew bootRun --args='--app.provider.mode=HTTP --app.rate-limit.client-enabled=true'

기존 MySQL/Kafka와 HTTP Mock 실행도 필요하다. 기본값 false는 Redis 없이 기존 기준선을 실행한다. 127.0.0.1:${REDIS_PORT:-16379}, Redis 7.4.11, AOF/전용 volume/noeviction을 사용한다. 모든 참여 앱에 같은 Redis/키/rate/burst를 설정한다. 초기화는 토큰 0개에서 시작하고 기존 키는 덮어쓰지 않는다. 기존 version=1 예산은 새 앱과 호환되지 않는다. 전체 발송 중지·확인·대기 후 v2 전환/복구 절차를 따른다. 단순 연결 장애에서 신뢰할 수 있는 기존 v2 예산은 유지한다. 정상 형식의 오래된 snapshot 복원은 자동 감지하지 못하므로 자동 failover를 지원한다고 해석하지 않는다.

app.rate-limit.wait-timeout-ms 기본 2000(1~5000)이다. 두 모드 모두 quota 대기 중 DB 시도/lease를 만들지 않는다. 기본 app.rate-limit.pause-enabled=true에서는 정상 한도 부족(LIMITED)에 소비 pause → poll 유지 → 자동 resume를 사용한다. DB 선점과 Worker 처리 자리 없이 기다리고, 재개 후 같은 레코드의 상태와 허가를 다시 확인한다. wait-timeout-ms는 pause-enabled=false인 이전 동기 대기 비교 모드에만 적용된다. Redis 오류는 두 모드 모두 소비 중지/명시적 재시작이며, 자동 재개는 정상 한도 부족에만 적용한다. 설계·종료/리밸런스·poll/heartbeat 검증을 참고한다.

문제·알고리즘 비교·정책·실제 Redis 검증·한계를 참고한다. 연동 경계·대안·복구·실제 통합 검증을 함께 참고한다.

공급자 Circuit Breaker (S6)

HTTP 공급자의 연속 장애 시 DB 선점과 Redis quota 소비 전에 발송을 보류한다. 기본은 꺼져 있으며 비동기 HTTP 모드에서 --app.circuit-breaker.enabled=true로 선택한다. 임계값 failure-threshold=3, 차단 시간 open-ms=5000이 기본이다.

CLOSED → OPEN → HALF_OPEN으로 전환하며, HALF_OPEN에서는 앱당 한 요청으로 복구를 확인한다. 5xx/통신 오류는 장애로 세고 429/개별 요청 오류/로컬 자원 부족은 제외한다. 차단 중에는 기존 pause/poll/resume를 사용해 시도 횟수와 미완료 offset을 보존한다. 상태는 프로세스별이며 재시작하면 CLOSED로 초기화한다. Redis quota와 독립적으로 켤 수 있다. 문제·대안·선택 이유·상태 전이·실제 인프라 검증·한계를 참고한다.

실시간·캠페인 분리 (S6)

같은 JAR를 REALTIME/CAMPAIGN 역할의 별도 프로세스로 실행한다. 각 역할은 요청/Retry/DLQ 토픽, consumer group, Relay 선점 경로와 Worker/HTTP/DB 연결 풀을 따로 사용한다. 공급자 Redis 키는 하나를 공유하며 기본 전체 10/s·burst 10을 실시간 8/8, 캠페인 2/2로 예약한다. 사용하지 않는 다른 역할의 몫을 빌리지 않는다. 이 정책은 처리 순서 추월이나 지연 SLO를 보장하지 않는다.

기본 app.traffic.split-enabled=false는 기존 단일 REALTIME/v2 예산을 유지한다. 분리는 두 앱 모두 --app.traffic.split-enabled=true --app.rate-limit.client-enabled=true로 켜고, 역할만 --app.traffic.lane=REALTIME 또는 CAMPAIGN으로 구분한다. 기본 pause 모드를 유지해야 한다. 분리 모드는 v3 빈 예산을 명시적으로 초기화해야 하며 기존 v2와 혼합할 수 없다. 선택 이유·역할별 실행·v2/v3 전환·실제 검증·한계를 먼저 확인한다.

개별 캠페인 알림은 역할별 /notifications로 가상 대상 한 명씩 접수한다. API 본문으로 역할을 바꾸지 않는다. 재시도/DLQ/선택 재발행은 원래 역할을 보존하며 다른 역할의 redrive는 409다. S7에서 캠페인 정의와 시작 요청 API를 추가했다. 명시적 Batch 명령으로 대상별 Outbox 인계도 지원한다. MySQL/Kafka/Redis 서버와 호스트 자원은 공유한다.

캠페인 생성·시작·조회와 가상 대상자 (S7)

CAMPAIGN 역할의 비동기 앱에서 POST /campaigns로 정의를 저장하고, POST /campaigns/{id}/start로 시작 의도를 기록하며 GET /campaigns/{id}로 조회한다. 생성에는 Idempotency-Key가 필수다. 같은 키/같은 정의는 기존 캠페인을 반환하고 다른 정의는 409다. 최초 시작은 202, 중복 시작은 200이며 DB에 최초 요청 시각을 한 번 저장한다.

캠페인 상태는 DRAFT → START_REQUESTED이며 시작 의도를 나타낸다. 시작 요청 저장만으로 Batch를 자동 실행하지 않는다. 가상 대상 수 1~100만을 정의에 기록한다. GET /campaigns/{id}/audience?after=0&limit=100으로 고정 가상 대상자를 최대 1,000명씩 읽고, 응답의 nextAfter로 이어 읽는다. 집합 고정·keyset·재시작 계약을 참고한다. 가상 집합을 규칙으로 계산한다. 시작 요청 후 ./gradlew campaignBatch --args='캠페인_UUID'로 해당 캠페인의 대상별 알림/발송 작업/Outbox와 checkpoint를 chunk 단위로 함께 저장한다. FAILED 실행은 같은 명령으로 마지막 커밋에서 재시작하며, 완료 재요청은 기존 결과를 반환한다. 강제 종료된 새 버전 실행도 MySQL 세션 소유권을 확인한 뒤 재개한다. 복구 조건과 한계를 참고한다. Batch COMPLETED는 DB 인계 완료이며 발송 완료가 아니다. 별도 CAMPAIGN Relay/Worker가 기존 발송 경로를 수행한다. 실행·checkpoint·ACK 경계·복구 한계를 참고한다. 명령은 Relay/Worker를 끄고 종료하지만, 다른 앱에서 이미 실행 중이면 커밋된 Outbox가 처리될 수 있다. 요청 예제·트랜잭션·동시성·실패 정책·검증을 참고한다.

테스트와 빌드

테스트가 격리된 MySQL/Kafka/Redis 컨테이너를 생성·삭제하므로 .env와 Compose 사전 실행은 필요 없다. Docker가 없으면 실패하며 자동 스킵하지 않는다. Batch JVM 정지/재개 테스트는 macOS/Linux의 POSIX 신호를 사용한다.

./gradlew test
./gradlew build
# 별도 1만 건 HTTP → MySQL → Kafka → Worker 정합성 실험
./gradlew reconciliationTest
# 별도 캠페인 DB 인계 부하 (발송하지 않음)
./gradlew campaignLoadTest -PcampaignTargets=100000
# HTTP 발송 사전 실험 (기본 1만 건 + 실시간 동시 요청)
./gradlew campaignDeliveryPilot
# 별도 10만 건 HTTP 발송 실험 (최대 task 90분)
./gradlew campaignDeliveryLoad
# 별도 100만 건 장시간 실험 (최대 task 12시간)
# 별도 실행하기로 결정한 경우에만 다음 명령 사용
# ./gradlew campaignDeliveryMillion
# 실행 JAR
java -jar build/libs/notification-lab-0.3.0-SNAPSHOT.jar

build는 일반 테스트와 알림 앱/HTTP Mock의 실행 JAR 생성을 포함한다. 1만 건 실험은 별도 명령이며 성능 벤치마크가 아니다. 캠페인 대량 DB 인계도 별도 task로 실행한다. 10만/100만 건의 저장·전체 매핑·완료 재요청을 검증했다. 최종 100만 건 DB 인계는 약 42분 25초였다. HTTP 발송 사전 실험은 1만 건을 약 115초에 처리하고 실시간 564건도 함께 대조했다. 10만 건 HTTP 발송은 캠페인100000+실시간5342건을 전수 대조했다. 발송 구간은 약22분27초/초당74.239건이었다. 혼합 실시간p95는918.136ms로 단독553.657ms보다 증가했다. 100만 건 실험 도구는 준비했고 2026-11-02 실제 실험을 시작했다. 첫 실행은 실험용 실시간 접수 클라이언트의5초 응답 대기 초과로 실패했다. 마지막 캠페인 진행 관측은 약38.4만 건이며 최종 전수 대조는 미완료다. 실패 원본과 진단 보강을 기록했고 원인 진단 후 재실행을 결정한다. 운영 성능/실시간 SLO 보장과 구분한다. timeout 후 작은 진단에서는1만 건 HTTP와1만/10만 행 SQL을 확인했고 같은 timeout은 미재현이다. 별도 ./gradlew outboxQueryProbe로 DB 실행 계획을 관측한다. 발송 성공을 검증하는 task는 아니다. ./gradlew outboxStatisticsProbe는 격리 테이블의 오래된 통계를 고정하고 ANALYZE TABLE 전후 계획·실행 행 수를 비교한다. 통계 갱신 후 실시간 스캔 감소를 확인했지만 이전100만 건 timeout의 원인은 아직 미확정이다. 교차 역할 잠금 재현과 수정에서는 역할별 인덱스 명시와 claim 전용 READ COMMITTED를 적용했다. ./gradlew outboxLockProbe로 기본 자동 통계·잠금·대기 대조군을 확인한다. 기존 진단 task는 현재 선점 SQL을 캡처한다. 수정 후10만 건 재검증도 캠페인100000+실시간7269건을 전수 대조했다(발송약30분41초/54.333건·초). 이번 혼합 APIp95는203.917ms/최대1904.024ms였다. 정합성은 통과했지만 이전보다 처리량은 낮았고100만 건 재실행은 미실행이다. DB 인계 측정 범위·설정·실패와 재실행 결과를 참고한다. Relay 구간 계측과 완료 저장 묶음 비교도 진행했다. 1만 건 각2회에서 단건109.349131.447초/최대10건93.949100.122초였고 HTTP42,160건을 전수 대조했다. 기본값은1이며 app.async.relay.publish-batch-size=10은 선택 옵션이다. 재발행 가능 범위가 늘어나는 비용이 있다. 실시간 p95 개선과10만/100만 건의 같은 속도는 보장하지 않는다. 후속10만 건 비교와 잠금 수정에서 구 OR구현은 처리량이 늘었지만 실시간 tail 지연도 커졌다. 별도 SQL 진단의 PRIMARY 전체 스캔/역할 간 차단을 수정해 현재는 최대10개의 기본키 단건 UPDATE를 한 번 커밋한다. 수정판557b2cf도10만 건1170.631초/85.424건·초, HTTP104639건의 전수 대조를 통과했다. 첫 단건 기준선 재사용 대비 처리량29.24% 증가였지만 혼합 APIp95는297.106→364.875ms로 악화했다. 기본값1과 실시간 설정을 유지하며 캠페인10건은 선택 옵션이다.100만 건 재실행은 아직 하지 않았다.

로컬 Relay1/2개 사전 비교는 같은 Worker3/Hikari4/캠페인200/s에서 1만 건을1→2→2→1 순서로 처리했다. 네 실행의 HTTP41711건 전수 대조를 통과했지만, 처리량 범위는1개120.646131.381/s, 2개98.426137.346/s로 일관된 개선을 확인하지 못했다. ./gradlew relayScalingPilot -PcampaignRelays=1 또는2로 재현한다(완료 저장10건 고정). 테스트 전용 같은 JVM의 독립 루프이며 기본 앱 설정이나 여러 서버 배포 기능을 변경하지 않는다. 이 결과에 이어 공유 DB 연결 취득/명령/commit과offset 저장 비용을 나눠 확인했다.

JDBC와offset 저장 비용 진단은 같은1만 건을1→2→2→1로 반복해 HTTP41717건을 전수 대조했다. 이번 설정에서 Worker는 알림당 JDBC 실행16회/DB 커밋3회, Kafka commitSync1회를 수행했고 offset 평균은5.770~6.008ms였다. 관찰 전용 ./gradlew deliveryTimingPilot -PcampaignRelays=1 또는2로 재현한다(1000..10000건). SQL 본문/인수를 저장하지 않으며 운영 코드/격리 수준/기본 RECORD ack는 유지한다. 여러 서버와100만 건 성능을 증명한 결과는 아니다.

완료 offset 묶음 비교는 같은 Relay2/Worker3에서 RECORD와COUNT_TIME(10개/100ms)을 각각2회 비교했다. HTTP41910건 전수 대조와 동기 커밋10000→2163/2019회 감소를 확인했고 처리량은89.67698.933→115.079123.383/s였다. ./gradlew offsetCommitPilot -PoffsetMode=COUNT_TIME으로 테스트에서만 선택한다. 기본 앱과 실시간 정책은 RECORD를 유지한다. 시간 기준은 엄격한100ms 보장이 아니며 마지막 offset 반영/재소비 범위를 함께 기록했다.100만 건 확대는 미실행이다.

후속 HTTP/커밋 오류 경계와10만 건 비교는 두 모드의 성공·500·429·400·timeout과 실제 커밋 RPC 앞뒤의 합성 오류 복구를 검증했다. 같은740d2ef에서각1회/HTTP209563건 전수 대조와 커밋100000→23891회 감소, 처리량77.180→92.263/s를 관측했다. 실시간 접수p95가97.694→202.728ms로 높게 관측돼 기본 RECORD를 유지한다. 조건별1회·공유 호스트 결과이며 원인을 단정하지 않는다. ./gradlew offsetCommitLoad -PoffsetMode=RECORD 또는COUNT_TIME은 정확히10만 건만 허용하는 별도 비교 task다. 기본 회귀/앱 실행에 포함하지 않고100만 건을 이 task로 실행하지 않는다.

실시간 접수 코드 흐름과 구간 진단은 기본 API의한 연결/SQL4회/commit1회를 따라가는 학습 문서다. 테스트 전용 ./gradlew apiAdmissionPilot -PoffsetMode=RECORD 또는COUNT_TIME으로1000..10000건만 측정한다. 요청별 연결/SQL/commit/서버/클라이언트 시간을 대응했고1만 건 각1회/HTTP21034건을 대조했다. 10만 건의p95 수준은 미재현이며 기본 정책을 유지한다. DB 내부 대기의 확정 원인은 아직 검증하지 않았다.

DB 대기와 호출자 대기 제어 실험은 ./gradlew apiWaitProbe로 실행하는 SQL 전용 검증이다. 실제 Outbox 잠금 대기와 native commit 이후 합성 호출자 지연을 DB 가시성/대기 관계/CPU·wall로 구분했다. HTTP/Kafka 발송 부하는 없고 기존 자연 발생 tail의 원인을 해결한 결과가 아니다. 운영 설정과 기본 정책을 유지한다.

같은 접수 연결의DB 관찰 대응은 apiSessionProbe로 세션 대응을 검증하고 apiDbObservationPilot -PdbObservation=OFF 또는ON으로정확히1천 건을 비교한다. API연결에진단SQL을추가하지 않는다. 호출이끝난표본은버리고 전체512조회/요청당8표본으로제한한다. 자연ON은87요청중4개만관측돼과거지연의원인은미확정이다.

긴 호출 우선 관찰은 같은 두 task에 -PdbMinCallMillis=20을 더해 20ms 이상 진행 중인 execute/commit만 조회하는 실험이다. 생략 또는0은 기존 즉시 조회다. 긴 호출 수도 별도 집계해 표본을 놓친 구간을 숨기지 않는다. 운영 설정은 그대로다.

연결 상태 변경의 메서드별 진단은 apiConnectionProbe로 진입·복원 지연을 구분한다. apiConnectionPilot -PconnectionCalls=OFF 또는ON은 기본1천 건이며, -PdeliveryTargets=10000으로1만 건을 허용한다(두 값만 허용). ON은 getAutoCommit과setAutoCommit(false/true)를 따로 기록한다. 제어군과 자연86개 접수의 호출 순서는 검증했으나 앞선127ms 상태 합계는 재현하지 못했다. 같은 계측의1만 건2회 반복도 접수684개/상태 상세2052개를 대조했지만20ms 이상 상태 호출은 없었다.

장시간 실패 직전 관찰·중단 기준은 최근32건과 진행 중1건을 보관하는 테스트 프로토타입이다. 첫 실패 snapshot을 늦은 응답이 바꾸지 않는지 검증했다. 실제 HTTP/MySQL 접수 제어는 apiFailurePersistenceProbe로 종료 전 첫 파일 저장과 늦은 처리 후 불변을 검증한다. 작은 Kafka 혼합 실험은 apiFailurePilot의1천 건 opt-in 연결로 정상 전수 대조와 timeout·저장 실패 보존을 검증했다. 장시간 도구의 선택적 보존은 campaignDeliveryMillion -PfailureObservation=ON으로 켜며 기본OFF다. 발송 없는 OFF/ON 설정 확인과1천 건 리허설까지 검증했다. 최종 보고서 오류 처리는 report 쓰기가 실패해도 원래 실행 오류를 유지한다. 100만 건 관찰 실행 분석은 캠페인190131건 수락 뒤 예산 조회 불가1회로 Worker가 중단된FAIL 기록이다. 예산 조회 진단·유한 복구는 고정 오류 분류와 첫 실패 진단을 보존하고, -PtransientQuotaRecovery=ON에서만 일시 연결 오류를 최대3번 pause 후 새 허가로 재시도한다. 기본OFF이며 상태 오류는 계속 중단한다. 100만 건 HTTP Mock 검증은 e5e5b01에서 캠페인1000000+실시간54124건의 전수대조를 통과했다. 발송 구간78.747건/초, 관찰 중복0이며 단말 도착을 뜻하지 않는다. 이 실행의Redis 오류는0회로 복구 발동 효과를 확정하지 않는다. 첫 실행의API timeout 원인 규명은 아직 남아 있다.

S8 실험 종합 대조·기본값 결정에서 HTTP18회/Kafka단독8회의 원본·조건·계산을 함께 확인할 수 있다. 실험별 산술평균과 총 건수÷총 시간은 구분하며, 서로 다른 실험의 개선율은 합치지 않는다. Consumer3/활성3/대기0은 실험 설정이고 저장소 기본은1/1/2다. 이번 대조에서 운영 기본값은 바꾸지 않았다.

S8 캠페인 동시처리수 비교는 1만 건을 조건별 2회 처리했다. Consumer/Worker 활성 상한 1/1·2/2·3/3의 평균 처리량은 각각 47.324/67.566/94.154건/초였다. 6회 합계 캠페인 60000+실시간 4558건의 HTTP·DB·매핑·offset 대조를 통과했다. 공유 호스트의 작은 비교이며 두 설정의 개별 효과를 분리하지 않는다. 운영 기본값은 유지한다. 명시적 실행은 ./gradlew consumerScalingPilot -PcampaignConsumers=1이며 1·2·3만 허용한다.

S8 파티션 3→6 계약 검증은 실제 Kafka에서 key 배정·기존 기록·순서·offset 초기화와 live 재할당을 확인했다. 60개 key 중 27개가 이동했고 기존 기록은 원래 파티션에 남았다. latest 제어군은 신규 파티션의 사전 기록 6건을 건너뛰어도 최종 lag가 0이었다. 앱은 earliest와 토픽별 파티션 3개 선언을 유지한다. HTTP 발송 경로 비교는 아래 별도 실험으로 구분한다.

S8 파티션 확대의 복구 예산은 요청·Retry 6+6의 실제 Worker 오류 경계를 검증했다. 이력 슬롯 기본 6을 유지하며 app.rate-limit.transient-recovery-max-records=12를 명시적으로 선택할 수 있다(허용 1~12). 슬롯 부족·지속 장애·잘못된 상태는 계속 중단하며, 이 옵션은 토픽 수나 Worker 동시성을 자동 확대하지 않는다.

S8 HTTP Mock 파티션 3/6 비교는 Consumer/Worker 활성 상한 3과 자원/quota/복구 용량 12를 고정했다. 3→6→6→3의 4회에서 캠페인40000+실시간2938건의 HTTP·DB·매핑·전체 offset을 대조했다. 평균 처리량은 3개에서55.749건/초, 6개에서68.392건/초였다. 같은 3개 조건의 실행 간 차이도 커서 +22.68%를 인과적 개선율로 확정하지 않는다. 운영 기본 파티션은 3을 유지한다. 테스트 전용 ./gradlew partitionScalingPilot -PcampaignPartitions=3은 3/6만 허용한다.

S8 producer batching·압축 사전 비교는 Kafka 단독 4조건을 각2회/13200건 전수 대조했다. 단건 ACK에서는 linger만 늘려도 묶음이 충분히 생기지 않았다. 제출창10/LZ4의 바이트 감소도 앱 처리량 개선으로 간주하지 않는다. 운영 Relay/producer 기본값은 유지한다. 별도 ./gradlew producerBatchingPilot은 DB/Worker/HTTP를 실행하지 않는다.

S8 실제 HTTP 경로 압축 비교는 캠페인 none/LZ4만 바꿔 각2회/HTTP42352건을 전수 대조했다. producer outgoing byte counter 평균은4.79% 줄었지만 처리량/실시간 지연 개선은 확인하지 못했다. 실행 변동과 측정 범위를 함께 남기고 운영 기본none·순차ACK·linger0을 유지한다. 명시적 ./gradlew compressionDeliveryPilot -PcampaignCompression=none은 none/lz4만 허용한다.

S8 Relay 제출 창 오류 경계에서는 선택 옵션 app.async.relay.submission-window-size=2..10을 추가했다. 기본1은 기존 순차 ACK 경로다. ACK 후 DB 갱신 묶음인 publish-batch-size와 별도이며, producer/broker 요청 개수 설정도 아니다. 창 하나를 모두 확인한 뒤 다음 창으로 넘어가고, ACK 미확인·일부 실패에서는 해당 호출의 새 창을 채우지 않는다. 이전 주기에 남은 미완료 future도 최대 한 창만 보관하며, 해소되기 전에는 다음 주기의 선점·제출을 막는다. timeout/interrupt의 미확인 전송은 취소됐다고 가정하지 않고 lease로 복구하므로 재발행 중복은 가능하다. 집중13개에서 실제 DB와 합성 future 오류, 실제 Kafka 6개 기록/Worker 호출3회 복구를 확인했다. 실제 HTTP 경로의 처리량·실시간 지연 비교와 제출 중 강제 프로세스 종료는 이번 검증 범위 밖이다. 기본1/linger0/none과 Worker/quota/토픽은 유지한다. 오류 경계 구현 당시 전체 build는16분30초/47개 클래스·379개 통과(실패·오류·스킵0)였다. 검증 원본을 참고한다.

S8 실제 HTTP 경로 제출 창1/10 비교는 1→10→10→1 순서로4회/HTTP42217건을 전수 대조했다. 합산 처리량은86.279→90.969건/초(+5.44% 관측)였지만 실행별 범위와 실시간 지연이 겹쳐 인과적 개선 효과를 확정하지 않는다. 제출10의 records/request 시간 창 평균도 약1.001로 큰 묶음 증가는 관측되지 않았다. 기본 제출1을 유지한다. 별도 ./gradlew relayWindowDeliveryPilot -PcampaignWindow=1을 사용한다. campaignWindow는 1·10만 허용하며 완료 저장1/linger0/none·자원/quota를 고정한다. 비교 도구의 전체 build는16분23초/48개 클래스·384개 통과(실패·오류·스킵0)였다. 최종 로컬 검증을 보존했다.

S8 파티션 간 완료 순서 검증은 한 파티션의 첫 작업을 유지하는 동안 다른 파티션의 두 작업을 먼저 완료시킨다. RECORD/테스트용 COUNT_TIME에서 미완료 offset 보존과 DB 완료 실패 후 새 앱 복구를 확인했다. 클래스 집중15개가 통과했다. 실패 복구에서는 알림4개에 HTTP 수락5회가 발생했다. 같은 파티션 내부는 동기 처리이며 외부 exactly-once를 보장하지 않는다. 전체 build는16분30초/48개 클래스·388개 통과(실패·오류·스킵0)였다. 로컬 검증 원본을 보존했다.

10만 건 발송은 별도 campaignDeliveryLoad task로 실행한다. 상한·전수 검증·측정 경계를 참고한다. 각 테스트 결과는 build/reports/tests/test/, build/reports/tests/reconciliationTest/, build/reports/tests/campaignLoadTest/, build/reports/tests/campaignDeliveryPilot/, build/reports/tests/campaignDeliveryLoad/에 저장된다. 100만 건 task를 실제 실행할 경우 build/reports/tests/campaignDeliveryMillion/에 별도 결과를 만든다. 코드를 바꾸지 않고 JAR만 다시 만들려면 ./gradlew bootJar를 사용한다.

이전 단계 비교

프로필 생성 응답 저장 Kafka
기본(S3) 접수 커밋 후 202 MySQL + Outbox 사용
sync(S2) 동기 결과 커밋 후 201 MySQL 사용하지 않음
memory(S1) 동기 처리 후 201 메모리 최대 10,000건 사용하지 않음
./gradlew bootRun --args='--spring.profiles.active=sync'
./gradlew bootRun --args='--spring.profiles.active=memory'

memory 앱은 Docker 없이 실행 가능하지만 전체 테스트는 Docker가 필요하다. S2 시절 이미 남은 PROCESSING 레코드는 Outbox가 없으므로 S3에서 자동 복구하지 않는다.

지표

  • notification_provider_attempts_total, notification_completed_total{status=...}: 시도/저장된 최종 결과. 중간 재시도 예약은 완료에 포함하지 않음.
  • notification_retry_scheduled_total: 성공적으로 저장한 일시 실패의 후속 예약 수.
  • notification_processing_seconds_*: 공급자 처리와 결과 저장 시간. 큐 대기 제외.
  • http_server_requests_seconds_*: HTTP 처리 시간.
  • outbox_unpublished, outbox_failed, outbox_oldest_age_seconds: 해당 프로세스 역할의 미발행 수(FAILED 포함), 실패 수, 가장 오래된 미발행 시간.
  • notification_consumer_lag: 해당 역할의 요청/Retry 두 토픽의 end offset에서 Worker 그룹 committed offset을 뺀 파티션별 합계. DLQ 제외.
  • outbox_sample_age_seconds, notification_consumer_sample_age_seconds: 마지막 지표 수집 성공 후 경과 시간.
  • notification_worker_active, notification_worker_waiting, notification_worker_admission_rejected_total{reason=...}: 처리/대기 수와 진입 거절 횟수.
  • notification_worker_running: 소비 중 1, 정지 0.
  • notification_rate_limit_decisions_total{outcome=allowed|limited|unavailable}, notification_rate_limit_connections_active: 제한기 호출 결과와 사용 중 Redis 연결 수. 클라이언트 활성화 시 등록. 허가 판정 지표이며 실제 HTTP 호출 수와 다를 수 있음.
  • notification_worker_quota_waiting, notification_worker_quota_rejected_total{reason=timeout|unavailable|stopping|interrupted}: 이전 동기 비교 모드의 대기 수와 두 모드의 진입 거절. pause 중 waiting은 0.
  • notification_provider_circuit_state, notification_provider_circuit_failures, notification_provider_circuit_probe_active: 프로세스별 회로 상태(0/1/2), 실패 수, 탐침 점유. 상세 카운터는 회로 문서 참고.
  • notification_worker_circuit_pauses_pending, notification_worker_circuit_pauses_total, notification_worker_circuit_resumes_total: 회로 차단 사유의 재개 예약과 요청 수.
  • notification_worker_quota_pauses_pending, notification_worker_quota_pauses_total, notification_worker_quota_resumes_total: 재개 예약 수와 pause/resume 요청 수. 실제 pause 확정은 컨테이너 상태와 함께 확인.
  • notification_worker_exhausted_total: 복구 선점 상한을 소진해 최종 저장한 작업 수.
  • outbox_publish_failures_total, outbox_published_total, notification_worker_failures_total, notification_worker_replays_total.

DB/Kafka 지표는 약 5초 주기로 수집하며 수집 실패는 NaN으로 표시한다. 실패를 lag 0으로 표현하지 않는다. 카운터는 프로세스 기준이며 정확한 대조는 DB/offset으로 수행한다. ID나 수신자/payload를 메트릭 label에 넣지 않는다. health UP만으로 Worker 정상 처리나 lag 0을 판단하지 않는다.

로컬 모니터링

선택 구성 docker compose -f compose.monitoring.yml up -d로 Prometheus와 Grafana를 실행한다. Grafana 대시보드는 22개 패널로 역할별 적체·Worker·처리 지연·자원을 표시한다. 앱은 별도로 8080(REALTIME)/8082(CAMPAIGN)에 실행해야 한다. 앱이 없으면 대상 연결0·업무 지표 데이터 없음이 정상적인 표시다. 기본 앱/기존 DB 볼륨을 바꾸지 않는 Docker Desktop용 localhost 전용 읽기 구성이다. 실행·메트릭 해석·검증·제한을 참고한다. 외부 경고 전송은 연결하지 않았다. 추가 후 전체 build는17분30초/49개 클래스·389개 통과(실패·오류·스킵0)였다. 로컬 검증 원본을 보존했다.

로컬 LB와 여러 앱 프로세스

S9 로컬 토폴로지는 실제 HAProxy 앞의 API2개와 별도 Worker2개 JVM을 사용한다. API는 Worker/Relay를 끄고, Worker 두 개는 같은 REALTIME group·Redis 예산으로 소비하며 각각 Relay를 실행한다. ./gradlew test --tests '*LocalTopologyIntegrationTest'로 기존 사용자 DB와 분리된 실제 MySQL/Kafka/Redis/HTTP Mock 검증을 재현한다. API 제외 후 재접수·본문 충돌, 작업을 비운 Worker 종료 후 6파티션 인수, 공통 예산과 HTTP/DB/offset 전수 대조를 확인한다. 검증 중 드러난 timed offset 커밋의 Wakeup은 같은 완료 offset·원래 deadline 안에서 한 번만 재시도한다. 공급자 호출이나 미완료 작업을 성공으로 바꾸지 않으며 재차 실패하면 기존 중단 정책을 유지한다.

선택 compose.topology.yml은 localhost18000의 LB만 실행한다. native API18010/18011와 공유 인프라는 별도 준비해야 한다. 동일 PC·REALTIME 한 lane의 정합성 실험이며 실제 서버 고가용성·처리 중 종료·대량 처리량·클라우드 배포를 검증한 결과는 아니다. 실제 건수·실패와 보완·검증 결과는 실험 문서에 기록한다. 전체 회귀는51개 클래스·397개 통과(25분53초)였고, 이후 테스트 표본 하한만 강화해 집중1개/27건을 다시 통과했다. 운영 소스·구성은 같으며 두 실행을 합산하지 않는다. 검증 원본을 보존한다.

세 주제별 학습·설계 판단에서 외부 API 보호, 유실·중복 대응, 병렬 처리·배포를 문제·대안·선택 이유·실제 전후 증거·남은 한계로 연결해 읽을 수 있다. DB 잠금 진단과 외부 수락의 불확실성, 성능 실험 조건/기본값 차이도 함께 설명한다.

이후 70fe60f의 원격 CI는397개 중3개 Worker 동시성 테스트가 실패했다. 시작 준비 조건 진단과 보완에 원격 실패와 로컬 재검증을 구분해 기록한다. 로컬 통과만으로 새 커밋의 원격 CI 성공을 뜻하지 않는다.

한계와 문서

자동 Redis failover, 실제 회원 DB 대상자 조회, 다중 DB/failover 환경의 Batch 복구, 실제 FCM/APNs, 인증과 운영 배포는 아직 구현하지 않았다. 데이터 보관/정리 정책도 없다. 브로커 보관 기간이 지난 미처리 메시지, volume 손실까지 보호하지 않는다.

About

Kafka 기반 알림 시스템을 단계별로 만드는 Java/Spring 학습 프로젝트

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages