docs(runbooks): runbook을 한국어로 옮기고 상태를 초안·운영으로 바꾼다

문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.

고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
  lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`.
  머리말이 없는 gRPC runbook 둘은 그대로다.
- 코드에 맞춘 주장:
  - adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의
    `failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는
    곳은 `RoutingNotifier`뿐이다.
  - startup-required-adapter-disabled: `startup.phase=adapter-check` →
    `adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`).
  - cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure:
    그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다.
  - db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout`
    → `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다.
  - dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call`
    (`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다).
  - management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록
    (`config/observability.yml`).
  - runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프
    경로(`src/Dockerfile`)를 적었다.
  - auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`.
  - grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` →
    `GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로.
  - grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index
  migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는
  쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다.
- `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영`
  밖이면 실패하는 테스트를 더했다.
- `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다.

버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영
runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다.

위험·한계:
- 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다.
- runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의
  `-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다.
- `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다.

검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다.

검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
  `:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
  `postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
  `postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
  rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
  `:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
  `everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
This commit is contained in:
DongHyeonka
2026-11-07 17:56:34 +09:00
parent 03a313ed65
commit a81e92faca
51 changed files with 911 additions and 954 deletions
+18 -14
View File
@@ -4,31 +4,35 @@ category: INTERNAL
error_codes: [ADAPTER_DISABLED]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: ADAPTER_DISABLED (`runbook://adapter/adapter-disabled`)
## Symptoms
## 증상
- HTTP 500 with `error.code=ADAPTER_DISABLED`
- Code invoked an optional adapter (Kafka/Redis/Slack/Email) that is disabled in this deployment
- HTTP 500, `error.code=ADAPTER_DISABLED`.
- 이 배포에서 꺼져 있거나 묶이지 않은 선택 어댑터의 경로를 코드가 호출했다. 지금 템플릿에서 이 코드를 내는
곳은 알림 라우터(`RoutingNotifier`)다. 채널과 route에 묶인 provider가 없을 때 낸다.
## Diagnosis
## 진단
- Check adapter name in log (`adapter_name` field)
- Review deployment config — which optional adapters are enabled?
- ERROR 로그 `failure classified as ADAPTER_DISABLED (category=INTERNAL, retryable=false)`를 찾는다. 줄에 붙은
예외(`AdapterDisabledException`)의 메시지가 어댑터와 고칠 키를 알려 준다.
- 기본 메시지: `optional adapter '<이름>' is disabled (app.<domain>.<이름>.enabled=false) …`
- 알림 라우터: `no notification route bound for channel=… route='…' — set app.notification.routes.<channel>.<route>=<providerId>…`
- 배포 설정에서 어떤 선택 어댑터가 켜져 있는지 본다.
## Action
## 조치
- Enable the adapter in deployment configuration (env flag)
- Or update application logic to skip disabled-adapter paths
- 배포 설정에서 그 어댑터를 켠다(환경 변수 스위치). 알림이면 메시지가 가리키는 route를 묶고 그 provider를 켠다.
- 아니면 꺼진 어댑터의 경로를 건너뛰도록 애플리케이션 로직을 고친다.
## Escalation
## 에스컬레이션
- Escalate to deployment team if adapter should be enabled but isn't
- 켜져 있어야 할 어댑터가 꺼져 있으면 배포 담당 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+14 -14
View File
@@ -5,31 +5,31 @@ error_codes: [AUTH_AUDIENCE_MISMATCH]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTH_AUDIENCE_MISMATCH (`runbook://auth/audience-mismatch`)
## Symptoms
## 증상
- HTTP 401 with `error.code=AUTH_AUDIENCE_MISMATCH`
- Token `aud` claim does not include this service's expected audience
- HTTP 401, `error.code=AUTH_AUDIENCE_MISMATCH`.
- 토큰의 `aud` 클레임에 이 서비스가 기대하는 audience가 없다.
## Diagnosis
## 진단
- Check token `aud` claim value
- Compare against configured `app.security.audience` (`APP_SECURITY_JWT_AUDIENCE`, comma-separated;
the token must name at least one)
- 토큰의 `aud` 클레임 값을 본다.
- 설정된 `app.security.audience`(`APP_SECURITY_JWT_AUDIENCE`, 쉼표로 구분)와 비교한다. 토큰은 그중 하나 이상을
담아야 한다.
## Action
## 조치
- Verify client is requesting tokens scoped to the correct audience
- Update audience configuration if service identifier changed
- 클라이언트가 맞는 audience로 토큰을 요청하는지 확인한다.
- 서비스 식별자가 바뀌었으면 audience 설정을 고친다.
## Escalation
## 에스컬레이션
- Escalate to auth-platform team if misconfiguration is system-wide
- 설정 오류가 시스템 전체에 걸쳐 있으면 인증 플랫폼 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [AUTH_CLAIM_MAPPING_FAILED]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTH_CLAIM_MAPPING_FAILED (`runbook://auth/claim-mapping-failed`)
## Symptoms
## 증상
- HTTP 401 with `error.code=AUTH_CLAIM_MAPPING_FAILED`
- Token validated but required claims (sub, roles, tenant) missing or unexpected type
- HTTP 401, `error.code=AUTH_CLAIM_MAPPING_FAILED`.
- 토큰 검증은 통과했지만 필요한 클레임(sub, roles, tenant)이 없거나 타입이 다르다.
## Diagnosis
## 진단
- Inspect token payload claims via logs
- Check claim extractor configuration
- 로그에서 토큰 payload의 클레임을 본다.
- 클레임 추출 설정을 확인한다.
## Action
## 조치
- Verify IdP token template includes required claims
- Update claim mapping configuration if IdP schema changed
- IdP 토큰 템플릿에 필요한 클레임이 들어 있는지 확인한다.
- IdP 스키마가 바뀌었으면 클레임 매핑 설정을 고친다.
## Escalation
## 에스컬레이션
- Escalate to auth-platform team if IdP changed claim schema
- IdP가 클레임 스키마를 바꿨으면 인증 플랫폼 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [AUTH_ISSUER_MISMATCH]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTH_ISSUER_MISMATCH (`runbook://auth/issuer-mismatch`)
## Symptoms
## 증상
- HTTP 401 with `error.code=AUTH_ISSUER_MISMATCH`
- Token `iss` claim does not match configured expected issuer
- HTTP 401, `error.code=AUTH_ISSUER_MISMATCH`.
- 토큰의 `iss` 클레임이 설정된 발급자와 다르다.
## Diagnosis
## 진단
- Compare token `iss` against `spring.security.oauth2.resourceserver.jwt.issuer-uri`
- Check if IdP environment changed
- 토큰의 `iss`를 `spring.security.oauth2.resourceserver.jwt.issuer-uri`와 비교한다.
- IdP 환경이 바뀌었는지 확인한다.
## Action
## 조치
- Update issuer config if IdP migrated
- Reject tokens from unexpected issuers
- IdP를 옮겼으면 issuer 설정을 고친다.
- 예상하지 않은 발급자의 토큰은 계속 거부한다.
## Escalation
## 에스컬레이션
- Escalate to platform-security if unexpected issuer detected
- 예상하지 않은 발급자를 찾으면 플랫폼 보안 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+15 -15
View File
@@ -5,32 +5,32 @@ error_codes: [AUTH_JWKS_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-11-06
status: stub
status: 초안
---
# Runbook: AUTH_JWKS_UNAVAILABLE (`runbook://auth/jwks-unavailable`)
## Symptoms
## 증상
- HTTP 503 with `error.code=AUTH_JWKS_UNAVAILABLE`
- ERROR log line `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
(logger `AuthErrorResponseWriter`)
- All authentication failing; JWKS refresh attempts failing
- HTTP 503, `error.code=AUTH_JWKS_UNAVAILABLE`.
- ERROR 로그 줄 `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
(logger `AuthErrorResponseWriter`).
- 인증이 모두 실패하고, JWKS 새로 고침도 실패한다.
## Diagnosis
## 진단
- Check IdP JWKS endpoint health: `curl -sf https://<idp-host>/.well-known/jwks.json`
- Check network connectivity from app pods to IdP
- IdP의 JWKS 엔드포인트 상태를 본다: `curl -sf https://<idp-host>/.well-known/jwks.json`
- 앱 pod에서 IdP까지 네트워크가 닿는지 확인한다.
## Action
## 조치
- Enable cached JWKS fallback if available
- Coordinate with IdP team for restoration
- 캐시된 JWKS로 버틸 수단이 있으면 쓴다.
- IdP 팀과 복구를 맞춘다.
## Escalation
## 에스컬레이션
- P1 page: IdP team immediately if JWKS endpoint unreachable > 2 minutes
- P1 호출: JWKS 엔드포인트에 2분 넘게 닿지 않으면 IdP 팀을 바로 부른다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [AUTH_KID_UNKNOWN]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTH_KID_UNKNOWN (`runbook://auth/kid-unknown`)
## Symptoms
## 증상
- HTTP 401 with `error.code=AUTH_KID_UNKNOWN`, `retryable=true`
- Token `kid` header not present in cached JWKS
- HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`.
- 토큰 헤더의 `kid`가 캐시된 JWKS에 없다.
## Diagnosis
## 진단
- Check if IdP key rotation occurred recently
- Verify JWKS cache TTL and refresh timing
- 최근에 IdP 키 교체가 있었는지 확인한다.
- JWKS 캐시 TTL과 새로 고침 시점을 확인한다.
## Action
## 조치
- Force JWKS cache refresh
- Confirm new key is published in IdP JWKS endpoint
- JWKS 캐시를 강제로 새로 고친다.
- 새 키가 IdP JWKS 엔드포인트에 게시됐는지 확인한다.
## Escalation
## 에스컬레이션
- Escalate to IdP team if new kid not appearing in JWKS after 10 minutes
- 10분이 지나도 새 kid가 JWKS에 나타나지 않으면 IdP 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
@@ -4,33 +4,34 @@ category: INTERNAL
error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
severity: P1
owner: oncall
last_updated: 2026-11-06
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/public-path-misconfiguration`)
## Symptoms
## 증상
- HTTP 500 with `error.code=INTERNAL_AUTH_MISCONFIGURATION`
- ERROR log line `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
(logger `AuthErrorResponseWriter`)
- Security filter misconfiguration detected at runtime
- HTTP 500, `error.code=INTERNAL_AUTH_MISCONFIGURATION`.
- ERROR 로그 줄 `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
(logger `AuthErrorResponseWriter`).
- 실행 중에 보안 필터 설정 오류가 드러났다.
## Diagnosis
## 진단
- Check `verifyPublicPathSnapshot` output in CI
- Review recent changes to `SecurityConfig` or `application.yml` public path list
- CI의 `verifyPublicPathSnapshot` 결과를 본다.
- `SecurityConfig`와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근
변경을 본다.
## Action
## 조치
- Revert misconfigured public path change
- Run `./gradlew verifyPublicPathSnapshot` to compare snapshot
- 잘못된 공개 경로 변경을 되돌린다.
- `src/`에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
## Escalation
## 에스컬레이션
- P1 immediate: if auth bypass is possible due to misconfiguration
- P1 즉시: 설정 오류로 인증을 건너뛸 수 있으면.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+14 -14
View File
@@ -4,31 +4,31 @@ category: AUTH
error_codes: [AUTH_TOKEN_EXPIRED]
severity: P3
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: AUTH_TOKEN_EXPIRED (`runbook://auth/token-expired`)
## Symptoms
## 증상
- HTTP 401 with `error.code=AUTH_TOKEN_EXPIRED`
- Spike may indicate clock skew or long-lived token usage
- HTTP 401, `error.code=AUTH_TOKEN_EXPIRED`.
- 급증하면 시계 차이(clock skew)나 오래 사는 토큰을 의심한다.
## Diagnosis
## 진단
- Check `exp` claim vs server clock
- Check NTP sync on token-issuing host
- `exp` 클레임과 서버 시계를 비교한다.
- 토큰을 발급하는 호스트의 NTP 동기화를 확인한다.
## Action
## 조치
- Client must refresh tokens before expiry
- Verify clock skew tolerance is configured (default 60s)
- 클라이언트는 만료 전에 토큰을 새로 받아야 한다.
- 시계 차이 허용값을 확인한다. 이 템플릿의 JWT 검증기는 60초를 허용한다(`JwtDecoderConfig`).
## Escalation
## 에스컬레이션
- Escalate if spike is widespread or clock drift is confirmed
- 급증이 넓게 퍼졌거나 시계 어긋남이 확인되면 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+15 -15
View File
@@ -5,32 +5,32 @@ error_codes: [AUTH_TOKEN_INVALID_SIGNATURE]
severity: P1
owner: oncall
last_updated: 2026-11-06
status: stub
status: 초안
---
# Runbook: AUTH_TOKEN_INVALID_SIGNATURE (`runbook://auth/token-invalid-signature`)
## Symptoms
## 증상
- HTTP 401 with `error.code=AUTH_TOKEN_INVALID_SIGNATURE`
- WARN log line `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE category=AUTH method=… path=…`
(logger `AuthErrorResponseWriter`). It is a WARN because the caller sent the token; search by
`code=`, not by level. A burst of these may indicate forged tokens or a wrong signing key
- HTTP 401, `error.code=AUTH_TOKEN_INVALID_SIGNATURE`.
- WARN 로그 줄 `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE category=AUTH method=… path=…`
(logger `AuthErrorResponseWriter`). 토큰을 보낸 쪽이 호출자라서 WARN이다. 수준이 아니라 `code=`로 찾는다.
한꺼번에 몰리면 위조 토큰이나 잘못된 서명 키를 의심한다.
## Diagnosis
## 진단
- Check if JWKS endpoint returned a new key set
- Check for token forgery attempts in logs
- JWKS 엔드포인트가 새 키 묶음을 내놓았는지 확인한다.
- 로그에서 토큰 위조 시도를 찾는다.
## Action
## 조치
- Verify JWKS key IDs match token headers
- Alert security team if forgery suspected
- JWKS의 키 ID가 토큰 헤더와 맞는지 확인한다.
- 위조가 의심되면 보안 팀에 알린다.
## Escalation
## 에스컬레이션
- Immediate P1 escalation if forgery indicators present
- 위조 흔적이 있으면 바로 P1으로 올린다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [AUTH_TOKEN_MALFORMED, INVALID_TOKEN]
severity: P3
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTH_TOKEN_MALFORMED (`runbook://auth/token-malformed`)
## Symptoms
## 증상
- HTTP 401 responses with `error.code=AUTH_TOKEN_MALFORMED`
- Token present but fails JWT parse (not 3-part, non-base64, etc.)
- HTTP 401 응답, `error.code=AUTH_TOKEN_MALFORMED`.
- 토큰은 있지만 JWT로 파싱되지 않는다(세 부분이 아님, base64가 아님 등).
## Diagnosis
## 진단
- Inspect raw Authorization header value in logs
- Check if token generation tooling has a bug
- 로그에서 Authorization 헤더 원문을 본다.
- 토큰을 만드는 도구에 버그가 있는지 확인한다.
## Action
## 조치
- Identify source of malformed tokens
- Fix or update client token generation
- 잘못된 토큰이 어디서 오는지 찾는다.
- 클라이언트의 토큰 생성을 고친다.
## Escalation
## 에스컬레이션
- Escalate if spike suggests infrastructure issue
- 급증이 인프라 문제를 가리키면 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [AUTH_TOKEN_MISSING, UNAUTHENTICATED]
severity: P3
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTH_TOKEN_MISSING (`runbook://auth/token-missing`)
## Symptoms
## 증상
- HTTP 401 responses with `error.code=AUTH_TOKEN_MISSING`
- Client missing Authorization header or Bearer token
- HTTP 401 응답, `error.code=AUTH_TOKEN_MISSING`.
- 클라이언트가 Authorization 헤더나 Bearer 토큰을 보내지 않았다.
## Diagnosis
## 진단
- Check request logs for missing Authorization header
- Verify client SDK configuration
- 요청 로그에서 Authorization 헤더가 빠졌는지 본다.
- 클라이언트 SDK 설정을 확인한다.
## Action
## 조치
- Confirm API clients are sending Authorization header
- Check gateway/proxy configuration for header stripping
- API 클라이언트가 Authorization 헤더를 보내는지 확인한다.
- gateway·proxy가 헤더를 지우는지 설정을 확인한다.
## Escalation
## 에스컬레이션
- Escalate if widespread or affecting critical workflows
- 넓게 퍼졌거나 중요한 업무 흐름에 영향이 있으면 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [AUTH_TOKEN_EXPIRED, AUTH_KID_UNKNOWN, AUTH_JWKS_UNAVAILABLE, AUTH_
severity: P1
owner: oncall
last_updated: 2026-05-22
status: stub
status: 초안
---
# Runbook: JWT key rotation 시 인증 실패 spike
@@ -5,7 +5,7 @@ error_codes: [AUTHZ_INSUFFICIENT_PERMISSION, AUTHZ_TENANT_MISMATCH]
severity: P2
owner: oncall
last_updated: 2026-05-22
status: stub
status: 초안
---
# Runbook: cross-tenant 접근 시도 감지
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [AUTHZ_INSUFFICIENT_PERMISSION, FORBIDDEN]
severity: P3
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: AUTHZ_INSUFFICIENT_PERMISSION (`runbook://authz/insufficient-permission`)
## Symptoms
## 증상
- HTTP 403 with `error.code=AUTHZ_INSUFFICIENT_PERMISSION`
- Valid token but missing required role or permission
- HTTP 403, `error.code=AUTHZ_INSUFFICIENT_PERMISSION`.
- 토큰은 유효하지만 필요한 역할이나 권한이 없다.
## Diagnosis
## 진단
- Check user's assigned roles in IdP
- Review endpoint's required permission annotation
- IdP에서 사용자에게 준 역할을 확인한다.
- 엔드포인트가 요구하는 권한 애너테이션을 확인한다.
## Action
## 조치
- Grant correct role/permission to user
- Verify endpoint permission requirement is correct
- 사용자에게 맞는 역할·권한을 준다.
- 엔드포인트의 권한 요구가 맞는지 확인한다.
## Escalation
## 에스컬레이션
- Escalate to access-management team if bulk users affected
- 여러 사용자가 한꺼번에 영향을 받으면 접근 관리 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+16 -16
View File
@@ -4,33 +4,33 @@ category: AUTHZ
error_codes: [AUTHZ_TENANT_MISMATCH]
severity: P1
owner: oncall
last_updated: 2026-11-06
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: AUTHZ_TENANT_MISMATCH (`runbook://authz/tenant-mismatch`)
## Symptoms
## 증상
- HTTP 403 with `error.code=AUTHZ_TENANT_MISMATCH`
- The template does not emit this code; the service that decides cross-tenant access does. A 403
carrier is answered without a log line (`ServerFailureLog`), so that service logs
`code=AUTHZ_TENANT_MISMATCH` where it decides, if this runbook is to find the attempt
- HTTP 403, `error.code=AUTHZ_TENANT_MISMATCH`.
- 템플릿은 이 코드를 내지 않는다. 다른 테넌트 접근을 판단하는 서비스가 낸다. 403 carrier는 로그 줄 없이
응답하므로(`ServerFailureLog`), 이 runbook으로 시도를 찾으려면 그 서비스가 판단하는 자리에서
`code=AUTHZ_TENANT_MISMATCH`를 남겨야 한다.
## Diagnosis
## 진단
- Extract `traceId`, check `X-Tenant-Id` vs token tenant claim
- Determine if this is misconfigured client or intentional attack
- `traceId`를 뽑고, 요청의 테넌트 헤더(서비스가 정한 이름, 예: `X-Tenant-Id`)와 토큰의 테넌트 클레임을 비교한다.
- 클라이언트 설정 오류인지 의도한 공격인지 가린다.
## Action
## 조치
- Block repeat offenders at gateway level
- Alert security team for investigation
- 반복하는 호출자는 gateway에서 막는다.
- 보안 팀에 조사를 요청한다.
## Escalation
## 에스컬레이션
- P1 if confirmed malicious cross-tenant access attempt
- 악의적인 다른 테넌트 접근 시도로 확인되면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+15 -14
View File
@@ -4,31 +4,32 @@ category: TRANSIENT_DEPENDENCY
error_codes: [CACHE_STAMPEDE_LOCK_TIMEOUT]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: CACHE_STAMPEDE_LOCK_TIMEOUT (`runbook://cache/stampede-lock-timeout`)
## Symptoms
## 증상
- HTTP 503 with `error.code=CACHE_STAMPEDE_LOCK_TIMEOUT`
- Multiple concurrent cache misses on same key; lock contention
- HTTP 503, `error.code=CACHE_STAMPEDE_LOCK_TIMEOUT`.
- 같은 키에 캐시 miss가 동시에 몰리고 락 경합이 생긴다.
- 지금 템플릿은 이 코드를 내지 않는다. `docs/registries/error-codes.yaml`에 이 코드의 행이 없다. 이 runbook은 캐시가 이 코드를 내게 될 때를 위한 초안이다. Redis 장애는 [redis-capability-incident.md](redis-capability-incident.md)를 먼저 본다.
## Diagnosis
## 진단
- Check cache hit ratio metrics
- Identify cache keys with high miss rates
- 캐시 적중률 메트릭을 본다.
- miss 비율이 높은 캐시 키를 찾는다.
## Action
## 조치
- Verify stampede lock TTL is configured appropriately
- Pre-warm cache for high-traffic keys on startup
- 스탬피드 락 TTL이 알맞게 설정됐는지 확인한다.
- 트래픽이 많은 키는 기동할 때 캐시를 미리 채운다.
## Escalation
## 에스컬레이션
- Escalate if backend load spike accompanies stampede
- 스탬피드와 함께 백엔드 부하가 치솟으면 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+15 -14
View File
@@ -4,31 +4,32 @@ category: TRANSIENT_DEPENDENCY
error_codes: [CACHE_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: CACHE_UNAVAILABLE (`runbook://cache/unavailable`)
## Symptoms
## 증상
- HTTP 503 with `error.code=CACHE_UNAVAILABLE`
- Redis connection errors in logs
- HTTP 503, `error.code=CACHE_UNAVAILABLE`.
- 로그에 Redis 연결 오류가 있다.
- 지금 템플릿은 이 코드를 내지 않는다. `docs/registries/error-codes.yaml`에 이 코드의 행이 없다. 이 runbook은 캐시가 이 코드를 내게 될 때를 위한 초안이다. Redis 장애는 [redis-capability-incident.md](redis-capability-incident.md)를 먼저 본다.
## Diagnosis
## 진단
- Check Redis cluster health
- Verify network connectivity from app to Redis
- Redis 클러스터 상태를 본다.
- 앱에서 Redis까지 네트워크가 닿는지 확인한다.
## Action
## 조치
- Check Redis sentinel/cluster status
- Enable cache degradation path if configured for optional caches
- Redis sentinel·클러스터 상태를 확인한다.
- 선택 캐시에 degraded 경로(캐시 없이 원본에서 읽기)가 설정돼 있으면 켠다.
## Escalation
## 에스컬레이션
- P1 if required cache is down and no degradation path exists
- 필수 캐시가 내려갔고 degraded 경로가 없으면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DB_DEADLOCK]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DB_DEADLOCK (`runbook://db/deadlock`)
## Symptoms
## 증상
- HTTP 409 with `error.code=DB_DEADLOCK`
- SQLState 40P01 in Postgres logs
- HTTP 409, `error.code=DB_DEADLOCK`.
- Postgres 로그에 SQLState 40P01이 있다.
## Diagnosis
## 진단
- Check `pg_locks` and `pg_stat_activity` during deadlock
- Identify conflicting transaction lock order
- 교착이 생길 때 `pg_locks`와 `pg_stat_activity`를 본다.
- 충돌하는 트랜잭션의 락 순서를 찾는다.
## Action
## 조치
- Client should retry (retryable=true)
- Fix lock ordering in code if recurring
- 클라이언트는 다시 시도한다(retryable=true).
- 반복되면 코드의 락 순서를 고친다.
## Escalation
## 에스컬레이션
- Escalate to DBA if deadlock rate is sustained > 1% of transactions
- 교착 비율이 트랜잭션의 1%를 넘는 상태가 이어지면 DBA에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+16 -14
View File
@@ -4,31 +4,33 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DB_IDLE_IN_TX_TIMEOUT]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: DB_IDLE_IN_TX_TIMEOUT (`runbook://db/idle-in-tx-timeout`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DB_IDLE_IN_TX_TIMEOUT`
- SQLState 25P03; transaction held open too long without activity
- HTTP 503, `error.code=DB_IDLE_IN_TX_TIMEOUT`.
- SQLState 25P03. 트랜잭션이 아무 일 없이 너무 오래 열려 있었다.
## Diagnosis
## 진단
- Check `idle_in_transaction_session_timeout` Postgres setting
- Look for application-level long-running transaction holders
- Postgres의 `idle_in_transaction_session_timeout` 설정을 확인한다. 템플릿은 이 값을 설정하지 않는다.
DB나 역할에 걸린 값이다.
- 트랜잭션을 오래 쥐고 있는 애플리케이션 코드를 찾는다. 트랜잭션 안에서 외부 호출을 기다리는 코드가 흔한
원인이다.
## Action
## 조치
- Reduce transaction scope in application code
- Verify `spring.jpa.properties.hibernate.connection.timeout` is bounded
- 애플리케이션 코드에서 트랜잭션 범위를 줄인다.
- 트랜잭션 시간 상한(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`)이 정해져 있는지 확인한다.
## Escalation
## 에스컬레이션
- Escalate to DBA if connection pool exhaustion results
- 그 결과로 커넥션 풀이 바닥나면 DBA에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+16 -14
View File
@@ -4,31 +4,33 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DB_QUERY_CANCELED]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: DB_QUERY_CANCELED (`runbook://db/query-canceled`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DB_QUERY_CANCELED`
- SQLState 57014; query exceeds statement timeout
- HTTP 503, `error.code=DB_QUERY_CANCELED`.
- SQLState 57014. 쿼리가 문장 시간 상한을 넘었다.
## Diagnosis
## 진단
- Check `statement_timeout` in Postgres
- Identify slow queries in `pg_stat_statements`
- Postgres의 `statement_timeout`을 확인한다. 템플릿은 트랜잭션 시간 상한
(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`)의 남은 시간을 문장마다 넘기므로, 그 상한을
넘긴 문장도 이 코드로 끝난다.
- `pg_stat_statements`에서 느린 쿼리를 찾는다.
## Action
## 조치
- Optimize slow query or add index
- Adjust statement timeout if query is legitimately long
- 느린 쿼리를 고치거나 인덱스를 더한다.
- 정말 오래 걸려야 하는 쿼리면 시간 상한을 조정한다.
## Escalation
## 에스컬레이션
- Escalate to DBA for query optimization if recurring
- 반복되면 쿼리 최적화를 DBA에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DB_SERIALIZATION_FAILURE]
severity: P3
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DB_SERIALIZATION_FAILURE (`runbook://db/serialization-failure`)
## Symptoms
## 증상
- HTTP 409 with `error.code=DB_SERIALIZATION_FAILURE`
- SQLState 40001; high concurrent transaction contention
- HTTP 409, `error.code=DB_SERIALIZATION_FAILURE`.
- SQLState 40001. 동시 트랜잭션 경합이 심하다.
## Diagnosis
## 진단
- Check DB transaction isolation level
- Identify hot rows / hot tables under high concurrency
- DB 트랜잭션 격리 수준을 확인한다.
- 동시성이 높은 hot row·hot table을 찾는다.
## Action
## 조치
- Client should retry with exponential backoff (retryable=true)
- Optimize transaction scope if spike is sustained
- 클라이언트는 지수 백오프로 다시 시도한다(retryable=true).
- 급증이 이어지면 트랜잭션 범위를 줄인다.
## Escalation
## 에스컬레이션
- Escalate to DBA if sustained serialization failure rate > 5%
- 직렬화 실패 비율이 5%를 넘는 상태가 이어지면 DBA에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DB_UNAVAILABLE]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DB_UNAVAILABLE (`runbook://db/unavailable`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DB_UNAVAILABLE`
- SQLState 08* connection errors in logs
- HTTP 503, `error.code=DB_UNAVAILABLE`.
- 로그에 SQLState 08* 연결 오류가 있다.
## Diagnosis
## 진단
- Check DB server health and connection pool exhaustion
- Review network connectivity from app pods to DB
- DB 서버 상태와 커넥션 풀 고갈을 확인한다.
- 앱 pod에서 DB까지 네트워크가 닿는지 확인한다.
## Action
## 조치
- Check DB primary health; failover to replica if available
- Drain connection pool and reconnect
- DB primary 상태를 확인한다. replica가 있으면 failover한다.
- 커넥션 풀을 비우고 다시 연결한다.
## Escalation
## 에스컬레이션
- P1: immediate if DB primary is down
- P1: DB primary가 내려갔으면 즉시.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DEPENDENCY_4XX_CLIENT]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DEPENDENCY_4XX_CLIENT (`runbook://dependency/4xx-client`)
## Symptoms
## 증상
- HTTP 502 with `error.code=DEPENDENCY_4XX_CLIENT`
- Upstream returned 401/403/400 — credential, scope, or request format issue
- HTTP 502, `error.code=DEPENDENCY_4XX_CLIENT`.
- 업스트림이 401·403·400을 돌려줬다. 자격 증명, scope, 요청 형식 문제다.
## Diagnosis
## 진단
- Check upstream response body in logs for error detail
- Verify API credentials and scopes are valid
- 로그에서 업스트림 응답 본문의 오류 내용을 본다.
- API 자격 증명과 scope가 유효한지 확인한다.
## Action
## 조치
- Rotate credentials if expired
- Fix request format if API contract changed
- 자격 증명이 만료됐으면 교체한다.
- API 계약이 바뀌었으면 요청 형식을 고친다.
## Escalation
## 에스컬레이션
- Escalate to upstream API owner if contract change is suspected
- 계약 변경이 의심되면 업스트림 API 소유자에게 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DEPENDENCY_5XX_SERVER]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DEPENDENCY_5XX_SERVER (`runbook://dependency/5xx-server`)
## Symptoms
## 증상
- HTTP 502 with `error.code=DEPENDENCY_5XX_SERVER`
- Upstream returned 5xx; transient server-side failure
- HTTP 502, `error.code=DEPENDENCY_5XX_SERVER`.
- 업스트림이 5xx를 돌려줬다. 서버 쪽 일시 장애다.
## Diagnosis
## 진단
- Check `dependency_name` tag for which upstream is failing
- Review upstream service status page
- `dependency_name` 태그로 어느 업스트림이 실패하는지 본다.
- 업스트림 서비스의 상태 페이지를 본다.
## Action
## 조치
- Client should retry (retryable=true)
- Monitor upstream recovery
- 클라이언트는 다시 시도한다(retryable=true).
- 업스트림 회복을 지켜본다.
## Escalation
## 에스컬레이션
- P1 if critical upstream is in sustained 5xx state
- 중요한 업스트림이 5xx 상태로 계속 머물면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DEPENDENCY_CIRCUIT_OPEN]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DEPENDENCY_CIRCUIT_OPEN (`runbook://dependency/circuit-open`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DEPENDENCY_CIRCUIT_OPEN`
- Circuit breaker (Resilience4j) in OPEN state for a dependency
- HTTP 503, `error.code=DEPENDENCY_CIRCUIT_OPEN`.
- 어떤 의존성의 circuit breaker(Resilience4j)가 OPEN 상태다.
## Diagnosis
## 진단
- Check Resilience4j circuit breaker metrics for the dependency
- Check upstream health; circuit opens after failure threshold breached
- 그 의존성의 Resilience4j circuit breaker 메트릭을 본다.
- 업스트림 상태를 확인한다. 실패가 임계를 넘으면 circuit이 열린다.
## Action
## 조치
- Wait for circuit half-open probe (automatic after wait duration)
- Resolve upstream issue to allow circuit to close
- circuit의 half-open 시험을 기다린다(대기 시간이 지나면 자동으로 한다).
- 업스트림 문제를 풀어 circuit이 닫히게 한다.
## Escalation
## 에스컬레이션
- P1 if circuit remains open > 5 minutes on a critical dependency
- 중요한 의존성의 circuit이 5분 넘게 열려 있으면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DEPENDENCY_CONNECT_FAILED]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DEPENDENCY_CONNECT_FAILED (`runbook://dependency/connect-failed`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DEPENDENCY_CONNECT_FAILED`
- TCP connection refused or network unreachable to upstream
- HTTP 503, `error.code=DEPENDENCY_CONNECT_FAILED`.
- 업스트림으로 TCP 연결이 거부됐거나 네트워크에 닿지 않는다.
## Diagnosis
## 진단
- Check `dependency_name` tag for which upstream is unreachable
- Verify network path and firewall rules
- `dependency_name` 태그로 어느 업스트림에 닿지 않는지 본다.
- 네트워크 경로와 방화벽 규칙을 확인한다.
## Action
## 조치
- Check upstream service availability
- Verify service discovery / DNS resolution
- 업스트림 서비스가 살아 있는지 확인한다.
- service discovery와 DNS 조회를 확인한다.
## Escalation
## 에스컬레이션
- P1 if upstream is a critical service dependency
- 업스트림이 중요한 서비스 의존성이면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [DEPENDENCY_DNS_FAILED]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: DEPENDENCY_DNS_FAILED (`runbook://dependency/dns-failed`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DEPENDENCY_DNS_FAILED`
- DNS resolution failure for upstream hostname
- HTTP 503, `error.code=DEPENDENCY_DNS_FAILED`.
- 업스트림 호스트 이름의 DNS 조회가 실패했다.
## Diagnosis
## 진단
- Test DNS resolution from app pod: `nslookup <upstream-host>`
- Check cluster DNS (CoreDNS) health
- 앱 pod에서 DNS 조회를 시험한다: `nslookup <upstream-host>`
- 클러스터 DNS(CoreDNS) 상태를 확인한다.
## Action
## 조치
- Verify upstream hostname configuration
- Check CoreDNS / cluster DNS health
- 업스트림 호스트 이름 설정을 확인한다.
- CoreDNS·클러스터 DNS 상태를 확인한다.
## Escalation
## 에스컬레이션
- P1 if cluster DNS is degraded
- 클러스터 DNS가 나빠졌으면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+15 -14
View File
@@ -4,31 +4,32 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DEPENDENCY_TIMEOUT]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: DEPENDENCY_TIMEOUT (`runbook://dependency/timeout`)
## Symptoms
## 증상
- HTTP 504 with `error.code=DEPENDENCY_TIMEOUT`
- Upstream service did not respond within configured timeout (default: global 10s)
- HTTP 504, `error.code=DEPENDENCY_TIMEOUT`.
- 업스트림 서비스가 설정된 시간 안에 답하지 않았다. 호출 전체의 상한은 HTTP 클라이언트 profile의
`timeout.total-call`이다(기본값은 `docs/httpclient/configuration-reference.md`).
## Diagnosis
## 진단
- Check `dependency_name` in log for which upstream is timing out
- Review upstream service latency metrics
- 로그의 `dependency_name`으로 어느 업스트림이 시간을 넘기는지 본다.
- 업스트림 서비스의 지연 메트릭을 본다.
## Action
## 조치
- Check upstream service health
- Verify timeout settings match SLA expectations
- 업스트림 서비스 상태를 확인한다.
- 시간 상한 설정이 SLA 기대와 맞는지 확인한다.
## Escalation
## 에스컬레이션
- P1 if critical upstream is timing out at scale
- 중요한 업스트림이 대규모로 시간을 넘기면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAIL
severity: P1
owner: oncall
last_updated: 2026-05-22
status: stub
status: 초안
---
# Runbook: 외부 의존성 unavailable
@@ -4,31 +4,33 @@ category: TRANSIENT_DEPENDENCY
error_codes: [DOWNLOAD_STREAMING_FAILURE]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: DOWNLOAD_STREAMING_FAILURE (`runbook://file/download-streaming-failure`)
## Symptoms
## 증상
- HTTP 503 with `error.code=DOWNLOAD_STREAMING_FAILURE`
- Streaming response truncated; backpressure or timeout (60s / 100MB limit)
- HTTP 503, `error.code=DOWNLOAD_STREAMING_FAILURE`.
- 스트리밍 응답이 잘렸다. backpressure나 시간 초과(60초 / 100MB 한도)다.
- 지금 템플릿은 이 코드를 내지 않는다. `docs/registries/error-codes.yaml`에 이 코드의 행이 없다. 파일 서버
다운로드 장애는 [`docs/fileserver/operations.md`](../fileserver/operations.md)를 먼저 본다.
## Diagnosis
## 진단
- Check streaming response timeout configuration
- Review download size vs 100MB limit
- 스트리밍 응답 시간 상한 설정을 확인한다.
- 다운로드 크기를 100MB 한도와 비교한다.
## Action
## 조치
- Verify storage backend is reachable
- Check for network congestion on download path
- 저장소 백엔드에 닿는지 확인한다.
- 다운로드 경로의 네트워크 혼잡을 확인한다.
## Escalation
## 에스컬레이션
- Escalate to infra if storage backend is degraded
- 저장소 백엔드가 나빠졌으면 인프라 팀에 넘긴다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+49 -55
View File
@@ -1,94 +1,88 @@
# Runbook: gRPC advanced capabilities
Scope: the `:grpc-advanced:*` family. Everything here is off by default and stays off until a
deployment names it. Nothing in this family ships in a runtime composition today.
범위: `:grpc-advanced:*` family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로
있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다.
Flags are `app.grpc.advanced.<capability>.enabled`. `GrpcAdvancedCapability` owns the list of
capability names; `GrpcAdvancedSupportMatrix` owns their current grades.
스위치는 `app.grpc.advanced.<capability>.enabled`다. capability 이름 목록과 기본 등급은
`GrpcAdvancedCapability`(`defaultGrade()`)가 가진다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로
등급을 바꾼다.
---
## A capability refuses to start
## capability가 뜨기를 거부한다
`GrpcAdvancedModuleGuard` gives three different refusals, and the remedy differs:
`GrpcAdvancedModuleGuard`는 세 가지로 거부하고, 고치는 법이 다르다.
| Message contains | Meaning | Remedy |
| 메시지에 있는 말 | 뜻 | 고치는 법 |
| --- | --- | --- |
| "its feature flag is not set" | Nobody enabled it | Set the property named in the message |
| "tracked rather than implemented" | Grade is `WATCH` | Nothing to do here; the capability is not implemented |
| "uncharacterised failure modes" | Grade is `EXPERIMENTAL` and this is production | Record a production approval, or run it outside production |
| "its feature flag is not set" | 아무도 켜지 않았다 | 메시지가 이름 댄 속성을 설정한다 |
| "tracked rather than implemented" | 등급이 `WATCH`다 | 여기서 할 일은 없다. 그 capability는 구현되지 않았다 |
| "uncharacterised failure modes" | 등급이 `EXPERIMENTAL`이고 여기는 운영이다 | 운영 승인을 기록하거나, 운영 밖에서 돌린다 |
The refusal message always names the property key, so the first case is a configuration line rather
than a support question.
거부 메시지는 늘 속성 키를 이름 댄다. 그래서 첫 경우는 지원 문의가 아니라 설정 한 줄이다.
---
## xDS: the control plane went away
## xDS: control plane이 사라졌다
**What you are seeing.** The control plane is unreachable and clients are still routing.
**보이는 것.** control plane에 닿지 않는데 클라이언트는 아직 라우팅한다.
**What it means.** `GrpcXdsFailurePolicy` serves the last-known-good snapshot, up to its staleness
bound.
**뜻.** `GrpcXdsFailurePolicy`가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다.
**What to do.**
**할 일.**
1. Check the snapshot's age. `SERVE_LAST_KNOWN_GOOD` is the healthy degraded state.
2. `STALE_BEYOND_BOUND` means the snapshot is older than the policy allows and is no longer trusted.
Beyond that bound, a decommissioned backend would otherwise keep receiving traffic indefinitely.
3. `NO_SNAPSHOT_YET` on a starting instance means it never reached the control plane. It fails after
the initial fetch timeout rather than starting with no routing.
1. snapshot의 나이를 본다. `SERVE_LAST_KNOWN_GOOD`는 정상적인 degraded 상태다.
2. `STALE_BEYOND_BOUND`는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이
없으면 내린 backend가 트래픽을 끝없이 받는다.
3. 뜨는 인스턴스의 `NO_SNAPSHOT_YET`은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫
fetch 시간 상한이 지나면 실패한다.
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsProfile` refuses an
`APPLICATION` retry owner, because retry defined in two places has a winner that depends on
resolution order rather than on a decision.
xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하지 않는다**. `GrpcXdsProfile`이 `APPLICATION` 재시도
소유자를 거부한다. 두 곳에 정의한 재시도는 결정이 아니라 해석 순서가 이기는 쪽을 정하기 때문이다.
---
## gRPC-Web: a browser call hangs and then fails with no status
## gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다
**Almost always the proxy.** A gRPC status arrives as a trailer, and a browser cannot read a trailer
the proxy did not expose. Check that the proxy's CORS `expose_headers` includes `grpc-status` and
`grpc-message`; `GrpcWebProxyContract.violations` reports exactly this, and the reference
configuration in `envoy/envoy.yaml` shows it in place.
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
`src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
**If the method is client- or bidirectional-streaming**, it cannot work over gRPC-Web at all — a
browser has no way to send a stream of messages. `GrpcWebRpcSupport.require` refuses such a method.
**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
---
## Servlet: a transport setting appears to be ignored
## Servlet: 전송 설정이 무시되는 것 같다
It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and
flow-control window tuning belong to it. This repository has no Servlet transport code that would
refuse them, so configure them on the container.
무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의
몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다.
A Servlet run never substitutes for Netty certification.
Servlet 실행은 Netty 인증을 대신하지 않는다.
---
## Hedging: backend load doubled
## Hedging: backend 부하가 두 배가 됐다
**Expected, within a bound.** Hedging trades duplicate load for tail latency.
`GrpcHedgingResult` records both `duplicateBackendCalls` and `cancelledLoserAttempts`; a dashboard
showing only the latency improvement makes the trade look free.
**상한 안이면 예상한 일이다.** hedging은 중복 부하를 내고 꼬리 지연을 줄인다. `GrpcHedgingResult`는
`duplicateBackendCalls`와 `cancelledLoserAttempts`를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을
공짜처럼 보이게 한다.
**What to check.** `GrpcHedgingBudget` caps hedges as a fraction of completed calls. If duplicate
load is above that fraction, the budget is not being consumed — which means something is issuing
hedges outside the coordinator.
**확인할 것.** `GrpcHedgingBudget`은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이
쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다.
**Hedging is refused** for anything but a read-only unary method. A hedged mutation runs twice by
design, and an idempotency key does not help: the second attempt duplicates a success in progress
rather than retrying a failure.
읽기 전용 unary 메서드가 아니면 **hedging을 거부한다**. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다.
두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다.
---
## Promoting a capability
## capability 승격
Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence,
performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable
default needs thirty. Promotions are independent: promoting one capability changes no other's
grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was
removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it.
`ADVANCED_STABLE`로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일
soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은
바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 `GrpcAdvancedPromotionGate`는 자기 테스트
말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4).
Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy,
container, control plane or toolchain). A suite that ran without it passed and established nothing.
어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고
돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다.
+101 -120
View File
@@ -1,179 +1,160 @@
# Runbook: gRPC platform operations
Scope: the `:grpc:*` family. All of it is build-only today — every leaf's `runtime_memberships` is
empty — so nothing here fires in production yet. It is written now because the states it covers are
the ones an on-call cannot work out from first principles at three in the morning, and shipping the
behaviour before the runbook means the first person to meet one is doing that.
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"`
(주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
Configuration lives under `app.grpc.platform.*` and is bound by `GrpcPlatformProperties`.
The platform does not start unless `app.grpc.platform.enabled=true`.
설정은 `app.grpc.platform.*` 아래에 있고 `GrpcPlatformProperties`가 묶는다. 플랫폼은
`app.grpc.platform.enabled=true`가 아니면 뜨지 않는다.
---
## COMPLETION_UNKNOWN on a mutation
## 상태를 바꾸는 호출의 COMPLETION_UNKNOWN
**What you are seeing.** A client received `DEADLINE_EXCEEDED`, `UNAVAILABLE` or `INTERNAL` on a
state-changing call, and the response trailer `completion-outcome` reads `COMPLETION_UNKNOWN`.
**보이는 것.** 클라이언트가 상태를 바꾸는 호출에서 `DEADLINE_EXCEEDED`, `UNAVAILABLE`, `INTERNAL`을 받았고, 응답
trailer `completion-outcome`이 `COMPLETION_UNKNOWN`이다.
**What it means.** The server may have committed. This is not a failure and not a success; the status
code cannot distinguish them, which is why the outcome is carried separately.
**뜻.** 서버가 커밋했을 수 있다. 실패도 성공도 아니다. 상태 코드로는 둘을 가릴 수 없어서 결과를 따로 싣는다.
**What not to do.** Do not re-issue the call. Do not tell the caller it failed. Both are wrong half
the time, and which half is not knowable from the status.
**하지 말 것.** 호출을 다시 보내지 않는다. 호출자에게 실패했다고 말하지 않는다. 둘 다 절반은 틀리고, 어느 절반인지
상태 코드로는 알 수 없다.
**What to do.**
**할 일.**
1. Take the `error-execution-id` from the trailers. It is the only link between what the client saw
and what the server did.
2. If the method is `IDEMPOTENCY_KEY_REQUIRED`, query the operation ledger with the caller
fingerprint, the full method name and the caller's key. `GrpcOperationStatusQuery` returns one of
`IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND` or `UNKNOWN`.
3. `COMMITTED` means return the stored outcome reference, not a freshly computed answer — the resource
may have changed since, and a new answer would describe the state at reconciliation time rather
than the state the caller's own call produced.
4. `NOT_FOUND` means the operation never started and is safe to re-issue. `FAILED_TERMINAL` means the
same.
5. `UNKNOWN` means the ledger could not be consulted. Nothing may be concluded. The case is queued by
`GrpcCompletionReconciler` and retried later.
6. If the method is not keyed, there is no ledger row. Resolve it against the business resource, or
escalate to the service owner. This is the case the keyed profile exists to avoid.
1. trailer에서 `error-execution-id`를 꺼낸다. 클라이언트가 본 것과 서버가 한 것을 잇는 유일한 고리다.
2. 메서드가 `IDEMPOTENCY_KEY_REQUIRED`면 호출자 fingerprint, 전체 메서드 이름, 호출자의 키로 operation ledger를
조회한다. `GrpcOperationStatusQuery`는 `IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND`, `UNKNOWN`
중 하나를 돌려준다.
3. `COMMITTED`면 새로 계산한 답이 아니라 저장된 결과 참조를 돌려준다. 그 뒤에 자원이 바뀌었을 수 있고, 새 답은
호출자 자신의 호출이 만든 상태가 아니라 맞춰 보는 시점의 상태를 설명한다.
4. `NOT_FOUND`는 operation이 시작하지 않았다는 뜻이라 다시 보내도 안전하다. `FAILED_TERMINAL`도 같다.
5. `UNKNOWN`은 ledger를 조회하지 못했다는 뜻이다. 아무것도 결론 낼 수 없다. `GrpcCompletionReconciler`가 그
건을 대기열에 넣고 나중에 다시 시도한다.
6. 메서드에 키가 없으면 ledger 행이 없다. 업무 자원으로 맞춰 보거나 서비스 소유자에게 넘긴다. 키 있는 profile은
이 경우를 피하려고 있다.
7. `IN_PROGRESS` means a claim exists and has not finished. If its owner died, the claim is not
stuck forever: once it is older than the claim TTL (`app.grpc.platform.operation-ledger-claim-ttl`,
default 5m), the next retry of the same request takes it over and runs again,
and a later reconciler pass sees that attempt's `COMMITTED` or `FAILED_TERMINAL`. Until a retry
arrives, the case stays pending. The re-run is safe only when the ledger commit is recorded in the
mutation's own transaction; if this service commits them separately, check the business resource
before letting the retry through. An owner that was only slow cannot spoil the takeover: its claim
attempt (`claim_attempt`) is behind, so its late commit is refused and its late failure ignored.
A log line saying an operation "is no longer held by attempt N" is that refusal, not an outage.
7. `IN_PROGRESS`는 claim이 있고 끝나지 않았다는 뜻이다. 그 소유자가 죽었어도 claim이 영원히 묶이지는 않는다.
claim TTL(`app.grpc.platform.operation-ledger-claim-ttl`, 기본 5m)보다 오래되면, 같은 요청의 다음 재시도가
그것을 넘겨받아 다시 돌리고, 뒤의 reconciler 단계가 그 시도의 `COMMITTED`나 `FAILED_TERMINAL`을 본다.
재시도가 오기 전까지 그 건은 대기로 남는다. 다시 돌리는 것은 ledger 커밋이 변경 자신의 트랜잭션 안에서 기록될
때만 안전하다. 이 서비스가 둘을 따로 커밋하면 재시도를 들이기 전에 업무 자원을 확인한다. 느리기만 했던
소유자는 넘겨받기를 망치지 못한다. 그 claim 시도(`claim_attempt`)가 뒤처졌으므로 늦은 커밋은 거부되고 늦은
실패는 무시된다. operation이 "is no longer held by attempt N"이라는 로그 줄이 그 거부다. 장애가 아니다.
**Escalate when** the reconciler's pending list grows across passes. That means the ledger is
unreachable rather than slow. A case pending as `IN_PROGRESS` for longer than the claim TTL with no
retry arriving is a caller that gave up; it needs the business resource checked, not a ledger fix.
**넘길 때는** reconciler의 대기 목록이 단계를 거듭하며 커질 때다. ledger가 느린 게 아니라 닿지 않는다는 뜻이다.
claim TTL보다 오래 `IN_PROGRESS`로 대기 중인데 재시도가 오지 않는 건은 호출자가 포기한 것이다. ledger를 고칠 일이
아니라 업무 자원을 확인할 일이다.
---
## The operation ledger table keeps growing
## operation ledger 테이블이 계속 커진다
**What you are seeing.** `grpc_operation_ledger` grows without bound, or a retry of an old key runs
the mutation again instead of replaying.
**보이는 것.** `grpc_operation_ledger`가 끝없이 커지거나, 오래된 키의 재시도가 replay 대신 변경을 다시 돌린다.
**What it means.** Finished rows (`COMMITTED`, `FAILED_TERMINAL`) are deleted only when something
calls `GrpcOperationLedgerRetention.purgeExpired(now)`; the starter assembles that bean
(`app.grpc.platform.operation-ledger-enabled=true`) but does not schedule it. A growing table means
the service's scheduler is not calling it. A retry that re-ran after the retention
(`app.grpc.platform.operation-ledger-retention`, default 24h) is the trade the retention makes: its
record was purged, so it was a new operation.
**뜻.** 끝난 행(`COMMITTED`, `FAILED_TERMINAL`)은 누군가 `GrpcOperationLedgerRetention.purgeExpired(now)`를 불러야만
지워진다. starter는 그 bean을 조립하지만(`app.grpc.platform.operation-ledger-enabled=true`) 일정을 걸지는 않는다.
테이블이 커지면 서비스의 scheduler가 그것을 부르지 않는 것이다. 보존 기간
(`app.grpc.platform.operation-ledger-retention`, 기본 24h)이 지난 뒤 다시 돈 재시도는 보존 기간이 감수하는
교환이다. 기록이 지워졌으므로 새 operation이었다.
**What to do.**
**할 일.**
1. Check that the service schedules `purgeExpired`. Each call deletes in batches of 500 until a batch
comes back short, never touching `IN_PROGRESS` rows.
2. For a large backlog, call it repeatedly; each batch is a short transaction that skips rows another
transaction holds.
3. If retried keys re-run after the retention, raise the retention above the callers' retry window
rather than skipping the purge.
1. 서비스가 `purgeExpired`에 일정을 걸었는지 확인한다. 한 번 부르면 500행씩 지우다가 덜 찬 묶음이 나오면 멈추고,
`IN_PROGRESS` 행은 건드리지 않는다.
2. 밀린 양이 많으면 여러 번 부른다. 묶음마다 짧은 트랜잭션이고, 다른 트랜잭션이 쥔 행은 건너뛴다.
3. 다시 보낸 키가 보존 기간 뒤에 다시 돌면, purge를 건너뛰지 말고 보존 기간을 호출자의 재시도 창보다 길게 한다.
**Escalate when** old `IN_PROGRESS` rows accumulate. Those are not purged by design; each is an
abandoned claim no retry has taken over (see `IN_PROGRESS` above).
**넘길 때는** 오래된 `IN_PROGRESS` 행이 쌓일 때다. 그 행은 설계상 지워지지 않는다. 하나하나가 어느 재시도도
넘겨받지 않은 버려진 claim이다(위의 `IN_PROGRESS`).
---
## A stream ended with FULL_RESYNC_REQUIRED
## stream이 FULL_RESYNC_REQUIRED로 끝났다
**What you are seeing.** A client's resume was refused and it was told to resynchronise.
**보이는 것.** 클라이언트의 resume이 거부되고 다시 동기화하라는 답을 받았다.
**What it means.** The server can no longer replay from the client's cursor. Either the snapshot
version moved, or the cursor predates retained history.
**뜻.** 서버가 클라이언트의 cursor부터 더는 replay할 수 없다. snapshot 버전이 움직였거나, cursor가 보존된 이력보다
앞선다.
**What to do.** Nothing on the server. The client is expected to discard its position and start a new
stream from a fresh snapshot. A client that instead retries the same token will keep receiving the
same answer.
**할 일.** 서버에서는 없다. 클라이언트가 자기 위치를 버리고 새 snapshot에서 새 stream을 시작해야 한다. 대신 같은
token으로 다시 시도하는 클라이언트는 같은 답을 계속 받는다.
**Escalate when** it is happening to many clients at once. That usually means history retention was
reduced, or snapshots are rotating faster than clients reconnect.
**넘길 때는** 많은 클라이언트에 한꺼번에 일어날 때다. 보통 이력 보존이 줄었거나, 클라이언트가 다시 붙는 것보다
snapshot이 빨리 돈다는 뜻이다.
---
## A stream ended with SLOW_CONSUMER
## stream이 SLOW_CONSUMER로 끝났다
**What you are seeing.** Streams terminating with `SLOW_CONSUMER`, and
`grpc.stream.flow_control_stalls` rising.
**보이는 것.** stream이 `SLOW_CONSUMER`로 끝나고 `grpc.stream.flow_control_stalls`가 오른다.
**What it means.** The consumer could not keep up with the bounded queue. The stream was terminated
rather than silently dropping messages, because a client cannot detect drops — the sequence numbers
it sees are the ones it was sent.
**뜻.** 소비자가 상한 있는 큐를 따라가지 못했다. 메시지를 조용히 버리는 대신 stream을 끝냈다. 클라이언트는 버려진
것을 알아챌 수 없다. 클라이언트가 보는 순번은 보내진 것뿐이다.
**What to do.**
**할 일.**
1. Check whether the consumer is slow or the producer is fast. `grpc.stream.messages` against
`grpc.stream.lifetime` tells you the rate.
2. If the consumer is slow, the fix is on the consumer. Raising the queue bound moves the failure
later and makes it larger.
3. A resume is not available after this ending: the messages that overflowed the queue are gone, so
continuing from the last delivered sequence would silently skip them. The client resynchronises.
1. 소비자가 느린지 생산자가 빠른지 확인한다. `grpc.stream.messages`를 `grpc.stream.lifetime`과 견주면 속도가
나온다.
2. 소비자가 느리면 고칠 곳은 소비자다. 큐 상한을 올리면 실패가 뒤로 밀리고 커질 뿐이다.
3. 이렇게 끝난 뒤에는 resume을 쓸 수 없다. 큐를 넘친 메시지는 사라졌으므로, 마지막으로 전달한 순번부터 이어 가면
그것을 조용히 건너뛴다. 클라이언트는 다시 동기화한다.
---
## RESOURCE_EXHAUSTED under load
## 부하에서 RESOURCE_EXHAUSTED
**What you are seeing.** Calls refused with `RESOURCE_EXHAUSTED` and `GrpcAdmissionController`
reporting rejections.
**보이는 것.** 호출이 `RESOURCE_EXHAUSTED`로 거부되고 `GrpcAdmissionController`가 거부를 보고한다.
**What it means.** The server is at its concurrency and queue bounds and is shedding rather than
queueing. This is the designed behaviour: accepting work whose callers have already given up spends
capacity on nothing.
**뜻.** 서버가 동시성과 큐 상한에 닿아서 줄을 세우지 않고 덜어 낸다. 설계한 동작이다. 호출자가 이미 포기한 일을
받으면 아무것도 아닌 데 용량을 쓴다.
**What to do.**
**할 일.**
1. Read `grpc.rpc.duration` and `grpc.rpc.queue_wait` separately. Queue time rising with duration flat
means the bottleneck is admission, not the work.
2. Check which saturation counter is moving — executor, channel or flow control. They look identical
in a latency graph and have different fixes.
3. Raising `app.grpc.platform.executor-queue-capacity` defers the problem; it does not remove
it. `GrpcExecutorProfile` refuses a queue above ten thousand for that reason.
1. `grpc.rpc.duration`과 `grpc.rpc.queue_wait`를 따로 읽는다. duration은 그대로인데 큐 시간이 오르면 병목은 일이
아니라 admission이다.
2. 어느 포화 counter가 움직이는지 확인한다. executor, channel, flow control이다. 지연 그래프에서는 똑같이 보이지만
고치는 법이 다르다.
3. `app.grpc.platform.executor-queue-capacity`를 올리면 문제를 미룰 뿐 없애지 않는다. 그래서 `GrpcExecutorProfile`이
1만이 넘는 큐를 거부한다.
---
## A rollout is producing errors at every deploy
## 배포할 때마다 rollout이 오류를 낸다
**What you are seeing.** A burst of `UNAVAILABLE` or `CANCELLED` each time an instance goes away.
**보이는 것.** 인스턴스가 빠질 때마다 `UNAVAILABLE`이나 `CANCELLED`가 몰린다.
**What it means.** The drain sequence is not completing, or is running out of order.
**뜻.** drain 순서가 끝나지 않거나, 순서가 어긋나서 돈다.
**What to do.**
**할 일.**
1. `GrpcDrainResult` records what each drain achieved: completed and cancelled unary calls, signalled
and cancelled streams, and which phases ran. A drain that routinely force-cancels is the cause.
2. The order matters. Readiness flips first and nothing is refused during that window, because there
is a gap between an instance reporting unready and routing acting on it. Refusing during that gap
turns a clean rollout into a burst of errors at every deploy.
3. For long streams, check the Kubernetes profile's `streamReconnectBudget` and
`readinessDrainGrace`. A stream is pinned to one pod for its whole life, so every rollout ends it;
a profile with long streams and no reconnect budget has not decided what clients do next.
1. `GrpcDrainResult`가 각 drain이 해낸 것을 기록한다. 끝난 unary 호출과 취소된 unary 호출, 신호를 받은 stream과
취소된 stream, 돈 단계다. 늘 강제 취소하는 drain이 원인이다.
2. 순서가 중요하다. readiness가 먼저 뒤집히고, 그 사이에는 아무것도 거부하지 않는다. 인스턴스가 unready를 보고한
뒤 라우팅이 그것을 따르기까지 틈이 있기 때문이다. 그 틈에 거부하면 깨끗한 rollout이 배포마다 오류 묶음이 된다.
3. 긴 stream이면 Kubernetes profile의 `streamReconnectBudget`과 `readinessDrainGrace`를 확인한다. stream은 일생
내내 한 pod에 묶이므로 rollout마다 끝난다. 긴 stream이 있는데 다시 붙는 예산이 없는 profile은 클라이언트가 다음에
할 일을 정하지 않은 것이다.
---
## Verifying a deployment's configuration
## 배포의 설정 확인
`GrpcPlatformSnapshotService` produces a secret-free snapshot for a caller on the admin network
holding an admin role. Both gates are required.
`GrpcPlatformSnapshotService`는 관리 네트워크에 있고 관리 역할을 가진 호출자에게 secret 없는 snapshot을 만든다.
두 관문이 모두 필요하다.
`GrpcPlatformSnapshotService.driftAgainstRelease` compares a running snapshot with the release
manifest and reports schema version, method policy hash and per-channel profile differences. An
instance running a configuration the release did not ship is behind a whole class of incidents that
are otherwise diagnosed by reading logs.
`GrpcPlatformSnapshotService.driftAgainstRelease`는 실행 중인 snapshot을 릴리스 manifest와 비교해 스키마 버전,
메서드 정책 해시, channel별 profile 차이를 보고한다. 릴리스가 내보내지 않은 설정으로 도는 인스턴스는, 그렇지 않으면
로그를 읽어야만 진단되는 장애 한 부류의 원인이다.
The snapshot carries hashes and names only. A field whose name looks like a credential is refused at
construction rather than redacted.
snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이름의 칸은 가리지 않고 만들 때 거부한다.
---
## Things that are deliberately off
## 일부러 꺼 둔 것
- **Reflection in production.** `GrpcReflectionMode.defaultFor` returns `DISABLED` for `STAGE` and
`PROD`. Reflection publishes the whole schema to anyone who can open a connection.
- **Every advanced capability.** See `docs/runbooks/grpc-advanced-capabilities.md`.
- **The platform itself.** `app.grpc.platform.enabled` defaults to false, and every `:grpc:*`
leaf is build-only in the registry.
- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는
`"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.
+95 -111
View File
@@ -4,68 +4,58 @@ category: TRANSIENT_DEPENDENCY
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
severity: P2
owner: oncall
last_updated: 2026-11-05
status: active
last_updated: 2026-11-07
status: 운영
---
# Runbook: IDEMPOTENCY_UNAVAILABLE (`runbook://idempotency/unavailable`)
## Symptoms
## 증상
- HTTP 503 (`error.code=IDEMPOTENCY_UNAVAILABLE`, `retryable=true`) on endpoints that take an
`Idempotency-Key`; the same code on the gRPC `error-code` trailer (`UNAVAILABLE`).
- `IdempotencyExecutor` refused to run the action because the replay store (JPA or Redis, whichever
`app.idempotency` selects) did not answer. Nothing was executed: the refusal happens before the
action, so a client retry is safe.
- The same 503 when the store refused to start a claim whose processing lease had already run out
— the request spent longer than the lease between its claim and the start of its action (a
stalled process, a slow store call). The ERROR line, `failure classified as
IDEMPOTENCY_UNAVAILABLE (…)`, has the exception attached, and the exception's message reads `the
claim's processing lease ran out before the action started; nothing ran: <scope>` — in prod JSON
logs that is in `stack_trace`, not `message`. The store may be healthy.
Nothing ran here either, and the next request with the key takes the claim over and runs it.
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` (`retryable=true`) is the same outage hitting after the
action ran: the store did not answer while the result was being recorded. When the use case called
the executor inside its write transaction, that transaction's database writes rolled back with the
exception; an action that committed a transaction of its own kept its writes, and anything outside
a transaction (an outbound call, a message) may have happened. This is not "nothing was executed".
Clients resend with the same key.
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED` (`retryable=false`) means the opposite case: the store
cannot tell whether an earlier attempt's effect already happened. Two records produce it:
- `ABANDONED`: the action threw, or reported its effect unknown. Final until the record expires.
- `EXECUTING` past its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s): the attempt
crashed, or is still running longer than the lease. The executor never renews the lease, so a
slow but healthy request lands here too. The server never runs it again and does not touch the
record. If the attempt is still running and finishes, its result is recorded, the first request
gets its normal answer, and later requests with the key get that result replayed; a failure it
reports is recorded the same way. So this 500 can stop on its own (owner decision 2026-11-04).
This is the Redis store's case. The PostgreSQL store, called inside the use case's write
transaction as the template calls it, never shows another request an unfinished record: that
request waits for the first transaction to end, and gets the replay if it committed or a fresh
run if it rolled back (`docs/web/http-contract.md` §2).
- `Idempotency-Key`를 받는 엔드포인트에서 HTTP 503(`error.code=IDEMPOTENCY_UNAVAILABLE`, `retryable=true`).
gRPC는 `error-code` trailer에 같은 코드가 온다(`UNAVAILABLE`).
- replay 저장소(`app.idempotency`가 고른 JPA나 Redis)가 답하지 않아서 `IdempotencyExecutor`가 action 실행을
거절했다. 아무것도 실행되지 않았다. 거절은 action 전에 일어나므로 클라이언트가 다시 시도해도 안전하다.
- 처리 lease가 이미 끝난 claim을 저장소가 시작하지 않을 때도 같은 503이다. 요청이 claim과 action 시작 사이에
lease보다 오래 걸렸다(멈춘 프로세스, 느린 저장소 호출). ERROR 줄 `failure classified as
IDEMPOTENCY_UNAVAILABLE (…)`에 예외가 붙고, 예외 메시지는 `the claim's processing lease ran out before the
action started; nothing ran: <scope>`다. prod JSON 로그에서는 `message`가 아니라 `stack_trace`에 있다.
저장소는 멀쩡할 수 있다. 이때도 아무것도 실행되지 않았고, 그 키로 오는 다음 요청이 claim을 넘겨받아 실행한다.
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(`retryable=true`)은 같은 장애가 action이 실행된 뒤에 닥친 것이다.
결과를 기록하는 동안 저장소가 답하지 않았다. use case가 자기 쓰기 트랜잭션 안에서 executor를 불렀으면, 그
트랜잭션의 DB 쓰기는 예외와 함께 롤백됐다. 자기 트랜잭션을 따로 커밋한 action은 쓰기가 남았고, 트랜잭션 밖의
일(외부 호출, 메시지)은 일어났을 수 있다. 「아무것도 실행되지 않았다」가 아니다. 클라이언트는 같은 키로 다시
보낸다.
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED`(`retryable=false`)는 반대 경우다. 앞선 시도의 효과가 이미 일어났는지
저장소가 가릴 수 없다. 두 기록이 이 코드를 낸다.
- `ABANDONED`: action이 예외를 던졌거나 효과를 모른다고 보고했다. 기록이 만료될 때까지 바뀌지 않는다.
- 처리 lease(`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s)가 지난 `EXECUTING`: 시도가 죽었거나, lease보다 오래 아직
돌고 있다. executor는 lease를 늘리지 않으므로 느리지만 멀쩡한 요청도 여기에 온다. 서버는 그 요청을 다시
실행하지 않고 기록도 건드리지 않는다. 시도가 아직 돌다가 끝나면 그 결과가 기록되고, 첫 요청은 보통의 응답을
받고, 그 키로 오는 뒤의 요청은 그 결과를 replay로 받는다. 시도가 보고한 실패도 같은 식으로 기록된다. 그래서
이 500은 저절로 멈출 수 있다(소유자 결정 2026-11-04).
이것은 Redis 저장소의 경우다. PostgreSQL 저장소는 템플릿이 부르는 대로 use case의 쓰기 트랜잭션 안에서
불리면, 끝나지 않은 기록을 다른 요청에 보이지 않는다. 그 요청은 첫 트랜잭션이 끝나기를 기다렸다가, 커밋됐으면
replay를, 롤백됐으면 새 실행을 받는다(`docs/web/http-contract.md` §2).
## Diagnosis
## 진단
- Check the health of the idempotency store the service uses (`/actuator/health` component of the
JPA datasource or Redis, depending on the selected provider).
- Look for connection-pool saturation or timeouts on that store in the same time window; the
executor reports saturation as unavailable rather than guessing.
- For `IDEMPOTENCY_RECOVERY_REQUIRED`, find the scope in the server's ERROR log of the failed request.
Every transport writes the same line, `failure classified as IDEMPOTENCY_RECOVERY_REQUIRED
(category=DATA_INTEGRITY, retryable=false)`, with the exception attached
(shared-contract `ServerFailureLog`), and adds its own correlation:
- web: no suffix; the line carries the request's `X-Request-Id` (MDC `request_id`).
- gRPC: ` (method=<service>/<method>)`; MDC `request_id` too when the service closed the call on
its callback thread.
- GraphQL: ` (executionId=<id>)`, the `executionId` the client got in the error's `extensions`.
- STOMP (`@MessageMapping`): no suffix; MDC `request_id` is the frame's.
- 서비스가 쓰는 멱등성 저장소의 상태를 본다(고른 provider에 따라 JPA datasource나 Redis의 `/actuator/health`
구성 요소).
- 같은 시간대에 그 저장소의 커넥션 풀 포화나 시간 초과를 찾는다. executor는 포화를 추측하지 않고 사용 불가로
보고한다.
- `IDEMPOTENCY_RECOVERY_REQUIRED`는 실패한 요청의 서버 ERROR 로그에서 scope를 찾는다. 모든 전송 계층이 같은 줄
`failure classified as IDEMPOTENCY_RECOVERY_REQUIRED (category=DATA_INTEGRITY, retryable=false)`에 예외를
붙여 쓰고(shared-contract `ServerFailureLog`), 자기 상관 정보를 덧붙인다.
- web: 덧붙이는 것이 없다. 줄에 요청의 `X-Request-Id`(MDC `request_id`)가 실린다.
- gRPC: ` (method=<service>/<method>)`. 서비스가 callback 스레드에서 호출을 닫았으면 MDC `request_id`도 있다.
- GraphQL: ` (executionId=<id>)`. 클라이언트가 오류의 `extensions`에서 받은 `executionId`다.
- STOMP(`@MessageMapping`): 덧붙이는 것이 없다. MDC `request_id`는 그 frame의 것이다.
The exception message ends with
`<operation code>::v<digest version>::<scope digest>`, for example
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…` (64 hex characters). Then look at the
record in the store the service uses (`APP_IDEMPOTENCY_PROVIDER`). There is no tool for this; these
are the commands.
- Redis. The key, for example `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`, is
예외 메시지는 `<operation code>::v<digest version>::<scope digest>`로 끝난다. 예:
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…`(16진수 64자). 그다음 서비스가 쓰는 저장소
(`APP_IDEMPOTENCY_PROVIDER`)에서 기록을 본다. 이것을 해 주는 도구는 없다. 아래가 그 명령이다.
- Redis. 키는 예를 들어 `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`이고, 모양은 다음과 같다.
<!-- runbook-redis: idempotency-record-key -->
```
@@ -77,11 +67,10 @@ status: active
PTTL <key>
```
`state` `ABANDONED` is final. `state` `EXECUTING` with a `leaseUntil` (lease end, epoch
milliseconds, server clock) earlier than the server's `TIME` (first value × 1000) is an attempt
past its lease that may still be running. `PTTL` is how long the record still lives, in
milliseconds.
- PostgreSQL, in the application's schema:
`state` `ABANDONED`는 바뀌지 않는다. `state` `EXECUTING`이면서 `leaseUntil`(lease 끝, epoch 밀리초, 서버
시계)이 서버의 `TIME`(첫 값 × 1000)보다 이르면, lease가 지났지만 아직 돌고 있을 수 있는 시도다. `PTTL`은
기록이 앞으로 살아 있을 시간(밀리초)이다.
- PostgreSQL. 애플리케이션의 스키마에서:
```sql
SELECT status, attempt, failure_disposition, last_transition_kind,
@@ -91,48 +80,44 @@ status: active
AND scope_hash = '<scope digest>';
```
`status` `ABANDONED` with `last_transition_kind` `FAIL_ABANDONED` means the action threw or
reported its effect unknown. `status` `EXECUTING` with `processing_lease_until` before
`clock_timestamp()` is an attempt past its lease that may still be running. (`ABANDONED` with
`EXPIRED_EXECUTION` is a lease that ran out under a version before 2026-11-04, which abandoned
such rows; it goes away when the row expires.) `expires_at` is when the reaper deletes the row.
`status` `ABANDONED`에 `last_transition_kind` `FAIL_ABANDONED`면 action이 예외를 던졌거나 효과를 모른다고
보고했다. `status` `EXECUTING`에 `processing_lease_until`이 `clock_timestamp()`보다 이르면, lease가 지났지만
아직 돌고 있을 수 있는 시도다. `expires_at`은 reaper가 행을 지우는 시각이다.
## Action
> 이력: `ABANDONED`에 `EXPIRED_EXECUTION`은 2026-11-04 전 버전에서 lease가 끝난 행이다. 그 버전은 그런 행을
> 버렸다. 행이 만료되면 사라진다.
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff. When
the exception message says the claim's processing lease ran out before the action started, the
store is not the cause: find what held those requests between claim and start (thread dumps, GC
pauses, the store's latency in that window). Nothing to repair; the next same-key request runs.
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: restore the store, then check the effects outside the
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts,
and `IDEMPOTENCY_RECOVERY_REQUIRED` after it — handle that one as below.
- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. If the record is
`EXECUTING` past its lease, first wait for the attempt: look the record up again after the
longest time the action can take. It changes by itself when the attempt finishes — `COMPLETED`
(resends replay it, nothing to do), `ABANDONED`, or `FAILED_RETRYABLE` (the attempt proved it had
no effect, and the next request with the key runs it). A crashed attempt, or one whose request
already ended with `IDEMPOTENCY_COMPLETION_UNKNOWN`, never changes it; that record stays
`EXECUTING` until it expires. Business data checked while the attempt still runs can say "no
effect" a moment before the effect lands. Then confirm from business data (the order, the
payment, the downstream system) whether the effect exists. There is no way to complete the record
by hand — the stored response is the action's own result.
- The effect exists: tell the client it was applied. Leave the record; a resend with the key keeps
getting this 500 until the record expires (Redis `PTTL`, PostgreSQL `expires_at`).
- The effect does not exist: the client sends the request again under a new key. To let the same
key run again instead, delete the record — only while it is `ABANDONED`, because any other state
belongs to a request that may still be running or to a stored result. Do not delete an
`EXECUTING` record, even past its lease: if its attempt is still alive, its late result finds no
record (`ABSENT`) — the result is lost, the first request gets this 500 after its work took
effect, and the next request with the key runs the work a second time. Leave it to expire.
- Redis: check and delete in one step, as the account the service's registered scripts run as
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, or the application account when it
is unset). Checking with `HMGET` and then sending `DEL` is two commands: a record that expires
between them and is claimed again by a new request is deleted while that request runs, and
the next request with the key runs the work a second time (re-review 2026-11-04 RR4-03-02).
The program below deletes the key only while its `state` is `ABANDONED`. The application
accounts are denied `EVAL` (`compose/redis/acl/README.md`), so load it and run it by the
digest `SCRIPT LOAD` prints, as the service runs its own scripts:
## 조치
- `IDEMPOTENCY_UNAVAILABLE`: 저장소를 되살린다. 클라이언트는 같은 키로 백오프하며 다시 시도한다. 예외 메시지가
action 시작 전에 claim의 처리 lease가 끝났다고 하면 저장소가 원인이 아니다. claim과 시작 사이에 그 요청들을
붙잡은 것을 찾는다(스레드 덤프, GC 멈춤, 그 시간대의 저장소 지연). 고칠 것은 없다. 같은 키의 다음 요청이
실행된다.
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: 저장소를 되살린 뒤, 실패한 요청들의 트랜잭션 밖 효과를 확인한다(ERROR 로그
줄이 코드를 알려 준다). 같은 키로 다시 보내면, 실제로 기록된 결과는 replay로 받고, 시도의 lease가 남은 동안은
`IDEMPOTENT_IN_FLIGHT`를, 그 뒤에는 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다. 마지막 것은 아래처럼 다룬다.
- `IDEMPOTENCY_RECOVERY_REQUIRED`: 클라이언트에게 그냥 다시 시도하라고 하지 않는다. 기록이 lease가 지난
`EXECUTING`이면 먼저 시도를 기다린다. action이 걸릴 수 있는 가장 긴 시간이 지난 뒤 기록을 다시 본다. 시도가
끝나면 기록은 저절로 바뀐다. `COMPLETED`(다시 보내면 replay된다, 할 일 없음), `ABANDONED`, `FAILED_RETRYABLE`
(시도가 효과가 없었음을 증명했고, 그 키의 다음 요청이 실행한다) 중 하나다. 죽은 시도, 또는 요청이 이미
`IDEMPOTENCY_COMPLETION_UNKNOWN`으로 끝난 시도는 기록을 바꾸지 않는다. 그 기록은 만료될 때까지 `EXECUTING`으로
남는다. 시도가 아직 도는 동안 확인한 업무 데이터는 효과가 들어가기 직전에 「효과 없음」으로 보일 수 있다.
그다음 업무 데이터(주문, 결제, 하위 시스템)로 효과가 있는지 확인한다. 기록을 손으로 완료할 방법은 없다. 저장된
응답은 action 자신의 결과다.
- 효과가 있다: 클라이언트에게 적용됐다고 알린다. 기록은 그대로 둔다. 그 키로 다시 보내면 기록이 만료될 때까지
(Redis `PTTL`, PostgreSQL `expires_at`) 이 500을 계속 받는다.
- 효과가 없다: 클라이언트가 새 키로 요청을 다시 보낸다. 같은 키로 다시 돌리게 하려면 기록을 지운다. 단
`ABANDONED`일 때만 지운다. 다른 상태는 아직 돌고 있을 수 있는 요청이나 저장된 결과의 것이다. `EXECUTING`
기록은 lease가 지났어도 지우지 않는다. 그 시도가 아직 살아 있으면 늦게 온 결과가 기록을 찾지 못하고
(`ABSENT`) 결과가 사라진다. 첫 요청은 일이 적용된 뒤에 이 500을 받고, 그 키의 다음 요청이 일을 한 번 더
한다. 만료되게 둔다.
- Redis: 확인과 삭제를 한 단계로, 서비스에 등록된 스크립트가 도는 계정으로 한다
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, 비어 있으면 애플리케이션 계정). `HMGET`으로
확인하고 `DEL`을 보내면 명령이 둘이다. 그 사이에 만료되어 새 요청이 다시 claim한 기록은 그 요청이 도는
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다(2026-11-04 재확인 리뷰 RR4-03-02). 아래 프로그램은
`state`가 `ABANDONED`일 때만 키를 지운다. 애플리케이션 계정은 `EVAL`이 막혀 있으므로
(`compose/redis/acl/README.md`), 서비스가 자기 스크립트를 돌리는 것처럼 불러 올리고 `SCRIPT LOAD`가 찍은
digest로 돌린다.
<!-- runbook-redis: idempotency-delete-abandoned -->
```
@@ -140,11 +125,10 @@ status: active
EVALSHA <digest SCRIPT LOAD printed> 1 <key>
```
`1` deleted the record; the key is new. `0` deleted nothing: the record is no longer
`ABANDONED` (or is gone) — look again before doing anything else. `NOSCRIPT` means the node
that holds the key (a cluster) has not loaded the program: run `SCRIPT LOAD` on that node and
`EVALSHA` again; nothing was deleted. A record that is about to expire needs nothing; once it
is gone the key is new.
`1`이면 기록을 지웠고 키는 새것이다. `0`이면 아무것도 지우지 않았다. 기록이 더는 `ABANDONED`가 아니다
(또는 없다). 다른 일을 하기 전에 다시 본다. `NOSCRIPT`는 키를 가진 노드(클러스터)가 프로그램을 불러 올리지
않았다는 뜻이다. 그 노드에서 `SCRIPT LOAD`를 돌리고 `EVALSHA`를 다시 한다. 아무것도 지워지지 않았다. 곧
만료될 기록은 할 일이 없다. 사라지면 키는 새것이다.
- PostgreSQL:
```sql
@@ -154,12 +138,12 @@ status: active
AND status = 'ABANDONED';
```
Without either step the key is released when the record expires. A record whose attempt never
finished lives for the processing lease plus `APP_IDEMPOTENCY_TTL` from its claim; one the action
marked failed lives for `APP_IDEMPOTENCY_FAILURE_RETENTION` (not shorter than `APP_IDEMPOTENCY_TTL`)
from the failure (`docs/web/http-contract.md`, "서버가 기억하는 기간").
어느 단계도 하지 않으면 기록이 만료될 때 키가 풀린다. 시도가 끝나지 않은 기록은 claim부터 처리 lease에
`APP_IDEMPOTENCY_TTL`을 더한 만큼 산다. action이 실패로 표시한 기록은 실패부터
`APP_IDEMPOTENCY_FAILURE_RETENTION`(`APP_IDEMPOTENCY_TTL`보다 짧지 않다)만큼 산다
(`docs/web/http-contract.md` 「서버가 기억하는 기간」).
## Escalation
## 에스컬레이션
- P2 → P1 when the store stays unavailable for more than 10 minutes on a write path.
- Page the owner of the idempotency store (database or Redis on-call).
- 쓰기 경로에서 저장소가 10분 넘게 사용 불가로 남으면 P2 → P1.
- 멱등성 저장소 소유자(DB나 Redis 당번)를 부른다.
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [INTERNAL_ERROR, INTERNAL_AUTH_MISCONFIGURATION, JVM_OOM]
severity: P1
owner: oncall
last_updated: 2026-05-22
status: stub
status: 초안
---
# Runbook: 5xx Internal error spike
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [JOB_DEAD_LETTER]
severity: P1
owner: oncall
last_updated: 2026-06-13
status: stub
status: 초안
---
# Runbook: background job dead letter (`runbook://job/dead-letter`)
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [JOB_EXECUTOR_REJECTED]
severity: P1
owner: oncall
last_updated: 2026-06-13
status: stub
status: 초안
---
# Runbook: async executor rejected (`runbook://job/executor-rejected`)
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [JOB_TIMEOUT]
severity: P2
owner: oncall
last_updated: 2026-11-03
status: stub
status: 초안
---
# Runbook: background job timeout (`runbook://job/timeout`)
+32 -33
View File
@@ -5,34 +5,34 @@ error_codes: [LOCK_ACQUISITION_TIMEOUT]
severity: P2
owner: oncall
last_updated: 2026-11-07
status: stub
status: 초안
---
# Runbook: LOCK_ACQUISITION_TIMEOUT (`runbook://lock/acquisition-timeout`)
## Symptoms
## 증상
- HTTP 409 with `error.code=LOCK_ACQUISITION_TIMEOUT` and `Retry-After: 1`; GraphQL extension
`code=LOCK_ACQUISITION_TIMEOUT`, gRPC trailer `error-code: LOCK_ACQUISITION_TIMEOUT` (`ABORTED`), all
`retryable=true`.
- No server log line. A 4xx answer is not an incident, so no transport logs it, and the lock adapters
do not log a timeout either. The exception's message (lock key, wait time) reaches no log and no
client, so which lock timed out is recorded nowhere. Read the metric and the lock table below.
- Before 2026-11-07 the template answered this as 500 `INTERNAL_ERROR` with an "unhandled exception"
ERROR line (the exception was not an `ApiErrorCarrier`). A service on an older template sees that
instead.
- Distributed lock wait exceeded configured timeout; high contention on a resource
- HTTP 409, `error.code=LOCK_ACQUISITION_TIMEOUT`, `Retry-After: 1`. GraphQL은 extension
`code=LOCK_ACQUISITION_TIMEOUT`, gRPC는 trailer `error-code: LOCK_ACQUISITION_TIMEOUT`(`ABORTED`)이고, 모두
`retryable=true`다.
- 서버 로그 줄이 없다. 4xx 응답은 장애가 아니라서 어느 전송 계층도 로그를 남기지 않고, 락 어댑터도 시간 초과를
로그에 쓰지 않는다. 예외 메시지(락 키, 대기 시간)는 어느 로그에도 클라이언트에도 닿지 않으므로 어느 락이
시간을 넘겼는지는 어디에도 기록되지 않는다. 아래의 메트릭과 락 테이블을 읽는다.
- 분산 락 대기가 설정된 시간 상한을 넘었다. 한 자원에 경합이 심하다.
## Diagnosis
> 이력: 2026-11-07 전의 템플릿은 이 경우를 500 `INTERNAL_ERROR`와 "unhandled exception" ERROR 줄로
> 응답했다(예외가 `ApiErrorCarrier`가 아니었다). 옛 템플릿을 쓰는 서비스에서는 그것이 보인다.
1. Contention rate. With `APP_MULTI_INSTANCE_ENABLED=true` the JDBC lock is metered: compare
`lock.acquisition{outcome="timeout"}` with `lock.acquisition{outcome="acquired"}`. The counter has
no lock name and no wait time — a key is never a metric tag (`docs/registries/metrics.yaml`). The
in-process lock (`APP_MULTI_INSTANCE_ENABLED=false`, the default) has no metric and keeps nothing in
the database; the steps below apply only to the JDBC lock.
2. Who holds locks now. `INT_LOCK` has one row per held lock. `CLIENT_ID` is the holding instance's
lock repository id, and the times are UTC. A row whose `EXPIRED_AFTER` has passed is a dead lease:
the next acquisition of that key takes it over. The oldest live rows are the long holders.
## 진단
1. 경합 비율. `APP_MULTI_INSTANCE_ENABLED=true`이면 JDBC 락에 메트릭이 붙는다.
`lock.acquisition{outcome="timeout"}`을 `lock.acquisition{outcome="acquired"}`와 비교한다. 이 counter에는
락 이름도 대기 시간도 없다. 키는 메트릭 태그가 되지 않는다(`docs/registries/metrics.yaml`). 프로세스 안 락
(`APP_MULTI_INSTANCE_ENABLED=false`, 기본값)은 메트릭이 없고 DB에 아무것도 남기지 않는다. 아래 단계는 JDBC
락에만 해당한다.
2. 지금 누가 락을 쥐고 있나. `INT_LOCK`에는 쥔 락마다 한 행이 있다. `CLIENT_ID`는 쥔 인스턴스의 락 저장소 id이고,
시각은 UTC다. `EXPIRED_AFTER`가 지난 행은 죽은 lease다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된
살아 있는 행이 오래 쥔 쪽이다.
<!-- runbook-sql: lock-holders -->
```sql
@@ -41,10 +41,9 @@ FROM int_lock
ORDER BY created_date;
```
3. The holder of one lock whose key you know from the code (for example `orders/42`). `LOCK_KEY` is
not the key: Spring Integration stores the key's name-based UUID (`UUID.nameUUIDFromBytes` of the
key's UTF-8 bytes), so a key cannot be read back from the table. This computes the UUID from the
key and finds its row:
3. 코드에서 키를 아는 락 하나(예: `orders/42`)를 누가 쥐고 있나. `LOCK_KEY`는 키 자체가 아니다. Spring
Integration은 키의 이름 기반 UUID(키의 UTF-8 바이트에 `UUID.nameUUIDFromBytes`)를 저장하므로 테이블에서 키를
거꾸로 읽을 수 없다. 아래 쿼리는 키에서 UUID를 계산해 그 행을 찾는다.
<!-- runbook-sql: lock-holder-of-key -->
```sql
@@ -56,18 +55,18 @@ WHERE lock_key = (
FROM md5('<lock_key>') AS h);
```
`:adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest` runs both blocks, read
from this file, against real PostgreSQL while locks are held.
`:adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest`가 두 블록을 이 파일에서 읽어,
락을 쥔 상태의 실제 PostgreSQL에 돌린다.
## Action
## 조치
- Client should retry with backoff (retryable=true)
- Optimize critical section holding time if lock contention is systemic
- 클라이언트는 백오프하며 다시 시도한다(retryable=true).
- 락 경합이 구조적이면 임계 구역을 쥐는 시간을 줄인다.
## Escalation
## 에스컬레이션
- Escalate if lock holder appears stuck (potential deadlock in distributed lock)
- 락 보유자가 멈춘 것으로 보이면 넘긴다(분산 락의 교착 가능성).
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+16 -14
View File
@@ -4,31 +4,33 @@ category: AUTHZ
error_codes: [ACTUATOR_FORBIDDEN]
severity: P2
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: ACTUATOR_FORBIDDEN (`runbook://management/actuator-forbidden`)
## Symptoms
## 증상
- HTTP 403 with `error.code=ACTUATOR_FORBIDDEN`
- Attempt to access restricted actuator endpoint (env/configprops/heapdump/shutdown)
- HTTP 403, `error.code=ACTUATOR_FORBIDDEN`.
- 제한된 actuator 엔드포인트(env·configprops·heapdump·shutdown)에 접근하려 했다.
## Diagnosis
## 진단
- Identify which actuator endpoint was accessed
- Check caller identity (internal tooling vs external)
- 어느 actuator 엔드포인트에 접근했는지 찾는다.
- 호출자가 누구인지(내부 도구인지 외부인지) 확인한다.
## Action
## 조치
- Verify management port is not exposed externally
- For heapdump/threaddump: follow break-glass runbook procedure
- management 포트가 밖으로 노출되지 않았는지 확인한다.
- heapdump·threaddump는 노출 목록에서 빠져 있다(`config/observability.yml`의
`management.endpoints.web.exposure.exclude`). 꼭 필요하면 운영 조직의 break-glass 절차를 따른다. 이 저장소에는
그 절차 문서가 없다.
## Escalation
## 에스컬레이션
- P1 if forbidden actuator access appears to be external attack
- 금지된 actuator 접근이 외부 공격으로 보이면 P1.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+94 -113
View File
@@ -5,27 +5,25 @@ error_codes: [MIGRATION_FAILED]
severity: P1
owner: oncall
last_updated: 2026-11-07
status: active
status: 운영
---
# Runbook: MIGRATION_FAILED (`runbook://migration/failed`)
## Symptoms
## 증상
- Container exits with code 70 (migration failure exit)
- Structured log with `error.code=MIGRATION_FAILED`, `startup.phase=migration`
- App refuses to start (fail-fast)
- JPA capability adapter refuses activation because its
`capability_schema_registry.lifecycle_state` is not `ACTIVE`
- 컨테이너가 코드 70으로 끝난다(마이그레이션 실패 종료).
- 구조화 로그 `error.code=MIGRATION_FAILED`, `startup.phase=migration`.
- 앱이 뜨기를 거부한다(fail-fast).
- JPA capability 어댑터가 활성화를 거부한다. 그 `capability_schema_registry.lifecycle_state`가 `ACTIVE`가 아니다.
## Diagnosis
## 진단
1. Stop rollout and keep the failed revision out of readiness. Do not route traffic to a partially
migrated instance.
2. Identify the exact stream from `src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml`. Each stream has an
independent `location` and `history-table`; do not infer ownership from a broad
`classpath:db/migration` scan.
3. From a privileged migration session, capture the stream state before changing anything:
1. rollout을 멈추고, 실패한 revision을 readiness 밖에 둔다. 마이그레이션이 반쯤 된 인스턴스로 트래픽을 보내지
않는다.
2. `src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml`에서 정확한 stream을 찾는다. stream마다
`location`과 `history-table`이 따로 있다. 넓은 `classpath:db/migration` 스캔으로 소유를 짐작하지 않는다.
3. 권한 있는 마이그레이션 세션에서, 무엇이든 바꾸기 전에 stream 상태를 남긴다.
```sql
select installed_rank, version, description, success
@@ -37,15 +35,14 @@ status: active
where capability_id = '<card-id>';
```
4. Check whether any owned relation was created without a successful history entry. Compare only
against the owned tables in the reviewed migration; do not drop unrelated relations.
5. Classify the failure:
- lock/statement timeout: remove the blocker or reduce rollout concurrency, then rerun. A
migration that locks a table already in use gives up after its own `SET LOCAL lock_timeout`
(5 s; SQLState `55P03` `lock_not_available`) and rolls back whole, so the history ends one
version below it. The blocker is a transaction that touched the table and is still open —
often an idle-in-transaction session. Find it by the lock it holds on that table (`<table>`
is the table the failing statement locks; for a `REFERENCES`, also the table it references):
4. 성공한 이력 행 없이 만들어진 소유 relation이 있는지 확인한다. 검토한 마이그레이션의 소유 테이블과만
비교한다. 상관없는 relation은 지우지 않는다.
5. 실패를 분류한다(Classify the failure).
- 락·문장 시간 초과: 막는 쪽을 없애거나 rollout 동시성을 줄이고 다시 돌린다. 이미 쓰는 테이블을 잠그는
마이그레이션은 자기 `SET LOCAL lock_timeout`(5 s, SQLState `55P03` `lock_not_available`)이 지나면 포기하고
통째로 롤백한다. 그래서 이력은 그 버전 바로 아래에서 끝난다. 막는 쪽은 그 테이블을 건드린 뒤 아직 열려 있는
트랜잭션이다. 흔히 idle-in-transaction 세션이다. 그 테이블에 쥔 락으로 찾는다(`<table>`은 실패한 문장이
잠그는 테이블이다. `REFERENCES`면 참조하는 테이블도 본다).
```sql
SELECT DISTINCT a.pid, a.state, a.xact_start, a.query
@@ -54,74 +51,65 @@ status: active
ORDER BY a.xact_start;
```
`query` is only that session's last statement, not the one that touched the table, so do not
look for the table name in it. Listing every long transaction instead names unrelated ones
(reports, batches) beside the blocker. End the blocker, then rerun
(`docs/jpa/migration-guide.md` "Bound the lock wait");
- SQL/data precondition: create a new forward migration that makes the precondition explicit;
a duplicate outbox order key stopping V21 (`ux_outbox_event_aggregate_order`) is the known
case — clean it up with `outbox-dead-letter.md` §8 and rerun, the migration stays as it is;
- checksum mismatch: compare the deployed artifact with the already applied script before
considering repair;
- a concurrent index migration failed (`CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX
CONCURRENTLY` or `REINDEX … CONCURRENTLY` that Flyway ran outside a transaction): a duplicate
value for a unique index, a deadlock, `statement_timeout` or a statement cancelled while it
waited for an open transaction. Outside a transaction nothing rolled back: the migration left
an invalid index and a history row with `success = false` for that version, and every later
deploy fails validation ("Detected failed migration to version …") until the row is gone.
Dropping the index alone does not clear it. Follow "Recover a failed concurrent index
migration" below;
- connection/TLS failure: fix transport or credentials without changing Flyway history.
`query`는 그 세션의 마지막 문장일 뿐 테이블을 건드린 문장이 아니므로, 거기서 테이블 이름을 찾지 않는다.
대신 긴 트랜잭션을 모두 나열하면 막는 쪽 옆에 상관없는 것(리포트, 배치)도 나온다. 막는 쪽을 끝낸 뒤 다시
돌린다(`docs/jpa/migration-guide.md` "Bound the lock wait").
- SQL·데이터 전제 조건: 전제 조건을 드러내는 새 forward 마이그레이션을 만든다. 중복된 outbox 순서 키가
V21(`ux_outbox_event_aggregate_order`)을 막는 것이 알려진 경우다. `outbox-dead-letter.md` §8로 정리하고 다시
돌린다. 마이그레이션은 그대로 둔다.
- checksum 불일치: repair를 생각하기 전에 배포한 산출물과 이미 적용된 스크립트를 비교한다.
- 동시 인덱스 마이그레이션 실패(Flyway가 트랜잭션 밖에서 돌린 `CREATE [UNIQUE] INDEX CONCURRENTLY`,
`DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`): unique 인덱스의 중복 값, 교착, `statement_timeout`,
또는 열린 트랜잭션을 기다리다 취소된 문장이다. 트랜잭션 밖이라 아무것도 롤백되지 않았다. 마이그레이션은
무효 인덱스와, 그 버전의 `success = false` 이력 행을 남겼다. 그 행이 사라질 때까지 뒤의 배포는 모두 검증에서
실패한다("Detected failed migration to version …"). 인덱스만 지워서는 풀리지 않는다. 아래 「실패한 동시
인덱스 마이그레이션 복구」를 따른다.
- 연결·TLS 실패: Flyway 이력을 바꾸지 않고 전송이나 자격 증명을 고친다.
## Action
## 조치
1. Prefer forward recovery. Fix the environmental blocker or add a new immutable migration, then
rerun the same owned stream with its exact history table.
2. For an optional stream that never installed successfully, keep the capability marker absent and
the runtime adapter disabled until migration succeeds.
3. After a successful migration, validate:
- the history contains only successful expected versions;
- `core_epoch` and `feature_revision` match the readiness registry;
- the marker is `INSTALLED_INACTIVE`;
- owned objects and constraints exist.
4. Change the marker to `ACTIVE` only after the compatible application revision is deployed and its
readiness check succeeds. Disabling or rolling back application code changes the marker to
`INSTALLED_INACTIVE`; it does not drop history or owned data.
5. Re-run the readiness lanes before promoting (every card's scenarios, no skips):
1. forward 복구를 먼저 쓴다. 환경 쪽 막힘을 고치거나 바뀌지 않는 새 마이그레이션을 더한 뒤, 같은 소유 stream을
그 정확한 이력 테이블로 다시 돌린다.
2. 한 번도 성공적으로 설치되지 않은 선택 stream은 마이그레이션이 성공할 때까지 capability 표시를 두지 않고 런타임
어댑터를 꺼 둔다.
3. 마이그레이션이 성공하면 확인한다.
- 이력에 기대한 버전의 성공 행만 있다.
- `core_epoch`와 `feature_revision`이 readiness registry와 같다.
- 표시가 `INSTALLED_INACTIVE`다.
- 소유 객체와 제약이 있다.
4. 맞는 애플리케이션 revision이 배포되고 그 readiness 검사가 성공한 뒤에만 표시를 `ACTIVE`로 바꾼다.
애플리케이션 코드를 끄거나 되돌리면 표시가 `INSTALLED_INACTIVE`로 바뀐다. 이력이나 소유 데이터는 지우지 않는다.
5. 승격 전에 readiness lane을 다시 돌린다(모든 card의 시나리오, 건너뜀 없음).
```bash
cd src
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain
```
6. Record the failed revision, stream/history table, root cause, recovery migration, elapsed time
and verification artifact in the incident.
6. 실패한 revision, stream·이력 테이블, 근본 원인, 복구 마이그레이션, 걸린 시간, 검증 산출물을 장애 기록에 남긴다.
Do not:
하지 않을 것:
- edit an already applied migration;
- delete or rewrite Flyway history to make validation green. The one exception is the failed row
of a failed concurrent index migration, deleted as "Recover a failed concurrent index migration"
below says — that row and nothing else;
- run `flyway repair` before checksum provenance is proven and reviewed;
- use `clean`, destructive rollback, or schema-wide restore as the first response;
- mark a capability `ACTIVE` before its migration and adapter readiness succeed.
- 이미 적용된 마이그레이션을 고친다.
- 검증을 통과시키려고 Flyway 이력을 지우거나 다시 쓴다. 예외는 하나다. 실패한 동시 인덱스 마이그레이션의 실패
행을 아래 「실패한 동시 인덱스 마이그레이션 복구」대로 지운다. 그 행 말고는 아무것도 지우지 않는다.
- checksum의 출처가 증명되고 검토되기 전에 `flyway repair`를 돌린다.
- 첫 대응으로 `clean`, 파괴적 롤백, 스키마 전체 복원을 쓴다.
- 마이그레이션과 어댑터 readiness가 성공하기 전에 capability를 `ACTIVE`로 표시한다.
If commit outcome was indeterminate during the failure, reconcile by the application
`OperationId`/idempotency reference before retrying business work. Never blind-retry a commit whose
result is unknown.
장애 중에 커밋 결과를 알 수 없었으면, 업무 작업을 다시 하기 전에 애플리케이션의 `OperationId`·멱등성 참조로
맞춘다. 결과를 모르는 커밋을 그냥 다시 시도하지 않는다.
## Recover a failed concurrent index migration
## 실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration)
The one case where this runbook changes Flyway history (owner decision, 2026-11-06). It applies to a
migration that holds a single concurrent index statement which Flyway ran outside a transaction —
with the `executeInTransaction=false` the guide asks for, or on its own for `CREATE`/`DROP INDEX
CONCURRENTLY` (`docs/jpa/migration-guide.md` "Concurrent index builds") — and whose row for this
version in the stream's history table says `success = false`. A migration that mixed other
statements in has already committed them: reconstruct that state with the database owner instead.
이 runbook이 Flyway 이력을 바꾸는 유일한 경우다(소유자 결정, 2026-11-06). Flyway가 트랜잭션 밖에서 돌린 동시
인덱스 문장 하나만 담은 마이그레이션에 쓴다. 가이드가 요구하는 `executeInTransaction=false`로 돌렸거나,
`CREATE`/`DROP INDEX CONCURRENTLY`라서 Flyway가 알아서 그렇게 돌린 경우다(`docs/jpa/migration-guide.md`
"Concurrent index builds"). 그리고 stream 이력 테이블의 이 버전 행이 `success = false`여야 한다. 다른 문장을 섞은
마이그레이션은 그 문장을 이미 커밋했다. 그 상태는 DB 소유자와 함께 다시 맞춘다.
1. Confirm no build is still running. An index that is still being built looks invalid in the
catalog too, and dropping it races the build. This query returns no rows when none is:
1. 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면
빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다.
<!-- runbook-sql: failed-concurrent-index-builds -->
```sql
@@ -130,29 +118,26 @@ FROM pg_stat_progress_create_index
WHERE datname = current_database();
```
2. Remove the cause. For a unique index, clean up the duplicate rows with the data owner (a forward
fix, never by editing the migration). For a deadlock, a timeout or a cancelled statement, end or
wait out the transaction that held it: a build or a rebuild waits for every transaction older
than itself, a drop for every transaction that holds a lock on its table. Do this before step 3,
whose `DROP INDEX CONCURRENTLY` waits for the same transactions.
3. Drop the invalid index a failed build or rebuild left: the index a `CREATE [UNIQUE] INDEX
CONCURRENTLY` names, or the copy a `REINDEX … CONCURRENTLY` made, named after the index with
`_ccnew` (or `_ccold`) on the end (`docs/jpa/runbooks.md` "An invalid index exists" lists them).
Run it on its own, not inside `BEGIN`: `CONCURRENTLY` refuses a transaction block.
**Skip this step when the failed statement is `DROP INDEX CONCURRENTLY`.** The invalid index it
left is the index the migration drops, and the deploy in step 5 runs the same statement, which
drops it. Dropped by hand first, that statement fails with `42704` ("index … does not exist")
and leaves a new failed row.
2. 원인을 없앤다. unique 인덱스면 데이터 소유자와 중복 행을 정리한다(forward 수정이다. 마이그레이션을 고치지
않는다). 교착, 시간 초과, 취소된 문장이면 그것을 쥔 트랜잭션을 끝내거나 끝나기를 기다린다. 빌드와 재빌드는
자기보다 오래된 트랜잭션을 모두 기다리고, 삭제는 그 테이블에 락을 쥔 트랜잭션을 모두 기다린다. 3단계 전에
한다. 3단계의 `DROP INDEX CONCURRENTLY`도 같은 트랜잭션을 기다린다.
3. 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지운다. `CREATE [UNIQUE] INDEX CONCURRENTLY`가 이름 붙인 인덱스,
또는 `REINDEX … CONCURRENTLY`가 만든 사본이다. 사본은 인덱스 이름 끝에 `_ccnew`(또는 `_ccold`)가 붙는다
(`docs/jpa/runbooks.md` "An invalid index exists"가 그 목록을 준다). `BEGIN` 안이 아니라 따로 돌린다.
`CONCURRENTLY`는 트랜잭션 블록을 거부한다.
**실패한 문장이 `DROP INDEX CONCURRENTLY`면 이 단계를 건너뛴다.** 그것이 남긴 무효 인덱스는 마이그레이션이
지우는 인덱스이고, 5단계의 배포가 같은 문장을 돌려 그것을 지운다. 먼저 손으로 지우면 그 문장이 `42704`
("index … does not exist")로 실패하고 새 실패 행을 남긴다.
<!-- runbook-sql: failed-concurrent-index-drop -->
```sql
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;
```
4. Delete that version's failed row from the stream's history table, and nothing else. `<version>`
is the `version` column of the failed row as the Diagnosis query shows it (`22.1` for
`V22_1__…`). It must delete exactly one row; if it deletes none, this is not the failure this
section is for, so classify it again.
4. stream 이력 테이블에서 그 버전의 실패 행을 지운다. 그 밖에는 아무것도 지우지 않는다. `<version>`은 진단
쿼리가 보여 주는 실패 행의 `version` 칸이다(`V22_1__…`이면 `22.1`). 정확히 한 행을 지워야 한다. 한 행도 지우지
않으면 이 절이 다루는 실패가 아니므로 다시 분류한다.
<!-- runbook-sql: failed-concurrent-index-history-row -->
```sql
@@ -160,28 +145,24 @@ DELETE FROM <owned_history_table>
WHERE version = '<version>' AND NOT success;
```
5. Deploy again. Flyway runs the same migration from the start: it builds the index, rebuilds it,
or drops the index the failed drop left.
5. 다시 배포한다. Flyway가 같은 마이그레이션을 처음부터 돌린다. 인덱스를 만들거나, 다시 만들거나, 실패한
삭제가 남긴 인덱스를 지운다.
The failed row is the record of a version that never applied, so deleting it leaves the order and
the checksum of every applied version as they were. Do not use `flyway repair` for this: it also
rewrites the checksums and descriptions of the remaining rows to match the scripts on disk, which
removes the evidence a checksum mismatch carries. `:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`
runs the three SQL blocks above, read from this file, against real PostgreSQL for each statement
this section covers: a unique build that fails on a duplicate, and a rebuild and a drop cancelled
while they wait for an open transaction. Steps 1–4 run in order, step 3 for the build and the
rebuild only, and the next deploy applies the version with no invalid index left and the earlier
version's checksum unchanged.
실패 행은 한 번도 적용되지 않은 버전의 기록이다. 그래서 지워도 적용된 모든 버전의 순서와 checksum은 그대로다.
이 일에 `flyway repair`를 쓰지 않는다. repair는 남은 행의 checksum과 description도 디스크의 스크립트에 맞춰 다시
쓰므로, checksum 불일치가 담은 증거를 지운다.
`:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`가 위의 SQL 블록 셋을 이
파일에서 읽어, 이 절이 다루는 문장마다 실제 PostgreSQL에 돌린다. 중복으로 실패하는 unique 빌드, 열린 트랜잭션을
기다리다 취소된 재빌드와 삭제다. 1~4단계를 차례로 돌리고(3단계는 빌드와 재빌드만), 다음 배포가 무효 인덱스 없이
그 버전을 적용하며 앞 버전의 checksum은 바뀌지 않는다.
## Escalation
## 에스컬레이션
- P1 immediate: the required application revision cannot become ready.
- Escalate to the database owner before Flyway history repair, destructive DDL, point-in-time
recovery, or primary failover.
- R3 restore/PITR and failover rehearsal requires a target-like backup topology; local
Testcontainers evidence is not a substitute.
- P1 즉시: 필요한 애플리케이션 revision이 ready가 되지 못한다.
- Flyway 이력 repair, 파괴적 DDL, 시점 복구(PITR), primary failover 전에 DB 소유자에게 넘긴다.
- R3 복원·PITR과 failover 예행연습에는 대상과 비슷한 백업 구성이 필요하다. 로컬 Testcontainers 증거로 대신하지
않는다.
---
This runbook is forward-only. The reviewed migration artifact and the readiness lanes' JUnit
results from CI are the audit sources.
이 runbook은 forward 방향만 다룬다. 감사 근거는 검토한 마이그레이션 산출물과 CI의 readiness lane JUnit 결과다.
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [OUTBOX_DEAD_LETTER]
severity: P1
owner: oncall
last_updated: 2026-11-04
status: stub
status: 초안
---
# Runbook: outbox dead letter (`runbook://outbox/dead-letter`)
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [OUTBOX_PUBLISH_FAILED]
severity: P2
owner: oncall
last_updated: 2026-11-04
status: stub
status: 초안
---
# Runbook: outbox publish 일시 실패 (`runbook://outbox/publish-failed`)
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: [RATE_LIMIT_EXCEEDED, IDEMPOTENT_IN_FLIGHT]
severity: P3
owner: oncall
last_updated: 2026-05-22
status: stub
status: 초안
---
# Runbook: Rate limit 초과 spike
+1 -1
View File
@@ -5,7 +5,7 @@ error_codes: []
severity: P1
owner: oncall
last_updated: 2026-07-29
status: active
status: 운영
---
# Runbook: Redis capability incident (`runbook://redis/capability-incident`)
+18 -16
View File
@@ -4,33 +4,35 @@ category: INTERNAL
error_codes: [JVM_OOM]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: JVM_OOM (`runbook://runtime/jvm-oom`)
## Symptoms
## 증상
- Container exits with code 137 (ExitOnOutOfMemoryError triggered)
- Structured log entry with `error.code=JVM_OOM` before exit
- 컨테이너가 코드 137로 끝난다(`-XX:+ExitOnOutOfMemoryError`가 동작함).
- 앱은 끝나기 전에 `error.code=JVM_OOM` 로그를 남기지 않는다. 이 코드를 로그에 쓰는 코드가 없다. JVM이
stderr에 `OutOfMemoryError`를 남기고 바로 끝난다.
## Diagnosis
## 진단
- Check heap dump if `-XX:HeapDumpOnOutOfMemoryError` is configured
- Review memory usage trends before crash
- Check for memory leaks: large cache growth, unbounded lists, session accumulation
- 힙 덤프를 본다. 이미지의 `JAVA_TOOL_OPTIONS`가 `-XX:+HeapDumpOnOutOfMemoryError`와
`-XX:HeapDumpPath=/var/tmp/heap`을 켠다(`src/Dockerfile`).
- 죽기 전 메모리 사용 추세를 본다.
- 메모리 누수를 찾는다: 커지기만 하는 캐시, 상한 없는 목록, 쌓이는 세션.
## Action
## 조치
- Restart container immediately (k8s will auto-restart with liveness probe)
- If recurring: increase heap `-Xmx` or fix memory leak
- 컨테이너를 바로 다시 띄운다(k8s는 liveness probe로 알아서 다시 띄운다).
- 반복되면 힙(`-Xmx`, 이미지는 `-XX:MaxRAMPercentage`)을 늘리거나 누수를 고친다.
## Escalation
## 에스컬레이션
- P1: immediate if multiple pods crashing simultaneously
- Page SRE / infra team for heap analysis
- P1: 여러 pod가 동시에 죽으면 즉시.
- 힙 분석은 SRE·인프라 팀을 부른다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+14 -14
View File
@@ -5,31 +5,31 @@ error_codes: [PROFILE_MISMATCH]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: PROFILE_MISMATCH (`runbook://startup/profile-mismatch`)
## Symptoms
## 증상
- Container exits with code 71 (profile mismatch exit)
- Structured log with `error.code=PROFILE_MISMATCH`, `startup.phase=profile-check`
- Production profile active with local-only settings enabled
- 컨테이너가 코드 71로 끝난다(프로파일 불일치 종료).
- 구조화 로그 `error.code=PROFILE_MISMATCH`, `startup.phase=profile-check`.
- 운영 프로파일이 켜져 있는데 로컬 전용 설정이 켜져 있다.
## Diagnosis
## 진단
- Check active Spring profiles (`spring.profiles.active`)
- Identify which local-only setting is incorrectly enabled in prod profile
- 켜진 Spring 프로파일(`spring.profiles.active`)을 확인한다.
- 운영 프로파일에서 잘못 켜진 로컬 전용 설정을 찾는다.
## Action
## 조치
- Remove local-only setting from production deployment config
- Ensure prod profile does not inherit local/dev profile settings
- 운영 배포 설정에서 로컬 전용 설정을 지운다.
- 운영 프로파일이 local·dev 프로파일 설정을 물려받지 않게 한다.
## Escalation
## 에스컬레이션
- P1: security risk if local settings expose debug endpoints in production
- P1: 로컬 설정이 운영에서 디버그 엔드포인트를 열면 보안 위험이다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
@@ -4,31 +4,31 @@ category: INTERNAL
error_codes: [REQUIRED_ADAPTER_DISABLED]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
last_updated: 2026-11-07
status: 초안
---
# Runbook: REQUIRED_ADAPTER_DISABLED (`runbook://startup/required-adapter-disabled`)
## Symptoms
## 증상
- Container exits with code 72 (required adapter disabled exit)
- Structured log with `error.code=REQUIRED_ADAPTER_DISABLED`, `startup.phase=adapter-check`
- 컨테이너가 코드 72로 끝난다(필수 어댑터 비활성화 종료).
- 구조화 로그 `error.code=REQUIRED_ADAPTER_DISABLED`, `startup.phase=adapter-enablement`.
## Diagnosis
## 진단
- Identify which adapter is disabled but required
- Check adapter enable flags in environment config
- 필수인데 꺼진 어댑터를 찾는다.
- 환경 설정의 어댑터 스위치를 확인한다.
## Action
## 조치
- Enable required adapter in deployment configuration
- If adapter is intentionally disabled, update the required/optional designation
- 배포 설정에서 필수 어댑터를 켠다.
- 일부러 끈 어댑터면 필수·선택 지정을 고친다.
## Escalation
## 에스컬레이션
- P1: app cannot start; coordinate with deployment team
- P1: 앱이 뜨지 못한다. 배포 팀과 맞춘다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+13 -13
View File
@@ -5,30 +5,30 @@ error_codes: [STARTUP_VALIDATION_FAILED]
severity: P1
owner: oncall
last_updated: 2026-06-15
status: stub
status: 초안
---
# Runbook: STARTUP_VALIDATION_FAILED (`runbook://startup/validation-failed`)
## Symptoms
## 증상
- Container exits with code 78 (env validation failure exit)
- Structured log with `error.code=STARTUP_VALIDATION_FAILED`, `startup.phase=env-validation`
- 컨테이너가 코드 78로 끝난다(환경 변수 검증 실패 종료).
- 구조화 로그 `error.code=STARTUP_VALIDATION_FAILED`, `startup.phase=env-validation`.
## Diagnosis
## 진단
- Check which required env variable is missing or malformed
- Review container environment and secrets injection
- 빠졌거나 형식이 틀린 필수 환경 변수를 찾는다.
- 컨테이너 환경과 secret 주입을 확인한다.
## Action
## 조치
- Supply missing environment variables to deployment
- Verify secrets are correctly mounted / injected
- 빠진 환경 변수를 배포에 넣는다.
- secret이 제대로 마운트·주입됐는지 확인한다.
## Escalation
## 에스컬레이션
- P1: app cannot start; coordinate with deployment/secrets team
- P1: 앱이 뜨지 못한다. 배포·secret 담당 팀과 맞춘다.
---
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
+22 -23
View File
@@ -5,40 +5,39 @@ error_codes: [<ERROR_CODE_1>, <ERROR_CODE_2>]
severity: <P1|P2|P3>
owner: oncall
last_updated: <YYYY-MM-DD>
status: <stub|active>
status: <초안|운영>
---
# Runbook: <TITLE> (`runbook://<area>/<scenario>`)
## Symptoms
## 증상
- What observable signals trigger this runbook?
- Alert name, metric thresholds, log patterns
- 이 runbook을 펴게 하는 관측 신호는 무엇인가?
- alert 이름, 메트릭 임계값, 로그 패턴
## Diagnosis
## 진단
- Step-by-step diagnostic commands and queries
- Log queries (Loki/CloudWatch)
- Metric panels to check
- Trace investigation approach
- 차례로 따라 하는 진단 명령과 쿼리
- 로그 쿼리(Loki·CloudWatch)
- 볼 메트릭 패널
- trace 조사 방법
## Action
## 조치
- Immediate mitigation steps
- Configuration changes
- Manual intervention procedures
- 바로 하는 완화
- 설정 변경
- 손으로 하는 개입 절차
## Escalation
## 에스컬레이션
- Conditions for severity upgrade (e.g., P2 → P1)
- Who to page and when
- Fallback procedures if on-call cannot resolve
- 심각도를 올리는 조건(예: P2 → P1)
- 언제 누구를 부르나
- 당번이 풀지 못할 때의 대안
---
> **Note**: This is the canonical runbook template.
> Copy this file, rename it to match the `runbook://area/scenario` pattern (→ `area-scenario.md`),
> fill in the frontmatter fields, replace section bodies with operational content,
> then set `status: active`. `LEGACY_STUB_DEBT` in `RunbookCoverageContractTest` is temporary
> containment for existing debt only; do not add a new stub there. Complete the runbook or adopt
> the future owned, expiring debt ledger.
> **안내**: 이 파일이 runbook의 기준 양식이다.
> 이 파일을 복사하고, `runbook://area/scenario` 꼴에 맞춰 이름을 바꾸고(→ `area-scenario.md`), 머리말 칸을 채우고,
> 절 본문을 운영 내용으로 바꾼 뒤 `status: 운영`으로 둔다. 본문을 아직 쓰지 못한 runbook은 `status: 초안`이다.
> `RunbookCoverageContractTest`의 `LEGACY_STUB_DEBT`는 이미 있는 초안만 잠시 담아 두는 목록이다. 새 초안을 거기에
> 더하지 않는다. runbook을 끝내거나, 앞으로 생길 소유자·기한 있는 부채 장부를 쓴다.
-38
View File
@@ -99,44 +99,6 @@ language docs/redis/command-policy.md
language docs/redis/operations.md
language docs/redis/support-matrix.md
language docs/redis/upgrade-guide.md
language docs/runbooks/adapter-adapter-disabled.md
language docs/runbooks/auth-audience-mismatch.md
language docs/runbooks/auth-claim-mapping-failed.md
language docs/runbooks/auth-issuer-mismatch.md
language docs/runbooks/auth-jwks-unavailable.md
language docs/runbooks/auth-kid-unknown.md
language docs/runbooks/auth-public-path-misconfiguration.md
language docs/runbooks/auth-token-expired.md
language docs/runbooks/auth-token-invalid-signature.md
language docs/runbooks/auth-token-malformed.md
language docs/runbooks/auth-token-missing.md
language docs/runbooks/authz-insufficient-permission.md
language docs/runbooks/authz-tenant-mismatch.md
language docs/runbooks/cache-stampede-lock-timeout.md
language docs/runbooks/cache-unavailable.md
language docs/runbooks/db-deadlock.md
language docs/runbooks/db-idle-in-tx-timeout.md
language docs/runbooks/db-query-canceled.md
language docs/runbooks/db-serialization-failure.md
language docs/runbooks/db-unavailable.md
language docs/runbooks/dependency-4xx-client.md
language docs/runbooks/dependency-5xx-server.md
language docs/runbooks/dependency-circuit-open.md
language docs/runbooks/dependency-connect-failed.md
language docs/runbooks/dependency-dns-failed.md
language docs/runbooks/dependency-timeout.md
language docs/runbooks/file-download-streaming-failure.md
language docs/runbooks/grpc-advanced-capabilities.md
language docs/runbooks/grpc-platform-operations.md
language docs/runbooks/idempotency-unavailable.md
language docs/runbooks/lock-acquisition-timeout.md
language docs/runbooks/management-actuator-forbidden.md
language docs/runbooks/migration-failed.md
language docs/runbooks/runtime-jvm-oom.md
language docs/runbooks/startup-profile-mismatch.md
language docs/runbooks/startup-required-adapter-disabled.md
language docs/runbooks/startup-validation-failed.md
language docs/runbooks/template.md
language docs/storage-capability-boundary.md
language docs/web/advanced-capabilities.md
language docs/web/openapi-32-compatibility.md
@@ -35,11 +35,16 @@ import org.yaml.snakeyaml.Yaml;
* <li><b>LINK RESOLUTION</b> — every non-null {@code runbook_link} resolves to an existing file
* under {@code docs/runbooks/}.
* <li><b>PLACEHOLDER/STUB SMOKE</b> — runbook body must not contain TODO/TBD/PLACEHOLDER/FIXME
* and frontmatter must not have {@code status: stub} — EXCEPT files on the {@code
* LEGACY_STUB_DEBT} below. Files outside this temporary debt set that are stub/placeholder
* FAIL.
* and frontmatter must not have the draft status {@code status: 초안} — EXCEPT files on the
* {@code LEGACY_STUB_DEBT} below. Files outside this temporary debt set that are
* draft/placeholder FAIL.
* </ol>
*
* <p>A runbook's {@code status} is one of the two words the runbook template ({@code
* docs/runbooks/template.md}) allows: {@code 초안} (draft) or {@code 운영} (in operation). Any other
* value fails, so a stub written with the retired {@code stub} spelling cannot pass as a finished
* runbook.
*
* <p>The registry and runbook directory are checked-in contract resources. Missing resources and
* every contract violation are hard failures.
*
@@ -54,7 +59,7 @@ class RunbookCoverageContractTest {
* (feature-operational-runbook-contract D9).
*
* <p>These are only the legacy stub runbooks seeded during Phase D1. This set must exactly match
* the current {@code status: stub} files. Do not add new debt here: complete the runbook or adopt
* the current {@code status: 초안} files. Do not add new debt here: complete the runbook or adopt
* the future owned, expiring debt ledger.
*/
private static final Set<String> LEGACY_STUB_DEBT =
@@ -105,6 +110,12 @@ class RunbookCoverageContractTest {
"startup-required-adapter-disabled.md",
"startup-validation-failed.md");
/** The draft status: the runbook's body is not written yet. */
private static final String DRAFT_STATUS = "초안";
/** Every status a runbook may declare: draft, or in operation. */
private static final Set<String> RUNBOOK_STATUSES = Set.of(DRAFT_STATUS, "운영");
/** Categories exempt from mandatory-runbook requirement (client-error only). */
private static final Set<String> EXEMPT_CATEGORIES =
Set.of("VALIDATION", "NOT_FOUND", "CONFLICT", "DATA_INTEGRITY");
@@ -232,7 +243,7 @@ class RunbookCoverageContractTest {
}
Path trackedRunbook =
repositoryResources.requireTrackedFileInside("docs/runbooks", filename);
if (extractFrontmatterStatus(Files.readString(trackedRunbook)).equals("stub")) {
if (extractFrontmatterStatus(Files.readString(trackedRunbook)).equals(DRAFT_STATUS)) {
currentStubRunbooks.add(filename);
}
}
@@ -241,7 +252,7 @@ class RunbookCoverageContractTest {
assertThat(LEGACY_STUB_DEBT)
.as(
"LEGACY_STUB_DEBT is temporary containment and must match every and only current "
+ "status=stub runbook; do not add new allowlist entries—complete the runbook "
+ "status=초안 runbook; do not add new allowlist entries—complete the runbook "
+ "or adopt the future owned, expiring debt ledger")
.containsExactlyInAnyOrderElementsOf(currentStubRunbooks);
}
@@ -264,15 +275,15 @@ class RunbookCoverageContractTest {
Path trackedRunbook =
repositoryResources.requireTrackedFileInside("docs/runbooks", filename);
String content = Files.readString(trackedRunbook);
// Check for status: stub in frontmatter
boolean hasStubStatus = extractFrontmatterStatus(content).equals("stub");
// Check for the draft status in frontmatter
boolean hasStubStatus = extractFrontmatterStatus(content).equals(DRAFT_STATUS);
// Check for placeholder body text
boolean hasPlaceholderBody = PLACEHOLDER_PATTERN.matcher(content).find();
if (hasStubStatus || hasPlaceholderBody) {
violations.add(
filename
+ ": "
+ (hasStubStatus ? "status=stub" : "")
+ (hasStubStatus ? "status=초안" : "")
+ (hasPlaceholderBody ? " body-contains-placeholder" : ""));
}
}
@@ -285,6 +296,34 @@ class RunbookCoverageContractTest {
.isEmpty();
}
@Test
void everyRunbookFrontmatterDeclaresDraftOrOperatingStatus() throws Exception {
// given
List<String> outsideVocabulary = new ArrayList<>();
// when
try (Stream<Path> files = Files.list(runbooksDir)) {
for (Path path : files.sorted().toList()) {
String filename = path.getFileName().toString();
if (!filename.endsWith(".md") || filename.equals("template.md")) {
continue;
}
Path trackedRunbook =
repositoryResources.requireTrackedFileInside("docs/runbooks", filename);
String content = Files.readString(trackedRunbook);
String status = extractFrontmatterStatus(content);
if (!extractFrontmatter(content).isEmpty() && !RUNBOOK_STATUSES.contains(status)) {
outsideVocabulary.add(filename + ": status=" + status);
}
}
}
// then
assertThat(outsideVocabulary)
.as("A runbook's frontmatter status must be one of %s", RUNBOOK_STATUSES)
.isEmpty();
}
@Test
void runbookCoverageRejectsFrontmatterFromSymlinkOutsideRunbooks(@TempDir Path tempDir)
throws Exception {