diff --git a/docs/runbooks/adapter-adapter-disabled.md b/docs/runbooks/adapter-adapter-disabled.md index 674e2299..3f88c52e 100644 --- a/docs/runbooks/adapter-adapter-disabled.md +++ b/docs/runbooks/adapter-adapter-disabled.md @@ -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..<이름>.enabled=false) …` + - 알림 라우터: `no notification route bound for channel=… route='…' — set app.notification.routes..=…` +- 배포 설정에서 어떤 선택 어댑터가 켜져 있는지 본다. -## 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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-audience-mismatch.md b/docs/runbooks/auth-audience-mismatch.md index 5677e363..028422e6 100644 --- a/docs/runbooks/auth-audience-mismatch.md +++ b/docs/runbooks/auth-audience-mismatch.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-claim-mapping-failed.md b/docs/runbooks/auth-claim-mapping-failed.md index eaee6ca0..338e8430 100644 --- a/docs/runbooks/auth-claim-mapping-failed.md +++ b/docs/runbooks/auth-claim-mapping-failed.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-issuer-mismatch.md b/docs/runbooks/auth-issuer-mismatch.md index 1a173344..d77b97bd 100644 --- a/docs/runbooks/auth-issuer-mismatch.md +++ b/docs/runbooks/auth-issuer-mismatch.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-jwks-unavailable.md b/docs/runbooks/auth-jwks-unavailable.md index b7c529e4..15197436 100644 --- a/docs/runbooks/auth-jwks-unavailable.md +++ b/docs/runbooks/auth-jwks-unavailable.md @@ -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:///.well-known/jwks.json` -- Check network connectivity from app pods to IdP +- IdP의 JWKS 엔드포인트 상태를 본다: `curl -sf https:///.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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-kid-unknown.md b/docs/runbooks/auth-kid-unknown.md index 1bb3ac15..d5949cfa 100644 --- a/docs/runbooks/auth-kid-unknown.md +++ b/docs/runbooks/auth-kid-unknown.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-public-path-misconfiguration.md b/docs/runbooks/auth-public-path-misconfiguration.md index 019a1976..164be247 100644 --- a/docs/runbooks/auth-public-path-misconfiguration.md +++ b/docs/runbooks/auth-public-path-misconfiguration.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-token-expired.md b/docs/runbooks/auth-token-expired.md index 215e86de..acb5d48d 100644 --- a/docs/runbooks/auth-token-expired.md +++ b/docs/runbooks/auth-token-expired.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-token-invalid-signature.md b/docs/runbooks/auth-token-invalid-signature.md index 02051f53..c0edd8eb 100644 --- a/docs/runbooks/auth-token-invalid-signature.md +++ b/docs/runbooks/auth-token-invalid-signature.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-token-malformed.md b/docs/runbooks/auth-token-malformed.md index 76a7d669..1ba219dd 100644 --- a/docs/runbooks/auth-token-malformed.md +++ b/docs/runbooks/auth-token-malformed.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-token-missing.md b/docs/runbooks/auth-token-missing.md index b454f909..64cb8c13 100644 --- a/docs/runbooks/auth-token-missing.md +++ b/docs/runbooks/auth-token-missing.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/auth-token-rotation-failure.md b/docs/runbooks/auth-token-rotation-failure.md index 5bdc2417..90564407 100644 --- a/docs/runbooks/auth-token-rotation-failure.md +++ b/docs/runbooks/auth-token-rotation-failure.md @@ -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 diff --git a/docs/runbooks/authz-cross-tenant-violation.md b/docs/runbooks/authz-cross-tenant-violation.md index b2a303c0..8aec86c6 100644 --- a/docs/runbooks/authz-cross-tenant-violation.md +++ b/docs/runbooks/authz-cross-tenant-violation.md @@ -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 접근 시도 감지 diff --git a/docs/runbooks/authz-insufficient-permission.md b/docs/runbooks/authz-insufficient-permission.md index ac74bfe7..b7b40bdf 100644 --- a/docs/runbooks/authz-insufficient-permission.md +++ b/docs/runbooks/authz-insufficient-permission.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/authz-tenant-mismatch.md b/docs/runbooks/authz-tenant-mismatch.md index 47747cd9..7a9e7035 100644 --- a/docs/runbooks/authz-tenant-mismatch.md +++ b/docs/runbooks/authz-tenant-mismatch.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/cache-stampede-lock-timeout.md b/docs/runbooks/cache-stampede-lock-timeout.md index f5e4f171..09643e5e 100644 --- a/docs/runbooks/cache-stampede-lock-timeout.md +++ b/docs/runbooks/cache-stampede-lock-timeout.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/cache-unavailable.md b/docs/runbooks/cache-unavailable.md index ebada52b..d2043c47 100644 --- a/docs/runbooks/cache-unavailable.md +++ b/docs/runbooks/cache-unavailable.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/db-deadlock.md b/docs/runbooks/db-deadlock.md index 6ba72674..d4db7a7d 100644 --- a/docs/runbooks/db-deadlock.md +++ b/docs/runbooks/db-deadlock.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/db-idle-in-tx-timeout.md b/docs/runbooks/db-idle-in-tx-timeout.md index ade79237..cb19af4f 100644 --- a/docs/runbooks/db-idle-in-tx-timeout.md +++ b/docs/runbooks/db-idle-in-tx-timeout.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/db-query-canceled.md b/docs/runbooks/db-query-canceled.md index 67ae9131..641833f2 100644 --- a/docs/runbooks/db-query-canceled.md +++ b/docs/runbooks/db-query-canceled.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/db-serialization-failure.md b/docs/runbooks/db-serialization-failure.md index eb424eb6..77d3ba61 100644 --- a/docs/runbooks/db-serialization-failure.md +++ b/docs/runbooks/db-serialization-failure.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/db-unavailable.md b/docs/runbooks/db-unavailable.md index 8b532c10..60a957ae 100644 --- a/docs/runbooks/db-unavailable.md +++ b/docs/runbooks/db-unavailable.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-4xx-client.md b/docs/runbooks/dependency-4xx-client.md index 19078807..81be84b1 100644 --- a/docs/runbooks/dependency-4xx-client.md +++ b/docs/runbooks/dependency-4xx-client.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-5xx-server.md b/docs/runbooks/dependency-5xx-server.md index 62d8c6a3..3affac0f 100644 --- a/docs/runbooks/dependency-5xx-server.md +++ b/docs/runbooks/dependency-5xx-server.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-circuit-open.md b/docs/runbooks/dependency-circuit-open.md index 9fc3e084..16111f36 100644 --- a/docs/runbooks/dependency-circuit-open.md +++ b/docs/runbooks/dependency-circuit-open.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-connect-failed.md b/docs/runbooks/dependency-connect-failed.md index ee8aff29..259ca94f 100644 --- a/docs/runbooks/dependency-connect-failed.md +++ b/docs/runbooks/dependency-connect-failed.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-dns-failed.md b/docs/runbooks/dependency-dns-failed.md index de1dd9f1..e65820d2 100644 --- a/docs/runbooks/dependency-dns-failed.md +++ b/docs/runbooks/dependency-dns-failed.md @@ -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 ` -- Check cluster DNS (CoreDNS) health +- 앱 pod에서 DNS 조회를 시험한다: `nslookup ` +- 클러스터 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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-timeout.md b/docs/runbooks/dependency-timeout.md index 6d5a98f6..693cc116 100644 --- a/docs/runbooks/dependency-timeout.md +++ b/docs/runbooks/dependency-timeout.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/dependency-unavailable.md b/docs/runbooks/dependency-unavailable.md index bd491f8f..a8d21080 100644 --- a/docs/runbooks/dependency-unavailable.md +++ b/docs/runbooks/dependency-unavailable.md @@ -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 diff --git a/docs/runbooks/file-download-streaming-failure.md b/docs/runbooks/file-download-streaming-failure.md index c1275456..743573d6 100644 --- a/docs/runbooks/file-download-streaming-failure.md +++ b/docs/runbooks/file-download-streaming-failure.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/grpc-advanced-capabilities.md b/docs/runbooks/grpc-advanced-capabilities.md index bc3a50d3..1382eade 100644 --- a/docs/runbooks/grpc-advanced-capabilities.md +++ b/docs/runbooks/grpc-advanced-capabilities.md @@ -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..enabled`. `GrpcAdvancedCapability` owns the list of -capability names; `GrpcAdvancedSupportMatrix` owns their current grades. +스위치는 `app.grpc.advanced..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는 통과했지만 아무것도 증명하지 않았다. diff --git a/docs/runbooks/grpc-platform-operations.md b/docs/runbooks/grpc-platform-operations.md index aa896ec7..44f2bf31 100644 --- a/docs/runbooks/grpc-platform-operations.md +++ b/docs/runbooks/grpc-platform-operations.md @@ -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"`라 기본 조립에 들어가지 않는다. diff --git a/docs/runbooks/idempotency-unavailable.md b/docs/runbooks/idempotency-unavailable.md index 8afacfac..72da6af8 100644 --- a/docs/runbooks/idempotency-unavailable.md +++ b/docs/runbooks/idempotency-unavailable.md @@ -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: ` — 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: `다. 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=/)`; MDC `request_id` too when the service closed the call on - its callback thread. - - GraphQL: ` (executionId=)`, 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=/)`. 서비스가 callback 스레드에서 호출을 닫았으면 MDC `request_id`도 있다. + - GraphQL: ` (executionId=)`. 클라이언트가 오류의 `extensions`에서 받은 `executionId`다. + - STOMP(`@MessageMapping`): 덧붙이는 것이 없다. MDC `request_id`는 그 frame의 것이다. - The exception message ends with - `::v::`, 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 + 예외 메시지는 `::v::`로 끝난다. 예: + `claim requires reconciliation: CHARGE_CARD::v1::3f9a…`(16진수 64자). 그다음 서비스가 쓰는 저장소 + (`APP_IDEMPOTENCY_PROVIDER`)에서 기록을 본다. 이것을 해 주는 도구는 없다. 아래가 그 명령이다. + - Redis. 키는 예를 들어 `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`이고, 모양은 다음과 같다. ``` @@ -77,11 +67,10 @@ status: active PTTL ``` - `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 = ''; ``` - `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로 돌린다. ``` @@ -140,11 +125,10 @@ status: active EVALSHA 1 ``` - `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 당번)를 부른다. diff --git a/docs/runbooks/internal-error-spike.md b/docs/runbooks/internal-error-spike.md index 0f90c325..83e6d561 100644 --- a/docs/runbooks/internal-error-spike.md +++ b/docs/runbooks/internal-error-spike.md @@ -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 diff --git a/docs/runbooks/job-dead-letter.md b/docs/runbooks/job-dead-letter.md index 0dfdd840..38faf6c3 100644 --- a/docs/runbooks/job-dead-letter.md +++ b/docs/runbooks/job-dead-letter.md @@ -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`) diff --git a/docs/runbooks/job-executor-rejected.md b/docs/runbooks/job-executor-rejected.md index c13db0d7..ea9fa91d 100644 --- a/docs/runbooks/job-executor-rejected.md +++ b/docs/runbooks/job-executor-rejected.md @@ -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`) diff --git a/docs/runbooks/job-timeout.md b/docs/runbooks/job-timeout.md index 30947cd7..dafd084b 100644 --- a/docs/runbooks/job-timeout.md +++ b/docs/runbooks/job-timeout.md @@ -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`) diff --git a/docs/runbooks/lock-acquisition-timeout.md b/docs/runbooks/lock-acquisition-timeout.md index 2f3f8bf4..4230ae9c 100644 --- a/docs/runbooks/lock-acquisition-timeout.md +++ b/docs/runbooks/lock-acquisition-timeout.md @@ -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다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된 + 살아 있는 행이 오래 쥔 쪽이다. ```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를 계산해 그 행을 찾는다. ```sql @@ -56,18 +55,18 @@ WHERE lock_key = ( FROM md5('') 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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/management-actuator-forbidden.md b/docs/runbooks/management-actuator-forbidden.md index 3aa96f73..d3115fb4 100644 --- a/docs/runbooks/management-actuator-forbidden.md +++ b/docs/runbooks/management-actuator-forbidden.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/migration-failed.md b/docs/runbooks/migration-failed.md index 601f96a6..4f96a60e 100644 --- a/docs/runbooks/migration-failed.md +++ b/docs/runbooks/migration-failed.md @@ -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 = ''; ``` -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 (`` - 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 세션이다. 그 테이블에 쥔 락으로 찾는다(`
`은 실패한 문장이 + 잠그는 테이블이다. `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. 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면 + 빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다. ```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")로 실패하고 새 실패 행을 남긴다. ```sql DROP INDEX CONCURRENTLY IF EXISTS ; ``` -4. Delete that version's failed row from the stream's history table, and nothing else. `` - 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` 칸이다(`V22_1__…`이면 `22.1`). 정확히 한 행을 지워야 한다. 한 행도 지우지 + 않으면 이 절이 다루는 실패가 아니므로 다시 분류한다. ```sql @@ -160,28 +145,24 @@ DELETE FROM WHERE 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 결과다. diff --git a/docs/runbooks/outbox-dead-letter.md b/docs/runbooks/outbox-dead-letter.md index 4799c29c..c42fdda9 100644 --- a/docs/runbooks/outbox-dead-letter.md +++ b/docs/runbooks/outbox-dead-letter.md @@ -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`) diff --git a/docs/runbooks/outbox-publish-failed.md b/docs/runbooks/outbox-publish-failed.md index b676e14e..fd6d7491 100644 --- a/docs/runbooks/outbox-publish-failed.md +++ b/docs/runbooks/outbox-publish-failed.md @@ -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`) diff --git a/docs/runbooks/rate-limit-exceeded.md b/docs/runbooks/rate-limit-exceeded.md index e3be402d..225512a1 100644 --- a/docs/runbooks/rate-limit-exceeded.md +++ b/docs/runbooks/rate-limit-exceeded.md @@ -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 diff --git a/docs/runbooks/redis-capability-incident.md b/docs/runbooks/redis-capability-incident.md index 481bb7fd..2af8035f 100644 --- a/docs/runbooks/redis-capability-incident.md +++ b/docs/runbooks/redis-capability-incident.md @@ -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`) diff --git a/docs/runbooks/runtime-jvm-oom.md b/docs/runbooks/runtime-jvm-oom.md index b8210da6..0f3e3a63 100644 --- a/docs/runbooks/runtime-jvm-oom.md +++ b/docs/runbooks/runtime-jvm-oom.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/startup-profile-mismatch.md b/docs/runbooks/startup-profile-mismatch.md index 6fa27e8b..a5d0ea2c 100644 --- a/docs/runbooks/startup-profile-mismatch.md +++ b/docs/runbooks/startup-profile-mismatch.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/startup-required-adapter-disabled.md b/docs/runbooks/startup-required-adapter-disabled.md index 341aa0cb..8862119a 100644 --- a/docs/runbooks/startup-required-adapter-disabled.md +++ b/docs/runbooks/startup-required-adapter-disabled.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/startup-validation-failed.md b/docs/runbooks/startup-validation-failed.md index fbeb5e8a..06a1ff90 100644 --- a/docs/runbooks/startup-validation-failed.md +++ b/docs/runbooks/startup-validation-failed.md @@ -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) +> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다. diff --git a/docs/runbooks/template.md b/docs/runbooks/template.md index 5759c600..48954a8a 100644 --- a/docs/runbooks/template.md +++ b/docs/runbooks/template.md @@ -5,40 +5,39 @@ error_codes: [, ] severity: owner: oncall last_updated: -status: +status: <초안|운영> --- # Runbook: (`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을 끝내거나, 앞으로 생길 소유자·기한 있는 부채 장부를 쓴다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 1bff4f87..b24b237e 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -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 diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java index c89a5109..6345f6f5 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/RunbookCoverageContractTest.java @@ -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 {