Files
clean-architecture-backend-…/docs/runbooks/job-timeout.md
T
DongHyeonka 13ffb6cfb1 docs(runbooks): runbook 본문의 옛 설계 번호와 커밋 sha를 설명으로 바꾼다
job·outbox·internal-error-spike runbook이 근거를 템플릿 개발 때의 설계
번호(D2·D4·D7·D8, K8S-POD-LC-C2, WAF-REL05-C3, TPE-JDK21-C6,
OUT_OF_BRANCH_SCOPE), 옛 feature 브랜치 이름의 wiki 링크, 커밋 sha
bbe944bd로 적는다. 파생 서비스의 운영자는 그 번호와 브랜치를 찾을 수
없어 근거를 읽지 못한다.

번호마다 그 뜻을 문장으로 쓴다: 한도 없는 queue가 무너지는 이유,
CallerRunsPolicy가 요청 지연을 늘리는 이유, 종료 대기 19s와 k8s grace
period의 SIGKILL, 다시 해도 같은 오류는 곧바로 DLQ로. PARKED가 생긴
버전은 커밋 sha 대신 V22 migration으로 가리킨다. 「관련 branch」 줄은
지우고, 「관련 runbook」의 wiki 링크는 상대 링크로 바꾼다.

위험: 문서만 바뀐다. 절차와 SQL 블록은 그대로다.

검증: python3 scripts/check-work-docs.py --history docs/runbooks에서
걸린 줄 0, check-docs.py OK.

Refs: round9 그룹 A 범위 밖 후속 6
2026-11-13 19:30:12 +09:00

4.0 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — background job timeout TRANSIENT_DEPENDENCY
JOB_TIMEOUT
P2 oncall 2026-11-13 초안

Runbook: background job timeout (runbook://job/timeout)

1. Trigger

JOB_TIMEOUT은 enum 상수와 registry 행이 있지만 템플릿 코드는 내지 않는다. job.retry.total도 서비스가 BackgroundJobMetrics.recordRetryOutcome을 부를 때만 생긴다. 그래서 이 runbook의 코드·지표 신호는 서비스가 job 시간 상한·재시도를 붙여 낼 때만 있다. 이 템플릿은 경보 규칙을 두지 않는다.

  • 템플릿이 내는 신호는 종료 때 하나다: async executor가 남은 작업을 19s 기다리고도 끝나지 않으면 Spring이 WARN 줄 Timed out while waiting for executor '<bean 이름>' to terminate를 남긴다 (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS). 남은 작업은 JVM이 끝날 때 함께 끊긴다.
  • 서비스가 낼 때 경보에 실을 만한 값: error.code=JOB_TIMEOUT, job_name, correlation_id
  • 임계: job.retry.total{outcome=RETRY} 급증

2. First Response (10분 이내)

Step 1 — 확인

  1. ERROR log에서 JOB_TIMEOUT 라인 확인: job_name, 마지막 단계, 소요 시간 추출
  2. timeout이 정상 실행 중 발생인지, graceful-shutdown(배포/스케일다운) 중 interrupt인지 구분
  3. 해당 job이 멱등(retry-on-next-cycle 안전)인지 확인 — 비멱등이면 §4에서 신중히 처리

Step 2 — 임시 격리

  • shutdown 중 interrupt면: 다음 기동 시 재시도 대상인지(멱등 전제) 확인, 중복 부작용 여부 점검
  • 정상 실행 중 timeout이면: 해당 job의 외부 의존성(DB/HTTP) 지연 여부 확인

3. Diagnosis

  • log query: {service="app"} | error.code="JOB_TIMEOUT" | stats count by job_name
  • metric panel: job.retry.total{job_name, outcome}
  • 가능한 원인 우선순위:
    • 외부 의존성(DB lock / 느린 HTTP) 지연으로 job p99 상승
    • job 작업량 증가로 한 cycle이 종료 대기 19s를 넘김(종료할 때 executor가 실행 중인 작업을 기다리는 시간)
    • interrupt 미반응 blocking call(JDBC 등) → awaitTermination 초과(그 사이 k8s grace period가 끝나면 SIGKILL로 죽는다)

4. Mitigation

  • 단기: 의존성 회복 / job 입력 배치 크기 축소
  • job p99가 구조적으로 19s를 넘으면: 작업을 분할하거나, grace period 연장 검토(grace period는 배포 설정이 정하므로 그 설정을 가진 팀과 정한다)
  • 비멱등 job이 재시도로 중복 부작용을 내면 멱등키/dedupe 도입 우선

5. Escalation

  • 의존성 지연이 근본 원인이면 해당 의존성 오너에게 escalate
  • 종료 예산은 차례로 더한 값이다: 웹 drain(APP_SERVER_SHUTDOWN_TIMEOUT, 기본 30s)이 끝난 뒤 async 대기 19s, 합계 49s에 preStop(5s)과 여유를 더한다. k8s terminationGracePeriodSeconds가 이보다 작으면(예: 기본 30s) async 대기 중 SIGKILL이다. compose는 60s(compose.yaml stop_grace_period, 합계는 DeveloperExperienceContractTest가 검사). 정합 이슈면 플랫폼/런타임 오너에게 escalate

6. Recovery / Verification

  • 회복 확인: JOB_TIMEOUT 신규 발생 멈춤, job.retry.total{outcome=SUCCESS} 정상 비율 회복
  • 멱등 재시도분의 부작용 중복 없음 확인
  • error-codes.yaml rows: JOB_TIMEOUT (TRANSIENT_DEPENDENCY, 500, retryable=true, retry_after 10s)
  • metrics.yaml: job.retry.total{job_name, outcome}
  • 코드: app-bootstrap async/AsyncExecutorConfig(종료 때 실행 중인 작업을 최대 19s 기다린다, AWAIT_TERMINATION_SECONDS)
  • env: APP_SERVER_SHUTDOWN_TIMEOUT(웹 요청 drain 시간, 정의는 docs/registries/env-keys.yaml)
  • 관련 runbook: job-executor-rejected.md, job-dead-letter.md

Stub 상태 안내: 이 runbook은 skeleton 단계의 stub. 실제 retry carrier·job p99·shutdown 예산 확정 시 보강 필요.