diff --git a/docs/runbooks/internal-error-spike.md b/docs/runbooks/internal-error-spike.md index aa6c98e8..778f4909 100644 --- a/docs/runbooks/internal-error-spike.md +++ b/docs/runbooks/internal-error-spike.md @@ -66,7 +66,6 @@ status: 초안 - error-codes.yaml rows: `INTERNAL_ERROR`, `INTERNAL_AUTH_MISCONFIGURATION`, `JVM_OOM` - metrics.yaml: `jvm_memory_used_bytes`, `jvm_gc_pause_seconds`, `http_server_requests_seconds_count` -- 관련 branch: [[feature-operational-error-observability-foundation]], [[feature-container-runtime-contract]] --- diff --git a/docs/runbooks/job-dead-letter.md b/docs/runbooks/job-dead-letter.md index 3da9bd71..dc9289cd 100644 --- a/docs/runbooks/job-dead-letter.md +++ b/docs/runbooks/job-dead-letter.md @@ -38,7 +38,7 @@ status: 초안 - 최종 실패 원인 분류: - poison input(직렬화/계약 위반) → 입력 결함, 재처리해도 실패 — 수정 후 재처리 또는 폐기 - 외부 의존성 장기 outage 중 attempts 소진 → 의존성 회복 후 재처리로 해결 가능 - - non-transient error(권한/도메인/스키마)인데 retry된 경우 → 분류기 보강 필요(WAF-REL05-C3: 즉시 DLQ가 정답) + - non-transient error(권한/도메인/스키마)인데 retry된 경우 → 분류기 보강 필요(다시 해도 같은 결과인 오류는 retry 없이 곧바로 DLQ로 보내야 한다) ## 4. Mitigation (수동 처분 — 둘 중 하나) @@ -60,9 +60,8 @@ status: 초안 - error-codes.yaml rows: `JOB_DEAD_LETTER` (INTERNAL, 500, retryable=false) - metrics.yaml: `job.dlq.total{job_name}`, `job.retry.total{job_name, outcome=DLQ}` -- 코드: `app-bootstrap` `async/BackgroundJobMetrics`(retry/DLQ vocabulary 기록 seam — D2/D4) -- 관련 runbook: [[job-executor-rejected]], [[job-timeout]], [[outbox-dead-letter]] -- 관련 branch: [[feature-background-job-async-contract]] (D4 retry/DLQ vocabulary SSOT — outbox/outbound가 consume) +- 코드: `app-bootstrap` `async/BackgroundJobMetrics`(`job.retry.total`·`job.dlq.total`을 남기는 곳) +- 관련 runbook: [job-executor-rejected.md](job-executor-rejected.md), [job-timeout.md](job-timeout.md), [outbox-dead-letter.md](outbox-dead-letter.md) --- diff --git a/docs/runbooks/job-executor-rejected.md b/docs/runbooks/job-executor-rejected.md index e2920811..cea9e5c5 100644 --- a/docs/runbooks/job-executor-rejected.md +++ b/docs/runbooks/job-executor-rejected.md @@ -43,8 +43,8 @@ status: 초안 - 단기: 유입 감속(상위 rate-limit / 스케줄러 interval 확대) 또는 다운스트림 의존성 회복 - pool 재조정(restart-only): `APP_ASYNC_EXECUTOR_CORE_SIZE` / `APP_ASYNC_EXECUTOR_MAX_SIZE` / `APP_ASYNC_EXECUTOR_QUEUE_CAPACITY` - — ⚠ queue를 무한정 키우지 말 것(unbounded 금지, D7). 부하테스트로 수치 검증 후 변경 -- CallerRunsPolicy로의 전환은 use-case 차원의 명시적 결정 필요(request thread latency 침식 — TPE-JDK21-C6) + — ⚠ queue를 무한정 키우지 말 것(한도 없는 queue는 거부 대신 메모리를 다 쓰고 무너진다). 부하테스트로 수치 검증 후 변경 +- CallerRunsPolicy로의 전환은 use-case 차원의 명시적 결정 필요(넘친 작업을 부른 요청 스레드가 직접 돌려서 그 요청의 지연이 늘어난다) ## 5. Escalation @@ -62,8 +62,7 @@ status: 초안 - metrics.yaml: `executor.rejected.total{executor_name, policy}`, `executor.saturation{executor_name}` - 코드: `app-bootstrap` `async/AsyncExecutorConfig`(bounded executor), `async/LoggingAbortPolicy`(reject log+metric), `async/BackgroundJobMetrics` - env: `APP_ASYNC_EXECUTOR_CORE_SIZE` / `APP_ASYNC_EXECUTOR_MAX_SIZE` / `APP_ASYNC_EXECUTOR_QUEUE_CAPACITY` -- 관련 runbook: [[job-timeout]], [[job-dead-letter]] -- 관련 branch: [[feature-background-job-async-contract]] (D7 saturation policy) +- 관련 runbook: [job-timeout.md](job-timeout.md), [job-dead-letter.md](job-dead-letter.md) --- diff --git a/docs/runbooks/job-timeout.md b/docs/runbooks/job-timeout.md index 048b2a2f..4aeabaa8 100644 --- a/docs/runbooks/job-timeout.md +++ b/docs/runbooks/job-timeout.md @@ -39,13 +39,13 @@ status: 초안 - metric panel: `job.retry.total{job_name, outcome}` - 가능한 원인 우선순위: - 외부 의존성(DB lock / 느린 HTTP) 지연으로 job p99 상승 - - job 작업량 증가로 단일 cycle이 19s 예산 초과 (D8 — interrupt 노출) - - interrupt 미반응 blocking call(JDBC 등) → awaitTermination 초과 (K8S-POD-LC-C2 SIGKILL 경로) + - job 작업량 증가로 한 cycle이 종료 대기 19s를 넘김(종료할 때 executor가 실행 중인 작업을 기다리는 시간) + - interrupt 미반응 blocking call(JDBC 등) → awaitTermination 초과(그 사이 k8s grace period가 끝나면 SIGKILL로 죽는다) ## 4. Mitigation - 단기: 의존성 회복 / job 입력 배치 크기 축소 -- job p99가 구조적으로 19s를 넘으면: 작업을 분할하거나, grace period 연장 검토(parent project 운영 계약 소유자 승인 필요 — OUT_OF_BRANCH_SCOPE) +- job p99가 구조적으로 19s를 넘으면: 작업을 분할하거나, grace period 연장 검토(grace period는 배포 설정이 정하므로 그 설정을 가진 팀과 정한다) - 비멱등 job이 재시도로 중복 부작용을 내면 멱등키/dedupe 도입 우선 ## 5. Escalation @@ -65,10 +65,9 @@ status: 초안 - 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`(awaitTermination 19s — D8 graceful shutdown) -- env: `APP_SERVER_SHUTDOWN_TIMEOUT`(owner: feature-env-driven-runtime-configuration D2) -- 관련 runbook: [[job-executor-rejected]], [[job-dead-letter]] -- 관련 branch: [[feature-background-job-async-contract]] (D4 retry / D8 shutdown) +- 코드: `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-executor-rejected.md), [job-dead-letter.md](job-dead-letter.md) --- diff --git a/docs/runbooks/outbox-dead-letter.md b/docs/runbooks/outbox-dead-letter.md index 552e0eb9..aeb99105 100644 --- a/docs/runbooks/outbox-dead-letter.md +++ b/docs/runbooks/outbox-dead-letter.md @@ -98,8 +98,7 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '' AND status - §4의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다 (`PostgreSqlOutboxDispositionRunbookIntegrationTest`, lane `postgresqlOutboxDispositionRunbookIntegrationTest`). 블록을 고치면 그 lane을 다시 돌린다 -- 관련 runbook: [[outbox-publish-failed]] -- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (max attempts/DLQ vocabulary SSOT) +- 관련 runbook: [outbox-publish-failed.md](outbox-publish-failed.md) ## 8. 배포 전 확인 — V21 순서 키 중복 diff --git a/docs/runbooks/outbox-publish-failed.md b/docs/runbooks/outbox-publish-failed.md index 21275c88..0b68a5ec 100644 --- a/docs/runbooks/outbox-publish-failed.md +++ b/docs/runbooks/outbox-publish-failed.md @@ -114,7 +114,7 @@ UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '' AND status = ' `UPDATE 0`이면 그 사이 relay가 행을 claim해 IN_FLIGHT다. `next_attempt_at`이 지난 뒤 다시 실행한다. 보류된 행 수는 `outbox.pending.size{status=PARKED}`로 보인다. -**롤백 전에 보류를 푼다.** `PARKED`는 이 버전(`bbe944bd` 이후)에 생긴 상태다. 그보다 옛 버전은 이 이름을 몰라 +**롤백 전에 보류를 푼다.** `PARKED`는 V22 migration(`V22__outbox_event_last_failure_code.sql`)과 함께 생긴 상태다. V22 전 버전은 이 이름을 몰라 상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing` 경보의 입력이 사라진다. 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두 Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을 @@ -155,8 +155,7 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '' AND status - error-codes.yaml rows: `OUTBOX_PUBLISH_FAILED` (TRANSIENT_DEPENDENCY, retryable=true, retry_after 30s) - metrics.yaml: `outbox.publisher.published.total`, `outbox.publisher.lag`, `outbox.pending.size`, `outbox.retry.long.size`, `outbox.retry.long.age` - 코드: `application-core` `PublishPendingOutboxEventsUseCase`(상태머신), `adapter:outbound:persistence-jpa` `outbox/postgresql/PostgreSqlOutboxClaimRepository`(SKIP LOCKED claim + FIFO 게이트), `adapter:outbound:messaging` `outbox/OutboxMessagePublishAdapter`·`platformbridge/PlatformIntegrationEventPublishAdapter`(fail-closed, 원인 코드 번역) -- 관련 runbook: [[outbox-dead-letter]] -- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (retry/DLQ vocabulary SSOT) +- 관련 runbook: [outbox-dead-letter.md](outbox-dead-letter.md) --- diff --git a/docs/upgrade/2026-11-round9-followups.md b/docs/upgrade/2026-11-round9-followups.md index 3c02b0e7..bc7e8279 100644 --- a/docs/upgrade/2026-11-round9-followups.md +++ b/docs/upgrade/2026-11-round9-followups.md @@ -1,6 +1,8 @@ # 업그레이드 안내 — 2026-11 GraphQL 관측 tag·안 쓰는 헤더 상수·인증 설정 runbook 이름 -- 범위: 2026-11-12 전체 리뷰를 고친 뒤 남은 후속. GraphQL resolver·DataLoader 지표가 플랫폼 tag를 달고, GraphQL 지표가 요청마다 같은 tag key를 달고, 쓰는 곳 없는 `ApiHeaders` 상수 둘을 지웠고, `INTERNAL_AUTH_MISCONFIGURATION`의 runbook 이름을 내용에 맞췄다. gRPC 권한 거부를 wire에서 확인하는 시험을 더했다. +- 범위: 2026-11-12 전체 리뷰를 고친 뒤 남은 후속 다섯 건. GraphQL resolver·DataLoader 지표가 플랫폼 tag를 달고, GraphQL 지표가 + 요청마다 같은 tag key를 달고, 쓰는 곳 없는 `ApiHeaders` 상수 둘을 지웠고, `INTERNAL_AUTH_MISCONFIGURATION`의 runbook 이름을 + 내용에 맞췄다. gRPC 권한 거부를 wire에서 확인하는 시험을 더했고, runbook 본문의 옛 설계 번호·커밋 sha를 평범한 설명으로 바꿨다. - 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 관측·인증 묶음을 고칠 때 범위 밖으로 남긴 후속 ## 1. 누가 읽나 @@ -25,3 +27,5 @@ web `ApiHeaders` 상수를 부르는 서비스, 오류 코드의 runbook 링크 - 지표 이름(`graphql.request`, `graphql.datafetcher`, `graphql.dataloader`)과 GraphQL 응답 모양은 그대로다. - gRPC 권한 거부의 wire 응답(`PERMISSION_DENIED`, `error-code=AUTHZ_INSUFFICIENT_PERMISSION`)도 그대로다. 이번에 더한 시험이 그것을 확인한다. +- runbook 본문은 옛 설계 번호·브랜치 이름·커밋 sha를 평범한 설명으로 바꿨을 뿐 절차는 그대로다. 관련 runbook 링크는 + 상대 링크(`[job-timeout.md](job-timeout.md)`)다.