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
This commit is contained in:
DongHyeonka
2026-11-13 19:30:12 +09:00
parent 346f8be837
commit 13ffb6cfb1
7 changed files with 20 additions and 22 deletions
-1
View File
@@ -66,7 +66,6 @@ status: 초안
- error-codes.yaml rows: `INTERNAL_ERROR`, `INTERNAL_AUTH_MISCONFIGURATION`, `JVM_OOM` - 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` - 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]]
--- ---
+3 -4
View File
@@ -38,7 +38,7 @@ status: 초안
- 최종 실패 원인 분류: - 최종 실패 원인 분류:
- poison input(직렬화/계약 위반) → 입력 결함, 재처리해도 실패 — 수정 후 재처리 또는 폐기 - poison input(직렬화/계약 위반) → 입력 결함, 재처리해도 실패 — 수정 후 재처리 또는 폐기
- 외부 의존성 장기 outage 중 attempts 소진 → 의존성 회복 후 재처리로 해결 가능 - 외부 의존성 장기 outage 중 attempts 소진 → 의존성 회복 후 재처리로 해결 가능
- non-transient error(권한/도메인/스키마)인데 retry된 경우 → 분류기 보강 필요(WAF-REL05-C3: 즉시 DLQ가 정답) - non-transient error(권한/도메인/스키마)인데 retry된 경우 → 분류기 보강 필요(다시 해도 같은 결과인 오류는 retry 없이 곧바로 DLQ로 보내야 한다)
## 4. Mitigation (수동 처분 — 둘 중 하나) ## 4. Mitigation (수동 처분 — 둘 중 하나)
@@ -60,9 +60,8 @@ status: 초안
- error-codes.yaml rows: `JOB_DEAD_LETTER` (INTERNAL, 500, retryable=false) - 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}` - metrics.yaml: `job.dlq.total{job_name}`, `job.retry.total{job_name, outcome=DLQ}`
- 코드: `app-bootstrap` `async/BackgroundJobMetrics`(retry/DLQ vocabulary 기록 seam — D2/D4) - 코드: `app-bootstrap` `async/BackgroundJobMetrics`(`job.retry.total`·`job.dlq.total`을 남기는 곳)
- 관련 runbook: [[job-executor-rejected]], [[job-timeout]], [[outbox-dead-letter]] - 관련 runbook: [job-executor-rejected.md](job-executor-rejected.md), [job-timeout.md](job-timeout.md), [outbox-dead-letter.md](outbox-dead-letter.md)
- 관련 branch: [[feature-background-job-async-contract]] (D4 retry/DLQ vocabulary SSOT — outbox/outbound가 consume)
--- ---
+3 -4
View File
@@ -43,8 +43,8 @@ status: 초안
- 단기: 유입 감속(상위 rate-limit / 스케줄러 interval 확대) 또는 다운스트림 의존성 회복 - 단기: 유입 감속(상위 rate-limit / 스케줄러 interval 확대) 또는 다운스트림 의존성 회복
- pool 재조정(restart-only): `APP_ASYNC_EXECUTOR_CORE_SIZE` / `APP_ASYNC_EXECUTOR_MAX_SIZE` / `APP_ASYNC_EXECUTOR_QUEUE_CAPACITY` - pool 재조정(restart-only): `APP_ASYNC_EXECUTOR_CORE_SIZE` / `APP_ASYNC_EXECUTOR_MAX_SIZE` / `APP_ASYNC_EXECUTOR_QUEUE_CAPACITY`
— ⚠ queue를 무한정 키우지 말 것(unbounded 금지, D7). 부하테스트로 수치 검증 후 변경 — ⚠ queue를 무한정 키우지 말 것(한도 없는 queue는 거부 대신 메모리를 다 쓰고 무너진다). 부하테스트로 수치 검증 후 변경
- CallerRunsPolicy로의 전환은 use-case 차원의 명시적 결정 필요(request thread latency 침식 — TPE-JDK21-C6) - CallerRunsPolicy로의 전환은 use-case 차원의 명시적 결정 필요(넘친 작업을 부른 요청 스레드가 직접 돌려서 그 요청의 지연이 늘어난다)
## 5. Escalation ## 5. Escalation
@@ -62,8 +62,7 @@ status: 초안
- metrics.yaml: `executor.rejected.total{executor_name, policy}`, `executor.saturation{executor_name}` - 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` - 코드: `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` - env: `APP_ASYNC_EXECUTOR_CORE_SIZE` / `APP_ASYNC_EXECUTOR_MAX_SIZE` / `APP_ASYNC_EXECUTOR_QUEUE_CAPACITY`
- 관련 runbook: [[job-timeout]], [[job-dead-letter]] - 관련 runbook: [job-timeout.md](job-timeout.md), [job-dead-letter.md](job-dead-letter.md)
- 관련 branch: [[feature-background-job-async-contract]] (D7 saturation policy)
--- ---
+6 -7
View File
@@ -39,13 +39,13 @@ status: 초안
- metric panel: `job.retry.total{job_name, outcome}` - metric panel: `job.retry.total{job_name, outcome}`
- 가능한 원인 우선순위: - 가능한 원인 우선순위:
- 외부 의존성(DB lock / 느린 HTTP) 지연으로 job p99 상승 - 외부 의존성(DB lock / 느린 HTTP) 지연으로 job p99 상승
- job 작업량 증가로 단일 cycle이 19s 예산 초과 (D8 — interrupt 노출) - job 작업량 증가로 한 cycle이 종료 대기 19s를 넘김(종료할 때 executor가 실행 중인 작업을 기다리는 시간)
- interrupt 미반응 blocking call(JDBC 등) → awaitTermination 초과 (K8S-POD-LC-C2 SIGKILL 경로) - interrupt 미반응 blocking call(JDBC 등) → awaitTermination 초과(그 사이 k8s grace period가 끝나면 SIGKILL로 죽는다)
## 4. Mitigation ## 4. Mitigation
- 단기: 의존성 회복 / job 입력 배치 크기 축소 - 단기: 의존성 회복 / job 입력 배치 크기 축소
- job p99가 구조적으로 19s를 넘으면: 작업을 분할하거나, grace period 연장 검토(parent project 운영 계약 소유자 승인 필요 — OUT_OF_BRANCH_SCOPE) - job p99가 구조적으로 19s를 넘으면: 작업을 분할하거나, grace period 연장 검토(grace period는 배포 설정이 정하므로 그 설정을 가진 팀과 정한다)
- 비멱등 job이 재시도로 중복 부작용을 내면 멱등키/dedupe 도입 우선 - 비멱등 job이 재시도로 중복 부작용을 내면 멱등키/dedupe 도입 우선
## 5. Escalation ## 5. Escalation
@@ -65,10 +65,9 @@ status: 초안
- error-codes.yaml rows: `JOB_TIMEOUT` (TRANSIENT_DEPENDENCY, 500, retryable=true, retry_after 10s) - error-codes.yaml rows: `JOB_TIMEOUT` (TRANSIENT_DEPENDENCY, 500, retryable=true, retry_after 10s)
- metrics.yaml: `job.retry.total{job_name, outcome}` - metrics.yaml: `job.retry.total{job_name, outcome}`
- 코드: `app-bootstrap` `async/AsyncExecutorConfig`(awaitTermination 19s — D8 graceful shutdown) - 코드: `app-bootstrap` `async/AsyncExecutorConfig`(종료 때 실행 중인 작업을 최대 19s 기다린다, `AWAIT_TERMINATION_SECONDS`)
- env: `APP_SERVER_SHUTDOWN_TIMEOUT`(owner: feature-env-driven-runtime-configuration D2) - env: `APP_SERVER_SHUTDOWN_TIMEOUT`(웹 요청 drain 시간, 정의는 `docs/registries/env-keys.yaml`)
- 관련 runbook: [[job-executor-rejected]], [[job-dead-letter]] - 관련 runbook: [job-executor-rejected.md](job-executor-rejected.md), [job-dead-letter.md](job-dead-letter.md)
- 관련 branch: [[feature-background-job-async-contract]] (D4 retry / D8 shutdown)
--- ---
+1 -2
View File
@@ -98,8 +98,7 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status
- §4의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다 - §4의 SQL 블록은 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는 테스트가 있다
(`PostgreSqlOutboxDispositionRunbookIntegrationTest`, lane `postgresqlOutboxDispositionRunbookIntegrationTest`). (`PostgreSqlOutboxDispositionRunbookIntegrationTest`, lane `postgresqlOutboxDispositionRunbookIntegrationTest`).
블록을 고치면 그 lane을 다시 돌린다 블록을 고치면 그 lane을 다시 돌린다
- 관련 runbook: [[outbox-publish-failed]] - 관련 runbook: [outbox-publish-failed.md](outbox-publish-failed.md)
- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (max attempts/DLQ vocabulary SSOT)
## 8. 배포 전 확인 — V21 순서 키 중복 ## 8. 배포 전 확인 — V21 순서 키 중복
+2 -3
View File
@@ -114,7 +114,7 @@ UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '<id>' AND status = '
`UPDATE 0`이면 그 사이 relay가 행을 claim해 IN_FLIGHT다. `next_attempt_at`이 지난 뒤 다시 실행한다. `UPDATE 0`이면 그 사이 relay가 행을 claim해 IN_FLIGHT다. `next_attempt_at`이 지난 뒤 다시 실행한다.
보류된 행 수는 `outbox.pending.size{status=PARKED}`로 보인다. 보류된 행 수는 `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` 상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing`
경보의 입력이 사라진다. 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두 경보의 입력이 사라진다. 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을 Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을
@@ -155,8 +155,7 @@ UPDATE outbox_event SET status = 'PUBLISHED' WHERE event_id = '<id>' AND status
- error-codes.yaml rows: `OUTBOX_PUBLISH_FAILED` (TRANSIENT_DEPENDENCY, retryable=true, retry_after 30s) - 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` - 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, 원인 코드 번역) - 코드: `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]] - 관련 runbook: [outbox-dead-letter.md](outbox-dead-letter.md)
- 관련 branch: [[feature-domain-event-outbox-contract]], [[feature-background-job-async-contract]] (retry/DLQ vocabulary SSOT)
--- ---
+5 -1
View File
@@ -1,6 +1,8 @@
# 업그레이드 안내 — 2026-11 GraphQL 관측 tag·안 쓰는 헤더 상수·인증 설정 runbook 이름 # 업그레이드 안내 — 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/`)의 관측·인증 묶음을 고칠 때 범위 밖으로 남긴 후속 - 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 관측·인증 묶음을 고칠 때 범위 밖으로 남긴 후속
## 1. 누가 읽나 ## 1. 누가 읽나
@@ -25,3 +27,5 @@ web `ApiHeaders` 상수를 부르는 서비스, 오류 코드의 runbook 링크
- 지표 이름(`graphql.request`, `graphql.datafetcher`, `graphql.dataloader`)과 GraphQL 응답 모양은 그대로다. - 지표 이름(`graphql.request`, `graphql.datafetcher`, `graphql.dataloader`)과 GraphQL 응답 모양은 그대로다.
- gRPC 권한 거부의 wire 응답(`PERMISSION_DENIED`, `error-code=AUTHZ_INSUFFICIENT_PERMISSION`)도 그대로다. 이번에 더한 시험이 - gRPC 권한 거부의 wire 응답(`PERMISSION_DENIED`, `error-code=AUTHZ_INSUFFICIENT_PERMISSION`)도 그대로다. 이번에 더한 시험이
그것을 확인한다. 그것을 확인한다.
- runbook 본문은 옛 설계 번호·브랜치 이름·커밋 sha를 평범한 설명으로 바꿨을 뿐 절차는 그대로다. 관련 runbook 링크는
상대 링크(`[job-timeout.md](job-timeout.md)`)다.