docs(runbooks): runbook을 한국어로 옮기고 상태를 초안·운영으로 바꾼다
문제: `docs/runbooks`의 runbook 38개가 영어였다(`check-docs.py` language
예외). 머리말 `status`는 `stub`·`active`였는데 문서 체계 규칙(design-docs
`conventions/docs-system.md` 1절)은 runbook 상태를 「초안 · 운영」으로 정한다.
번역하며 대조하니 지금 코드와 다른 주장도 있었다.
고친 것:
- 38개를 번역했다. 코드·명령·경로·설정 키·로그 문자열·표 구조는 그대로다.
lane이 읽는 SQL·Redis 블록과 표지(`<!-- runbook-sql: … -->`)는 바이트 그대로다.
- `status`: stub → 초안 43개, active → 운영 3개, `template.md`는 `<초안|운영>`.
머리말이 없는 gRPC runbook 둘은 그대로다.
- 코드에 맞춘 주장:
- adapter-adapter-disabled: 없는 `adapter_name` 로그 칸 → `ServerFailureLog`의
`failure classified as ADAPTER_DISABLED` 줄과 예외 메시지. 지금 이 코드를 내는
곳은 `RoutingNotifier`뿐이다.
- startup-required-adapter-disabled: `startup.phase=adapter-check` →
`adapter-enablement`(`StartupPhase.ADAPTER_ENABLEMENT`).
- cache-stampede-lock-timeout·cache-unavailable·file-download-streaming-failure:
그 코드는 `error-codes.yaml`에 없고 어느 코드도 내지 않는다고 밝혔다.
- db-idle-in-tx-timeout: 없는 `spring.jpa.properties.hibernate.connection.timeout`
→ `app.persistence-jpa.transaction.*`. db-query-canceled에 남은 시간 전달을 더했다.
- dependency-timeout: 「기본 전체 10s」 → profile `timeout.total-call`
(`HttpClientPlatformSettings` 기본 `4s`, 값은 configuration-reference를 가리킨다).
- management-actuator-forbidden: 없는 break-glass runbook → 노출 제외 목록
(`config/observability.yml`).
- runtime-jvm-oom: 아무것도 쓰지 않는 `error.code=JVM_OOM` 로그를 지우고, 힙 덤프
경로(`src/Dockerfile`)를 적었다.
- auth-public-path-misconfiguration: 공개 경로는 `config/security.yml` `public-paths`.
- grpc-advanced-capabilities: 지운 `GrpcAdvancedSupportMatrix` →
`GrpcAdvancedCapability.defaultGrade()`, envoy 참조 설정의 실제 경로.
- grpc-platform-operations: 없는 `runtime_memberships` → registry `"build": "optional-grpc"`.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Recover a failed concurrent index
migration", "Classify the failure")은 한국어 제목 뒤 괄호에 영어를 남겼다. 인용하는
쪽(테스트 fixture 메시지, `docs/upgrade`, 다른 세션 범위 문서)은 고치지 않아도 맞다.
- `RunbookCoverageContractTest`: `초안`을 초안으로 보고, 머리말 `status`가 `초안`·`운영`
밖이면 실패하는 테스트를 더했다.
- `scripts/check-docs-exceptions.txt`에서 runbook language 줄 38개를 지웠다.
버린 대안: 옛 `stub`도 초안으로 계속 받기. 그러면 옛 표기로 쓴 초안이 운영
runbook으로 통과한다. 어휘 밖 값을 실패로 둬야 그 길이 막힌다.
위험·한계:
- 이미 한국어였던 runbook 11개는 `status`만 바꿨고 본문 감사는 하지 않았다.
- runtime-jvm-oom의 「종료 코드 137」은 원문대로 두었다. JVM의
`-XX:+ExitOnOutOfMemoryError` 종료 코드는 3이고 137은 SIGKILL이라 확인이 필요하다.
- `docs/mongodb/runbooks/*.md`의 `status: active`는 이 테스트 밖이고 범위 밖이라 두었다.
검증: 아래 「검증」 줄은 영역 커밋 여섯이 합쳐진 최종 트리에서 돌렸다.
검증(desktop, 최종 트리 8295db89 = 이 묶음 마지막 커밋의 트리. 로그
`~/d2c-ops-docs-1-logs/`):
- `:app-bootstrap:documentContractTest` rc=0, 68개 실패 0(`RunbookCoverageContractTest` 7개).
`:app-bootstrap:repositoryContractTest` rc=0, 65개 건너뜀 1(원래 그렇다) 실패 0.
- runbook SQL·Redis 블록을 문서에서 읽는 lane: persistence-jpa
`postgresqlConcurrentIndexMigrationIntegrationTest`·`postgresqlDistributedLockIntegrationTest`·
`postgresqlOutboxOrderKeyRunbookIntegrationTest`·`postgresqlOutboxDispositionRunbookIntegrationTest`
rc=0(35개 실패 0), cache-redis `redisContainerContractTest` rc=0(103개 실패 0),
`:composition:outbox-relay:mainCheck` rc=0. 모두 실행됨(FROM-CACHE는 다른 leaf의 main 컴파일뿐).
- RED: 새 테스트를 기준 커밋의 옛 runbook에 대면 `legacyStubDebtMustMatchEveryAndOnlyCurrentStubRunbook`과
`everyRunbookFrontmatterDeclaresDraftOrOperatingStatus`가 실패한다("status=stub").
- `:app-bootstrap:spotlessCheck checkstyleTest testQualityCheck` rc=0.
- 커밋마다(노트북): `python3 scripts/check-docs.py` rc=0, `python3 -m unittest discover -s scripts/tests` rc=0.
This commit is contained in:
@@ -4,31 +4,35 @@ category: INTERNAL
|
||||
error_codes: [ADAPTER_DISABLED]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
last_updated: 2026-11-07
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: ADAPTER_DISABLED (`runbook://adapter/adapter-disabled`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 500 with `error.code=ADAPTER_DISABLED`
|
||||
- Code invoked an optional adapter (Kafka/Redis/Slack/Email) that is disabled in this deployment
|
||||
- HTTP 500, `error.code=ADAPTER_DISABLED`.
|
||||
- 이 배포에서 꺼져 있거나 묶이지 않은 선택 어댑터의 경로를 코드가 호출했다. 지금 템플릿에서 이 코드를 내는
|
||||
곳은 알림 라우터(`RoutingNotifier`)다. 채널과 route에 묶인 provider가 없을 때 낸다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check adapter name in log (`adapter_name` field)
|
||||
- Review deployment config — which optional adapters are enabled?
|
||||
- ERROR 로그 `failure classified as ADAPTER_DISABLED (category=INTERNAL, retryable=false)`를 찾는다. 줄에 붙은
|
||||
예외(`AdapterDisabledException`)의 메시지가 어댑터와 고칠 키를 알려 준다.
|
||||
- 기본 메시지: `optional adapter '<이름>' is disabled (app.<domain>.<이름>.enabled=false) …`
|
||||
- 알림 라우터: `no notification route bound for channel=… route='…' — set app.notification.routes.<channel>.<route>=<providerId>…`
|
||||
- 배포 설정에서 어떤 선택 어댑터가 켜져 있는지 본다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Enable the adapter in deployment configuration (env flag)
|
||||
- Or update application logic to skip disabled-adapter paths
|
||||
- 배포 설정에서 그 어댑터를 켠다(환경 변수 스위치). 알림이면 메시지가 가리키는 route를 묶고 그 provider를 켠다.
|
||||
- 아니면 꺼진 어댑터의 경로를 건너뛰도록 애플리케이션 로직을 고친다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- Escalate to deployment team if adapter should be enabled but isn't
|
||||
- 켜져 있어야 할 어댑터가 꺼져 있으면 배포 담당 팀에 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,32 +5,32 @@ error_codes: [AUTH_JWKS_UNAVAILABLE]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-06
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: AUTH_JWKS_UNAVAILABLE (`runbook://auth/jwks-unavailable`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 503 with `error.code=AUTH_JWKS_UNAVAILABLE`
|
||||
- ERROR log line `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`)
|
||||
- All authentication failing; JWKS refresh attempts failing
|
||||
- HTTP 503, `error.code=AUTH_JWKS_UNAVAILABLE`.
|
||||
- ERROR 로그 줄 `security failure: code=AUTH_JWKS_UNAVAILABLE category=TRANSIENT_DEPENDENCY method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`).
|
||||
- 인증이 모두 실패하고, JWKS 새로 고침도 실패한다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check IdP JWKS endpoint health: `curl -sf https://<idp-host>/.well-known/jwks.json`
|
||||
- Check network connectivity from app pods to IdP
|
||||
- IdP의 JWKS 엔드포인트 상태를 본다: `curl -sf https://<idp-host>/.well-known/jwks.json`
|
||||
- 앱 pod에서 IdP까지 네트워크가 닿는지 확인한다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Enable cached JWKS fallback if available
|
||||
- Coordinate with IdP team for restoration
|
||||
- 캐시된 JWKS로 버틸 수단이 있으면 쓴다.
|
||||
- IdP 팀과 복구를 맞춘다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1 page: IdP team immediately if JWKS endpoint unreachable > 2 minutes
|
||||
- P1 호출: JWKS 엔드포인트에 2분 넘게 닿지 않으면 IdP 팀을 바로 부른다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,30 +5,30 @@ error_codes: [AUTH_KID_UNKNOWN]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: AUTH_KID_UNKNOWN (`runbook://auth/kid-unknown`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 401 with `error.code=AUTH_KID_UNKNOWN`, `retryable=true`
|
||||
- Token `kid` header not present in cached JWKS
|
||||
- HTTP 401, `error.code=AUTH_KID_UNKNOWN`, `retryable=true`.
|
||||
- 토큰 헤더의 `kid`가 캐시된 JWKS에 없다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check if IdP key rotation occurred recently
|
||||
- Verify JWKS cache TTL and refresh timing
|
||||
- 최근에 IdP 키 교체가 있었는지 확인한다.
|
||||
- JWKS 캐시 TTL과 새로 고침 시점을 확인한다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Force JWKS cache refresh
|
||||
- Confirm new key is published in IdP JWKS endpoint
|
||||
- JWKS 캐시를 강제로 새로 고친다.
|
||||
- 새 키가 IdP JWKS 엔드포인트에 게시됐는지 확인한다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- Escalate to IdP team if new kid not appearing in JWKS after 10 minutes
|
||||
- 10분이 지나도 새 kid가 JWKS에 나타나지 않으면 IdP 팀에 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -4,33 +4,34 @@ category: INTERNAL
|
||||
error_codes: [INTERNAL_AUTH_MISCONFIGURATION]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-06
|
||||
status: stub
|
||||
last_updated: 2026-11-07
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: INTERNAL_AUTH_MISCONFIGURATION (`runbook://auth/public-path-misconfiguration`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 500 with `error.code=INTERNAL_AUTH_MISCONFIGURATION`
|
||||
- ERROR log line `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`)
|
||||
- Security filter misconfiguration detected at runtime
|
||||
- HTTP 500, `error.code=INTERNAL_AUTH_MISCONFIGURATION`.
|
||||
- ERROR 로그 줄 `security failure: code=INTERNAL_AUTH_MISCONFIGURATION category=INTERNAL method=… path=…`
|
||||
(logger `AuthErrorResponseWriter`).
|
||||
- 실행 중에 보안 필터 설정 오류가 드러났다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check `verifyPublicPathSnapshot` output in CI
|
||||
- Review recent changes to `SecurityConfig` or `application.yml` public path list
|
||||
- CI의 `verifyPublicPathSnapshot` 결과를 본다.
|
||||
- `SecurityConfig`와 공개 경로 목록(`config/security.yml`의 `public-paths`, `SECURITY_PUBLIC_PATHS`)의 최근
|
||||
변경을 본다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Revert misconfigured public path change
|
||||
- Run `./gradlew verifyPublicPathSnapshot` to compare snapshot
|
||||
- 잘못된 공개 경로 변경을 되돌린다.
|
||||
- `src/`에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1 immediate: if auth bypass is possible due to misconfiguration
|
||||
- P1 즉시: 설정 오류로 인증을 건너뛸 수 있으면.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,7 +5,7 @@ error_codes: [AUTH_TOKEN_EXPIRED, AUTH_KID_UNKNOWN, AUTH_JWKS_UNAVAILABLE, AUTH_
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: JWT key rotation 시 인증 실패 spike
|
||||
|
||||
@@ -5,7 +5,7 @@ error_codes: [AUTHZ_INSUFFICIENT_PERMISSION, AUTHZ_TENANT_MISMATCH]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: cross-tenant 접근 시도 감지
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,30 +5,30 @@ error_codes: [DEPENDENCY_DNS_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: DEPENDENCY_DNS_FAILED (`runbook://dependency/dns-failed`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 503 with `error.code=DEPENDENCY_DNS_FAILED`
|
||||
- DNS resolution failure for upstream hostname
|
||||
- HTTP 503, `error.code=DEPENDENCY_DNS_FAILED`.
|
||||
- 업스트림 호스트 이름의 DNS 조회가 실패했다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Test DNS resolution from app pod: `nslookup <upstream-host>`
|
||||
- Check cluster DNS (CoreDNS) health
|
||||
- 앱 pod에서 DNS 조회를 시험한다: `nslookup <upstream-host>`
|
||||
- 클러스터 DNS(CoreDNS) 상태를 확인한다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Verify upstream hostname configuration
|
||||
- Check CoreDNS / cluster DNS health
|
||||
- 업스트림 호스트 이름 설정을 확인한다.
|
||||
- CoreDNS·클러스터 DNS 상태를 확인한다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1 if cluster DNS is degraded
|
||||
- 클러스터 DNS가 나빠졌으면 P1.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,7 +5,7 @@ error_codes: [DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAIL
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-05-22
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: 외부 의존성 unavailable
|
||||
|
||||
@@ -4,31 +4,33 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [DOWNLOAD_STREAMING_FAILURE]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
last_updated: 2026-11-07
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: DOWNLOAD_STREAMING_FAILURE (`runbook://file/download-streaming-failure`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 503 with `error.code=DOWNLOAD_STREAMING_FAILURE`
|
||||
- Streaming response truncated; backpressure or timeout (60s / 100MB limit)
|
||||
- HTTP 503, `error.code=DOWNLOAD_STREAMING_FAILURE`.
|
||||
- 스트리밍 응답이 잘렸다. backpressure나 시간 초과(60초 / 100MB 한도)다.
|
||||
- 지금 템플릿은 이 코드를 내지 않는다. `docs/registries/error-codes.yaml`에 이 코드의 행이 없다. 파일 서버
|
||||
다운로드 장애는 [`docs/fileserver/operations.md`](../fileserver/operations.md)를 먼저 본다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check streaming response timeout configuration
|
||||
- Review download size vs 100MB limit
|
||||
- 스트리밍 응답 시간 상한 설정을 확인한다.
|
||||
- 다운로드 크기를 100MB 한도와 비교한다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Verify storage backend is reachable
|
||||
- Check for network congestion on download path
|
||||
- 저장소 백엔드에 닿는지 확인한다.
|
||||
- 다운로드 경로의 네트워크 혼잡을 확인한다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- Escalate to infra if storage backend is degraded
|
||||
- 저장소 백엔드가 나빠졌으면 인프라 팀에 넘긴다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -1,94 +1,88 @@
|
||||
# Runbook: gRPC advanced capabilities
|
||||
|
||||
Scope: the `:grpc-advanced:*` family. Everything here is off by default and stays off until a
|
||||
deployment names it. Nothing in this family ships in a runtime composition today.
|
||||
범위: `:grpc-advanced:*` family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로
|
||||
있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다.
|
||||
|
||||
Flags are `app.grpc.advanced.<capability>.enabled`. `GrpcAdvancedCapability` owns the list of
|
||||
capability names; `GrpcAdvancedSupportMatrix` owns their current grades.
|
||||
스위치는 `app.grpc.advanced.<capability>.enabled`다. capability 이름 목록과 기본 등급은
|
||||
`GrpcAdvancedCapability`(`defaultGrade()`)가 가진다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로
|
||||
등급을 바꾼다.
|
||||
|
||||
---
|
||||
|
||||
## A capability refuses to start
|
||||
## capability가 뜨기를 거부한다
|
||||
|
||||
`GrpcAdvancedModuleGuard` gives three different refusals, and the remedy differs:
|
||||
`GrpcAdvancedModuleGuard`는 세 가지로 거부하고, 고치는 법이 다르다.
|
||||
|
||||
| Message contains | Meaning | Remedy |
|
||||
| 메시지에 있는 말 | 뜻 | 고치는 법 |
|
||||
| --- | --- | --- |
|
||||
| "its feature flag is not set" | Nobody enabled it | Set the property named in the message |
|
||||
| "tracked rather than implemented" | Grade is `WATCH` | Nothing to do here; the capability is not implemented |
|
||||
| "uncharacterised failure modes" | Grade is `EXPERIMENTAL` and this is production | Record a production approval, or run it outside production |
|
||||
| "its feature flag is not set" | 아무도 켜지 않았다 | 메시지가 이름 댄 속성을 설정한다 |
|
||||
| "tracked rather than implemented" | 등급이 `WATCH`다 | 여기서 할 일은 없다. 그 capability는 구현되지 않았다 |
|
||||
| "uncharacterised failure modes" | 등급이 `EXPERIMENTAL`이고 여기는 운영이다 | 운영 승인을 기록하거나, 운영 밖에서 돌린다 |
|
||||
|
||||
The refusal message always names the property key, so the first case is a configuration line rather
|
||||
than a support question.
|
||||
거부 메시지는 늘 속성 키를 이름 댄다. 그래서 첫 경우는 지원 문의가 아니라 설정 한 줄이다.
|
||||
|
||||
---
|
||||
|
||||
## xDS: the control plane went away
|
||||
## xDS: control plane이 사라졌다
|
||||
|
||||
**What you are seeing.** The control plane is unreachable and clients are still routing.
|
||||
**보이는 것.** control plane에 닿지 않는데 클라이언트는 아직 라우팅한다.
|
||||
|
||||
**What it means.** `GrpcXdsFailurePolicy` serves the last-known-good snapshot, up to its staleness
|
||||
bound.
|
||||
**뜻.** `GrpcXdsFailurePolicy`가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다.
|
||||
|
||||
**What to do.**
|
||||
**할 일.**
|
||||
|
||||
1. Check the snapshot's age. `SERVE_LAST_KNOWN_GOOD` is the healthy degraded state.
|
||||
2. `STALE_BEYOND_BOUND` means the snapshot is older than the policy allows and is no longer trusted.
|
||||
Beyond that bound, a decommissioned backend would otherwise keep receiving traffic indefinitely.
|
||||
3. `NO_SNAPSHOT_YET` on a starting instance means it never reached the control plane. It fails after
|
||||
the initial fetch timeout rather than starting with no routing.
|
||||
1. snapshot의 나이를 본다. `SERVE_LAST_KNOWN_GOOD`는 정상적인 degraded 상태다.
|
||||
2. `STALE_BEYOND_BOUND`는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이
|
||||
없으면 내린 backend가 트래픽을 끝없이 받는다.
|
||||
3. 뜨는 인스턴스의 `NO_SNAPSHOT_YET`은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫
|
||||
fetch 시간 상한이 지나면 실패한다.
|
||||
|
||||
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsProfile` refuses an
|
||||
`APPLICATION` retry owner, because retry defined in two places has a winner that depends on
|
||||
resolution order rather than on a decision.
|
||||
xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하지 않는다**. `GrpcXdsProfile`이 `APPLICATION` 재시도
|
||||
소유자를 거부한다. 두 곳에 정의한 재시도는 결정이 아니라 해석 순서가 이기는 쪽을 정하기 때문이다.
|
||||
|
||||
---
|
||||
|
||||
## gRPC-Web: a browser call hangs and then fails with no status
|
||||
## gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다
|
||||
|
||||
**Almost always the proxy.** A gRPC status arrives as a trailer, and a browser cannot read a trailer
|
||||
the proxy did not expose. Check that the proxy's CORS `expose_headers` includes `grpc-status` and
|
||||
`grpc-message`; `GrpcWebProxyContract.violations` reports exactly this, and the reference
|
||||
configuration in `envoy/envoy.yaml` shows it in place.
|
||||
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
|
||||
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
|
||||
`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
|
||||
`src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
|
||||
|
||||
**If the method is client- or bidirectional-streaming**, it cannot work over gRPC-Web at all — a
|
||||
browser has no way to send a stream of messages. `GrpcWebRpcSupport.require` refuses such a method.
|
||||
**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
|
||||
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
|
||||
|
||||
---
|
||||
|
||||
## Servlet: a transport setting appears to be ignored
|
||||
## Servlet: 전송 설정이 무시되는 것 같다
|
||||
|
||||
It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and
|
||||
flow-control window tuning belong to it. This repository has no Servlet transport code that would
|
||||
refuse them, so configure them on the container.
|
||||
무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의
|
||||
몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다.
|
||||
|
||||
A Servlet run never substitutes for Netty certification.
|
||||
Servlet 실행은 Netty 인증을 대신하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## Hedging: backend load doubled
|
||||
## Hedging: backend 부하가 두 배가 됐다
|
||||
|
||||
**Expected, within a bound.** Hedging trades duplicate load for tail latency.
|
||||
`GrpcHedgingResult` records both `duplicateBackendCalls` and `cancelledLoserAttempts`; a dashboard
|
||||
showing only the latency improvement makes the trade look free.
|
||||
**상한 안이면 예상한 일이다.** hedging은 중복 부하를 내고 꼬리 지연을 줄인다. `GrpcHedgingResult`는
|
||||
`duplicateBackendCalls`와 `cancelledLoserAttempts`를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을
|
||||
공짜처럼 보이게 한다.
|
||||
|
||||
**What to check.** `GrpcHedgingBudget` caps hedges as a fraction of completed calls. If duplicate
|
||||
load is above that fraction, the budget is not being consumed — which means something is issuing
|
||||
hedges outside the coordinator.
|
||||
**확인할 것.** `GrpcHedgingBudget`은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이
|
||||
쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다.
|
||||
|
||||
**Hedging is refused** for anything but a read-only unary method. A hedged mutation runs twice by
|
||||
design, and an idempotency key does not help: the second attempt duplicates a success in progress
|
||||
rather than retrying a failure.
|
||||
읽기 전용 unary 메서드가 아니면 **hedging을 거부한다**. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다.
|
||||
두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다.
|
||||
|
||||
---
|
||||
|
||||
## Promoting a capability
|
||||
## capability 승격
|
||||
|
||||
Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence,
|
||||
performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable
|
||||
default needs thirty. Promotions are independent: promoting one capability changes no other's
|
||||
grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was
|
||||
removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it.
|
||||
`ADVANCED_STABLE`로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일
|
||||
soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은
|
||||
바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 `GrpcAdvancedPromotionGate`는 자기 테스트
|
||||
말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4).
|
||||
|
||||
Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy,
|
||||
container, control plane or toolchain). A suite that ran without it passed and established nothing.
|
||||
어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고
|
||||
돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다.
|
||||
|
||||
@@ -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"`라 기본 조립에 들어가지 않는다.
|
||||
|
||||
@@ -4,68 +4,58 @@ category: TRANSIENT_DEPENDENCY
|
||||
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-11-05
|
||||
status: active
|
||||
last_updated: 2026-11-07
|
||||
status: 운영
|
||||
---
|
||||
|
||||
# Runbook: IDEMPOTENCY_UNAVAILABLE (`runbook://idempotency/unavailable`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 503 (`error.code=IDEMPOTENCY_UNAVAILABLE`, `retryable=true`) on endpoints that take an
|
||||
`Idempotency-Key`; the same code on the gRPC `error-code` trailer (`UNAVAILABLE`).
|
||||
- `IdempotencyExecutor` refused to run the action because the replay store (JPA or Redis, whichever
|
||||
`app.idempotency` selects) did not answer. Nothing was executed: the refusal happens before the
|
||||
action, so a client retry is safe.
|
||||
- The same 503 when the store refused to start a claim whose processing lease had already run out
|
||||
— the request spent longer than the lease between its claim and the start of its action (a
|
||||
stalled process, a slow store call). The ERROR line, `failure classified as
|
||||
IDEMPOTENCY_UNAVAILABLE (…)`, has the exception attached, and the exception's message reads `the
|
||||
claim's processing lease ran out before the action started; nothing ran: <scope>` — in prod JSON
|
||||
logs that is in `stack_trace`, not `message`. The store may be healthy.
|
||||
Nothing ran here either, and the next request with the key takes the claim over and runs it.
|
||||
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` (`retryable=true`) is the same outage hitting after the
|
||||
action ran: the store did not answer while the result was being recorded. When the use case called
|
||||
the executor inside its write transaction, that transaction's database writes rolled back with the
|
||||
exception; an action that committed a transaction of its own kept its writes, and anything outside
|
||||
a transaction (an outbound call, a message) may have happened. This is not "nothing was executed".
|
||||
Clients resend with the same key.
|
||||
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED` (`retryable=false`) means the opposite case: the store
|
||||
cannot tell whether an earlier attempt's effect already happened. Two records produce it:
|
||||
- `ABANDONED`: the action threw, or reported its effect unknown. Final until the record expires.
|
||||
- `EXECUTING` past its processing lease (`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s): the attempt
|
||||
crashed, or is still running longer than the lease. The executor never renews the lease, so a
|
||||
slow but healthy request lands here too. The server never runs it again and does not touch the
|
||||
record. If the attempt is still running and finishes, its result is recorded, the first request
|
||||
gets its normal answer, and later requests with the key get that result replayed; a failure it
|
||||
reports is recorded the same way. So this 500 can stop on its own (owner decision 2026-11-04).
|
||||
This is the Redis store's case. The PostgreSQL store, called inside the use case's write
|
||||
transaction as the template calls it, never shows another request an unfinished record: that
|
||||
request waits for the first transaction to end, and gets the replay if it committed or a fresh
|
||||
run if it rolled back (`docs/web/http-contract.md` §2).
|
||||
- `Idempotency-Key`를 받는 엔드포인트에서 HTTP 503(`error.code=IDEMPOTENCY_UNAVAILABLE`, `retryable=true`).
|
||||
gRPC는 `error-code` trailer에 같은 코드가 온다(`UNAVAILABLE`).
|
||||
- replay 저장소(`app.idempotency`가 고른 JPA나 Redis)가 답하지 않아서 `IdempotencyExecutor`가 action 실행을
|
||||
거절했다. 아무것도 실행되지 않았다. 거절은 action 전에 일어나므로 클라이언트가 다시 시도해도 안전하다.
|
||||
- 처리 lease가 이미 끝난 claim을 저장소가 시작하지 않을 때도 같은 503이다. 요청이 claim과 action 시작 사이에
|
||||
lease보다 오래 걸렸다(멈춘 프로세스, 느린 저장소 호출). ERROR 줄 `failure classified as
|
||||
IDEMPOTENCY_UNAVAILABLE (…)`에 예외가 붙고, 예외 메시지는 `the claim's processing lease ran out before the
|
||||
action started; nothing ran: <scope>`다. prod JSON 로그에서는 `message`가 아니라 `stack_trace`에 있다.
|
||||
저장소는 멀쩡할 수 있다. 이때도 아무것도 실행되지 않았고, 그 키로 오는 다음 요청이 claim을 넘겨받아 실행한다.
|
||||
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(`retryable=true`)은 같은 장애가 action이 실행된 뒤에 닥친 것이다.
|
||||
결과를 기록하는 동안 저장소가 답하지 않았다. use case가 자기 쓰기 트랜잭션 안에서 executor를 불렀으면, 그
|
||||
트랜잭션의 DB 쓰기는 예외와 함께 롤백됐다. 자기 트랜잭션을 따로 커밋한 action은 쓰기가 남았고, 트랜잭션 밖의
|
||||
일(외부 호출, 메시지)은 일어났을 수 있다. 「아무것도 실행되지 않았다」가 아니다. 클라이언트는 같은 키로 다시
|
||||
보낸다.
|
||||
- HTTP 500 `IDEMPOTENCY_RECOVERY_REQUIRED`(`retryable=false`)는 반대 경우다. 앞선 시도의 효과가 이미 일어났는지
|
||||
저장소가 가릴 수 없다. 두 기록이 이 코드를 낸다.
|
||||
- `ABANDONED`: action이 예외를 던졌거나 효과를 모른다고 보고했다. 기록이 만료될 때까지 바뀌지 않는다.
|
||||
- 처리 lease(`APP_IDEMPOTENCY_PROCESSING_LEASE`, 30s)가 지난 `EXECUTING`: 시도가 죽었거나, lease보다 오래 아직
|
||||
돌고 있다. executor는 lease를 늘리지 않으므로 느리지만 멀쩡한 요청도 여기에 온다. 서버는 그 요청을 다시
|
||||
실행하지 않고 기록도 건드리지 않는다. 시도가 아직 돌다가 끝나면 그 결과가 기록되고, 첫 요청은 보통의 응답을
|
||||
받고, 그 키로 오는 뒤의 요청은 그 결과를 replay로 받는다. 시도가 보고한 실패도 같은 식으로 기록된다. 그래서
|
||||
이 500은 저절로 멈출 수 있다(소유자 결정 2026-11-04).
|
||||
이것은 Redis 저장소의 경우다. PostgreSQL 저장소는 템플릿이 부르는 대로 use case의 쓰기 트랜잭션 안에서
|
||||
불리면, 끝나지 않은 기록을 다른 요청에 보이지 않는다. 그 요청은 첫 트랜잭션이 끝나기를 기다렸다가, 커밋됐으면
|
||||
replay를, 롤백됐으면 새 실행을 받는다(`docs/web/http-contract.md` §2).
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check the health of the idempotency store the service uses (`/actuator/health` component of the
|
||||
JPA datasource or Redis, depending on the selected provider).
|
||||
- Look for connection-pool saturation or timeouts on that store in the same time window; the
|
||||
executor reports saturation as unavailable rather than guessing.
|
||||
- For `IDEMPOTENCY_RECOVERY_REQUIRED`, find the scope in the server's ERROR log of the failed request.
|
||||
Every transport writes the same line, `failure classified as IDEMPOTENCY_RECOVERY_REQUIRED
|
||||
(category=DATA_INTEGRITY, retryable=false)`, with the exception attached
|
||||
(shared-contract `ServerFailureLog`), and adds its own correlation:
|
||||
- web: no suffix; the line carries the request's `X-Request-Id` (MDC `request_id`).
|
||||
- gRPC: ` (method=<service>/<method>)`; MDC `request_id` too when the service closed the call on
|
||||
its callback thread.
|
||||
- GraphQL: ` (executionId=<id>)`, the `executionId` the client got in the error's `extensions`.
|
||||
- STOMP (`@MessageMapping`): no suffix; MDC `request_id` is the frame's.
|
||||
- 서비스가 쓰는 멱등성 저장소의 상태를 본다(고른 provider에 따라 JPA datasource나 Redis의 `/actuator/health`
|
||||
구성 요소).
|
||||
- 같은 시간대에 그 저장소의 커넥션 풀 포화나 시간 초과를 찾는다. executor는 포화를 추측하지 않고 사용 불가로
|
||||
보고한다.
|
||||
- `IDEMPOTENCY_RECOVERY_REQUIRED`는 실패한 요청의 서버 ERROR 로그에서 scope를 찾는다. 모든 전송 계층이 같은 줄
|
||||
`failure classified as IDEMPOTENCY_RECOVERY_REQUIRED (category=DATA_INTEGRITY, retryable=false)`에 예외를
|
||||
붙여 쓰고(shared-contract `ServerFailureLog`), 자기 상관 정보를 덧붙인다.
|
||||
- web: 덧붙이는 것이 없다. 줄에 요청의 `X-Request-Id`(MDC `request_id`)가 실린다.
|
||||
- gRPC: ` (method=<service>/<method>)`. 서비스가 callback 스레드에서 호출을 닫았으면 MDC `request_id`도 있다.
|
||||
- GraphQL: ` (executionId=<id>)`. 클라이언트가 오류의 `extensions`에서 받은 `executionId`다.
|
||||
- STOMP(`@MessageMapping`): 덧붙이는 것이 없다. MDC `request_id`는 그 frame의 것이다.
|
||||
|
||||
The exception message ends with
|
||||
`<operation code>::v<digest version>::<scope digest>`, for example
|
||||
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…` (64 hex characters). Then look at the
|
||||
record in the store the service uses (`APP_IDEMPOTENCY_PROVIDER`). There is no tool for this; these
|
||||
are the commands.
|
||||
- Redis. The key, for example `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`, is
|
||||
예외 메시지는 `<operation code>::v<digest version>::<scope digest>`로 끝난다. 예:
|
||||
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…`(16진수 64자). 그다음 서비스가 쓰는 저장소
|
||||
(`APP_IDEMPOTENCY_PROVIDER`)에서 기록을 본다. 이것을 해 주는 도구는 없다. 아래가 그 명령이다.
|
||||
- Redis. 키는 예를 들어 `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`이고, 모양은 다음과 같다.
|
||||
|
||||
<!-- runbook-redis: idempotency-record-key -->
|
||||
```
|
||||
@@ -77,11 +67,10 @@ status: active
|
||||
PTTL <key>
|
||||
```
|
||||
|
||||
`state` `ABANDONED` is final. `state` `EXECUTING` with a `leaseUntil` (lease end, epoch
|
||||
milliseconds, server clock) earlier than the server's `TIME` (first value × 1000) is an attempt
|
||||
past its lease that may still be running. `PTTL` is how long the record still lives, in
|
||||
milliseconds.
|
||||
- PostgreSQL, in the application's schema:
|
||||
`state` `ABANDONED`는 바뀌지 않는다. `state` `EXECUTING`이면서 `leaseUntil`(lease 끝, epoch 밀리초, 서버
|
||||
시계)이 서버의 `TIME`(첫 값 × 1000)보다 이르면, lease가 지났지만 아직 돌고 있을 수 있는 시도다. `PTTL`은
|
||||
기록이 앞으로 살아 있을 시간(밀리초)이다.
|
||||
- PostgreSQL. 애플리케이션의 스키마에서:
|
||||
|
||||
```sql
|
||||
SELECT status, attempt, failure_disposition, last_transition_kind,
|
||||
@@ -91,48 +80,44 @@ status: active
|
||||
AND scope_hash = '<scope digest>';
|
||||
```
|
||||
|
||||
`status` `ABANDONED` with `last_transition_kind` `FAIL_ABANDONED` means the action threw or
|
||||
reported its effect unknown. `status` `EXECUTING` with `processing_lease_until` before
|
||||
`clock_timestamp()` is an attempt past its lease that may still be running. (`ABANDONED` with
|
||||
`EXPIRED_EXECUTION` is a lease that ran out under a version before 2026-11-04, which abandoned
|
||||
such rows; it goes away when the row expires.) `expires_at` is when the reaper deletes the row.
|
||||
`status` `ABANDONED`에 `last_transition_kind` `FAIL_ABANDONED`면 action이 예외를 던졌거나 효과를 모른다고
|
||||
보고했다. `status` `EXECUTING`에 `processing_lease_until`이 `clock_timestamp()`보다 이르면, lease가 지났지만
|
||||
아직 돌고 있을 수 있는 시도다. `expires_at`은 reaper가 행을 지우는 시각이다.
|
||||
|
||||
## Action
|
||||
> 이력: `ABANDONED`에 `EXPIRED_EXECUTION`은 2026-11-04 전 버전에서 lease가 끝난 행이다. 그 버전은 그런 행을
|
||||
> 버렸다. 행이 만료되면 사라진다.
|
||||
|
||||
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff. When
|
||||
the exception message says the claim's processing lease ran out before the action started, the
|
||||
store is not the cause: find what held those requests between claim and start (thread dumps, GC
|
||||
pauses, the store's latency in that window). Nothing to repair; the next same-key request runs.
|
||||
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: restore the store, then check the effects outside the
|
||||
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
|
||||
a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts,
|
||||
and `IDEMPOTENCY_RECOVERY_REQUIRED` after it — handle that one as below.
|
||||
- `IDEMPOTENCY_RECOVERY_REQUIRED`: do not ask the client to retry blindly. If the record is
|
||||
`EXECUTING` past its lease, first wait for the attempt: look the record up again after the
|
||||
longest time the action can take. It changes by itself when the attempt finishes — `COMPLETED`
|
||||
(resends replay it, nothing to do), `ABANDONED`, or `FAILED_RETRYABLE` (the attempt proved it had
|
||||
no effect, and the next request with the key runs it). A crashed attempt, or one whose request
|
||||
already ended with `IDEMPOTENCY_COMPLETION_UNKNOWN`, never changes it; that record stays
|
||||
`EXECUTING` until it expires. Business data checked while the attempt still runs can say "no
|
||||
effect" a moment before the effect lands. Then confirm from business data (the order, the
|
||||
payment, the downstream system) whether the effect exists. There is no way to complete the record
|
||||
by hand — the stored response is the action's own result.
|
||||
- The effect exists: tell the client it was applied. Leave the record; a resend with the key keeps
|
||||
getting this 500 until the record expires (Redis `PTTL`, PostgreSQL `expires_at`).
|
||||
- The effect does not exist: the client sends the request again under a new key. To let the same
|
||||
key run again instead, delete the record — only while it is `ABANDONED`, because any other state
|
||||
belongs to a request that may still be running or to a stored result. Do not delete an
|
||||
`EXECUTING` record, even past its lease: if its attempt is still alive, its late result finds no
|
||||
record (`ABSENT`) — the result is lost, the first request gets this 500 after its work took
|
||||
effect, and the next request with the key runs the work a second time. Leave it to expire.
|
||||
- Redis: check and delete in one step, as the account the service's registered scripts run as
|
||||
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, or the application account when it
|
||||
is unset). Checking with `HMGET` and then sending `DEL` is two commands: a record that expires
|
||||
between them and is claimed again by a new request is deleted while that request runs, and
|
||||
the next request with the key runs the work a second time (re-review 2026-11-04 RR4-03-02).
|
||||
The program below deletes the key only while its `state` is `ABANDONED`. The application
|
||||
accounts are denied `EVAL` (`compose/redis/acl/README.md`), so load it and run it by the
|
||||
digest `SCRIPT LOAD` prints, as the service runs its own scripts:
|
||||
## 조치
|
||||
|
||||
- `IDEMPOTENCY_UNAVAILABLE`: 저장소를 되살린다. 클라이언트는 같은 키로 백오프하며 다시 시도한다. 예외 메시지가
|
||||
action 시작 전에 claim의 처리 lease가 끝났다고 하면 저장소가 원인이 아니다. claim과 시작 사이에 그 요청들을
|
||||
붙잡은 것을 찾는다(스레드 덤프, GC 멈춤, 그 시간대의 저장소 지연). 고칠 것은 없다. 같은 키의 다음 요청이
|
||||
실행된다.
|
||||
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: 저장소를 되살린 뒤, 실패한 요청들의 트랜잭션 밖 효과를 확인한다(ERROR 로그
|
||||
줄이 코드를 알려 준다). 같은 키로 다시 보내면, 실제로 기록된 결과는 replay로 받고, 시도의 lease가 남은 동안은
|
||||
`IDEMPOTENT_IN_FLIGHT`를, 그 뒤에는 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다. 마지막 것은 아래처럼 다룬다.
|
||||
- `IDEMPOTENCY_RECOVERY_REQUIRED`: 클라이언트에게 그냥 다시 시도하라고 하지 않는다. 기록이 lease가 지난
|
||||
`EXECUTING`이면 먼저 시도를 기다린다. action이 걸릴 수 있는 가장 긴 시간이 지난 뒤 기록을 다시 본다. 시도가
|
||||
끝나면 기록은 저절로 바뀐다. `COMPLETED`(다시 보내면 replay된다, 할 일 없음), `ABANDONED`, `FAILED_RETRYABLE`
|
||||
(시도가 효과가 없었음을 증명했고, 그 키의 다음 요청이 실행한다) 중 하나다. 죽은 시도, 또는 요청이 이미
|
||||
`IDEMPOTENCY_COMPLETION_UNKNOWN`으로 끝난 시도는 기록을 바꾸지 않는다. 그 기록은 만료될 때까지 `EXECUTING`으로
|
||||
남는다. 시도가 아직 도는 동안 확인한 업무 데이터는 효과가 들어가기 직전에 「효과 없음」으로 보일 수 있다.
|
||||
그다음 업무 데이터(주문, 결제, 하위 시스템)로 효과가 있는지 확인한다. 기록을 손으로 완료할 방법은 없다. 저장된
|
||||
응답은 action 자신의 결과다.
|
||||
- 효과가 있다: 클라이언트에게 적용됐다고 알린다. 기록은 그대로 둔다. 그 키로 다시 보내면 기록이 만료될 때까지
|
||||
(Redis `PTTL`, PostgreSQL `expires_at`) 이 500을 계속 받는다.
|
||||
- 효과가 없다: 클라이언트가 새 키로 요청을 다시 보낸다. 같은 키로 다시 돌리게 하려면 기록을 지운다. 단
|
||||
`ABANDONED`일 때만 지운다. 다른 상태는 아직 돌고 있을 수 있는 요청이나 저장된 결과의 것이다. `EXECUTING`
|
||||
기록은 lease가 지났어도 지우지 않는다. 그 시도가 아직 살아 있으면 늦게 온 결과가 기록을 찾지 못하고
|
||||
(`ABSENT`) 결과가 사라진다. 첫 요청은 일이 적용된 뒤에 이 500을 받고, 그 키의 다음 요청이 일을 한 번 더
|
||||
한다. 만료되게 둔다.
|
||||
- Redis: 확인과 삭제를 한 단계로, 서비스에 등록된 스크립트가 도는 계정으로 한다
|
||||
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, 비어 있으면 애플리케이션 계정). `HMGET`으로
|
||||
확인하고 `DEL`을 보내면 명령이 둘이다. 그 사이에 만료되어 새 요청이 다시 claim한 기록은 그 요청이 도는
|
||||
동안 지워지고, 그 키의 다음 요청이 일을 한 번 더 한다(2026-11-04 재확인 리뷰 RR4-03-02). 아래 프로그램은
|
||||
`state`가 `ABANDONED`일 때만 키를 지운다. 애플리케이션 계정은 `EVAL`이 막혀 있으므로
|
||||
(`compose/redis/acl/README.md`), 서비스가 자기 스크립트를 돌리는 것처럼 불러 올리고 `SCRIPT LOAD`가 찍은
|
||||
digest로 돌린다.
|
||||
|
||||
<!-- runbook-redis: idempotency-delete-abandoned -->
|
||||
```
|
||||
@@ -140,11 +125,10 @@ status: active
|
||||
EVALSHA <digest SCRIPT LOAD printed> 1 <key>
|
||||
```
|
||||
|
||||
`1` deleted the record; the key is new. `0` deleted nothing: the record is no longer
|
||||
`ABANDONED` (or is gone) — look again before doing anything else. `NOSCRIPT` means the node
|
||||
that holds the key (a cluster) has not loaded the program: run `SCRIPT LOAD` on that node and
|
||||
`EVALSHA` again; nothing was deleted. A record that is about to expire needs nothing; once it
|
||||
is gone the key is new.
|
||||
`1`이면 기록을 지웠고 키는 새것이다. `0`이면 아무것도 지우지 않았다. 기록이 더는 `ABANDONED`가 아니다
|
||||
(또는 없다). 다른 일을 하기 전에 다시 본다. `NOSCRIPT`는 키를 가진 노드(클러스터)가 프로그램을 불러 올리지
|
||||
않았다는 뜻이다. 그 노드에서 `SCRIPT LOAD`를 돌리고 `EVALSHA`를 다시 한다. 아무것도 지워지지 않았다. 곧
|
||||
만료될 기록은 할 일이 없다. 사라지면 키는 새것이다.
|
||||
- PostgreSQL:
|
||||
|
||||
```sql
|
||||
@@ -154,12 +138,12 @@ status: active
|
||||
AND status = 'ABANDONED';
|
||||
```
|
||||
|
||||
Without either step the key is released when the record expires. A record whose attempt never
|
||||
finished lives for the processing lease plus `APP_IDEMPOTENCY_TTL` from its claim; one the action
|
||||
marked failed lives for `APP_IDEMPOTENCY_FAILURE_RETENTION` (not shorter than `APP_IDEMPOTENCY_TTL`)
|
||||
from the failure (`docs/web/http-contract.md`, "서버가 기억하는 기간").
|
||||
어느 단계도 하지 않으면 기록이 만료될 때 키가 풀린다. 시도가 끝나지 않은 기록은 claim부터 처리 lease에
|
||||
`APP_IDEMPOTENCY_TTL`을 더한 만큼 산다. action이 실패로 표시한 기록은 실패부터
|
||||
`APP_IDEMPOTENCY_FAILURE_RETENTION`(`APP_IDEMPOTENCY_TTL`보다 짧지 않다)만큼 산다
|
||||
(`docs/web/http-contract.md` 「서버가 기억하는 기간」).
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P2 → P1 when the store stays unavailable for more than 10 minutes on a write path.
|
||||
- Page the owner of the idempotency store (database or Redis on-call).
|
||||
- 쓰기 경로에서 저장소가 10분 넘게 사용 불가로 남으면 P2 → P1.
|
||||
- 멱등성 저장소 소유자(DB나 Redis 당번)를 부른다.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`)
|
||||
|
||||
@@ -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`)
|
||||
|
||||
@@ -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`)
|
||||
|
||||
@@ -5,34 +5,34 @@ error_codes: [LOCK_ACQUISITION_TIMEOUT]
|
||||
severity: P2
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: LOCK_ACQUISITION_TIMEOUT (`runbook://lock/acquisition-timeout`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- HTTP 409 with `error.code=LOCK_ACQUISITION_TIMEOUT` and `Retry-After: 1`; GraphQL extension
|
||||
`code=LOCK_ACQUISITION_TIMEOUT`, gRPC trailer `error-code: LOCK_ACQUISITION_TIMEOUT` (`ABORTED`), all
|
||||
`retryable=true`.
|
||||
- No server log line. A 4xx answer is not an incident, so no transport logs it, and the lock adapters
|
||||
do not log a timeout either. The exception's message (lock key, wait time) reaches no log and no
|
||||
client, so which lock timed out is recorded nowhere. Read the metric and the lock table below.
|
||||
- Before 2026-11-07 the template answered this as 500 `INTERNAL_ERROR` with an "unhandled exception"
|
||||
ERROR line (the exception was not an `ApiErrorCarrier`). A service on an older template sees that
|
||||
instead.
|
||||
- Distributed lock wait exceeded configured timeout; high contention on a resource
|
||||
- HTTP 409, `error.code=LOCK_ACQUISITION_TIMEOUT`, `Retry-After: 1`. GraphQL은 extension
|
||||
`code=LOCK_ACQUISITION_TIMEOUT`, gRPC는 trailer `error-code: LOCK_ACQUISITION_TIMEOUT`(`ABORTED`)이고, 모두
|
||||
`retryable=true`다.
|
||||
- 서버 로그 줄이 없다. 4xx 응답은 장애가 아니라서 어느 전송 계층도 로그를 남기지 않고, 락 어댑터도 시간 초과를
|
||||
로그에 쓰지 않는다. 예외 메시지(락 키, 대기 시간)는 어느 로그에도 클라이언트에도 닿지 않으므로 어느 락이
|
||||
시간을 넘겼는지는 어디에도 기록되지 않는다. 아래의 메트릭과 락 테이블을 읽는다.
|
||||
- 분산 락 대기가 설정된 시간 상한을 넘었다. 한 자원에 경합이 심하다.
|
||||
|
||||
## Diagnosis
|
||||
> 이력: 2026-11-07 전의 템플릿은 이 경우를 500 `INTERNAL_ERROR`와 "unhandled exception" ERROR 줄로
|
||||
> 응답했다(예외가 `ApiErrorCarrier`가 아니었다). 옛 템플릿을 쓰는 서비스에서는 그것이 보인다.
|
||||
|
||||
1. Contention rate. With `APP_MULTI_INSTANCE_ENABLED=true` the JDBC lock is metered: compare
|
||||
`lock.acquisition{outcome="timeout"}` with `lock.acquisition{outcome="acquired"}`. The counter has
|
||||
no lock name and no wait time — a key is never a metric tag (`docs/registries/metrics.yaml`). The
|
||||
in-process lock (`APP_MULTI_INSTANCE_ENABLED=false`, the default) has no metric and keeps nothing in
|
||||
the database; the steps below apply only to the JDBC lock.
|
||||
2. Who holds locks now. `INT_LOCK` has one row per held lock. `CLIENT_ID` is the holding instance's
|
||||
lock repository id, and the times are UTC. A row whose `EXPIRED_AFTER` has passed is a dead lease:
|
||||
the next acquisition of that key takes it over. The oldest live rows are the long holders.
|
||||
## 진단
|
||||
|
||||
1. 경합 비율. `APP_MULTI_INSTANCE_ENABLED=true`이면 JDBC 락에 메트릭이 붙는다.
|
||||
`lock.acquisition{outcome="timeout"}`을 `lock.acquisition{outcome="acquired"}`와 비교한다. 이 counter에는
|
||||
락 이름도 대기 시간도 없다. 키는 메트릭 태그가 되지 않는다(`docs/registries/metrics.yaml`). 프로세스 안 락
|
||||
(`APP_MULTI_INSTANCE_ENABLED=false`, 기본값)은 메트릭이 없고 DB에 아무것도 남기지 않는다. 아래 단계는 JDBC
|
||||
락에만 해당한다.
|
||||
2. 지금 누가 락을 쥐고 있나. `INT_LOCK`에는 쥔 락마다 한 행이 있다. `CLIENT_ID`는 쥔 인스턴스의 락 저장소 id이고,
|
||||
시각은 UTC다. `EXPIRED_AFTER`가 지난 행은 죽은 lease다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된
|
||||
살아 있는 행이 오래 쥔 쪽이다.
|
||||
|
||||
<!-- runbook-sql: lock-holders -->
|
||||
```sql
|
||||
@@ -41,10 +41,9 @@ FROM int_lock
|
||||
ORDER BY created_date;
|
||||
```
|
||||
|
||||
3. The holder of one lock whose key you know from the code (for example `orders/42`). `LOCK_KEY` is
|
||||
not the key: Spring Integration stores the key's name-based UUID (`UUID.nameUUIDFromBytes` of the
|
||||
key's UTF-8 bytes), so a key cannot be read back from the table. This computes the UUID from the
|
||||
key and finds its row:
|
||||
3. 코드에서 키를 아는 락 하나(예: `orders/42`)를 누가 쥐고 있나. `LOCK_KEY`는 키 자체가 아니다. Spring
|
||||
Integration은 키의 이름 기반 UUID(키의 UTF-8 바이트에 `UUID.nameUUIDFromBytes`)를 저장하므로 테이블에서 키를
|
||||
거꾸로 읽을 수 없다. 아래 쿼리는 키에서 UUID를 계산해 그 행을 찾는다.
|
||||
|
||||
<!-- runbook-sql: lock-holder-of-key -->
|
||||
```sql
|
||||
@@ -56,18 +55,18 @@ WHERE lock_key = (
|
||||
FROM md5('<lock_key>') AS h);
|
||||
```
|
||||
|
||||
`:adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest` runs both blocks, read
|
||||
from this file, against real PostgreSQL while locks are held.
|
||||
`:adapter:outbound:persistence-jpa:postgresqlDistributedLockIntegrationTest`가 두 블록을 이 파일에서 읽어,
|
||||
락을 쥔 상태의 실제 PostgreSQL에 돌린다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Client should retry with backoff (retryable=true)
|
||||
- Optimize critical section holding time if lock contention is systemic
|
||||
- 클라이언트는 백오프하며 다시 시도한다(retryable=true).
|
||||
- 락 경합이 구조적이면 임계 구역을 쥐는 시간을 줄인다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- Escalate if lock holder appears stuck (potential deadlock in distributed lock)
|
||||
- 락 보유자가 멈춘 것으로 보이면 넘긴다(분산 락의 교착 가능성).
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,27 +5,25 @@ error_codes: [MIGRATION_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-11-07
|
||||
status: active
|
||||
status: 운영
|
||||
---
|
||||
|
||||
# Runbook: MIGRATION_FAILED (`runbook://migration/failed`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- Container exits with code 70 (migration failure exit)
|
||||
- Structured log with `error.code=MIGRATION_FAILED`, `startup.phase=migration`
|
||||
- App refuses to start (fail-fast)
|
||||
- JPA capability adapter refuses activation because its
|
||||
`capability_schema_registry.lifecycle_state` is not `ACTIVE`
|
||||
- 컨테이너가 코드 70으로 끝난다(마이그레이션 실패 종료).
|
||||
- 구조화 로그 `error.code=MIGRATION_FAILED`, `startup.phase=migration`.
|
||||
- 앱이 뜨기를 거부한다(fail-fast).
|
||||
- JPA capability 어댑터가 활성화를 거부한다. 그 `capability_schema_registry.lifecycle_state`가 `ACTIVE`가 아니다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
1. Stop rollout and keep the failed revision out of readiness. Do not route traffic to a partially
|
||||
migrated instance.
|
||||
2. Identify the exact stream from `src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml`. Each stream has an
|
||||
independent `location` and `history-table`; do not infer ownership from a broad
|
||||
`classpath:db/migration` scan.
|
||||
3. From a privileged migration session, capture the stream state before changing anything:
|
||||
1. rollout을 멈추고, 실패한 revision을 readiness 밖에 둔다. 마이그레이션이 반쯤 된 인스턴스로 트래픽을 보내지
|
||||
않는다.
|
||||
2. `src/adapter/outbound/persistence-jpa/release/readiness-cards.yaml`에서 정확한 stream을 찾는다. stream마다
|
||||
`location`과 `history-table`이 따로 있다. 넓은 `classpath:db/migration` 스캔으로 소유를 짐작하지 않는다.
|
||||
3. 권한 있는 마이그레이션 세션에서, 무엇이든 바꾸기 전에 stream 상태를 남긴다.
|
||||
|
||||
```sql
|
||||
select installed_rank, version, description, success
|
||||
@@ -37,15 +35,14 @@ status: active
|
||||
where capability_id = '<card-id>';
|
||||
```
|
||||
|
||||
4. Check whether any owned relation was created without a successful history entry. Compare only
|
||||
against the owned tables in the reviewed migration; do not drop unrelated relations.
|
||||
5. Classify the failure:
|
||||
- lock/statement timeout: remove the blocker or reduce rollout concurrency, then rerun. A
|
||||
migration that locks a table already in use gives up after its own `SET LOCAL lock_timeout`
|
||||
(5 s; SQLState `55P03` `lock_not_available`) and rolls back whole, so the history ends one
|
||||
version below it. The blocker is a transaction that touched the table and is still open —
|
||||
often an idle-in-transaction session. Find it by the lock it holds on that table (`<table>`
|
||||
is the table the failing statement locks; for a `REFERENCES`, also the table it references):
|
||||
4. 성공한 이력 행 없이 만들어진 소유 relation이 있는지 확인한다. 검토한 마이그레이션의 소유 테이블과만
|
||||
비교한다. 상관없는 relation은 지우지 않는다.
|
||||
5. 실패를 분류한다(Classify the failure).
|
||||
- 락·문장 시간 초과: 막는 쪽을 없애거나 rollout 동시성을 줄이고 다시 돌린다. 이미 쓰는 테이블을 잠그는
|
||||
마이그레이션은 자기 `SET LOCAL lock_timeout`(5 s, SQLState `55P03` `lock_not_available`)이 지나면 포기하고
|
||||
통째로 롤백한다. 그래서 이력은 그 버전 바로 아래에서 끝난다. 막는 쪽은 그 테이블을 건드린 뒤 아직 열려 있는
|
||||
트랜잭션이다. 흔히 idle-in-transaction 세션이다. 그 테이블에 쥔 락으로 찾는다(`<table>`은 실패한 문장이
|
||||
잠그는 테이블이다. `REFERENCES`면 참조하는 테이블도 본다).
|
||||
|
||||
```sql
|
||||
SELECT DISTINCT a.pid, a.state, a.xact_start, a.query
|
||||
@@ -54,74 +51,65 @@ status: active
|
||||
ORDER BY a.xact_start;
|
||||
```
|
||||
|
||||
`query` is only that session's last statement, not the one that touched the table, so do not
|
||||
look for the table name in it. Listing every long transaction instead names unrelated ones
|
||||
(reports, batches) beside the blocker. End the blocker, then rerun
|
||||
(`docs/jpa/migration-guide.md` "Bound the lock wait");
|
||||
- SQL/data precondition: create a new forward migration that makes the precondition explicit;
|
||||
a duplicate outbox order key stopping V21 (`ux_outbox_event_aggregate_order`) is the known
|
||||
case — clean it up with `outbox-dead-letter.md` §8 and rerun, the migration stays as it is;
|
||||
- checksum mismatch: compare the deployed artifact with the already applied script before
|
||||
considering repair;
|
||||
- a concurrent index migration failed (`CREATE [UNIQUE] INDEX CONCURRENTLY`, `DROP INDEX
|
||||
CONCURRENTLY` or `REINDEX … CONCURRENTLY` that Flyway ran outside a transaction): a duplicate
|
||||
value for a unique index, a deadlock, `statement_timeout` or a statement cancelled while it
|
||||
waited for an open transaction. Outside a transaction nothing rolled back: the migration left
|
||||
an invalid index and a history row with `success = false` for that version, and every later
|
||||
deploy fails validation ("Detected failed migration to version …") until the row is gone.
|
||||
Dropping the index alone does not clear it. Follow "Recover a failed concurrent index
|
||||
migration" below;
|
||||
- connection/TLS failure: fix transport or credentials without changing Flyway history.
|
||||
`query`는 그 세션의 마지막 문장일 뿐 테이블을 건드린 문장이 아니므로, 거기서 테이블 이름을 찾지 않는다.
|
||||
대신 긴 트랜잭션을 모두 나열하면 막는 쪽 옆에 상관없는 것(리포트, 배치)도 나온다. 막는 쪽을 끝낸 뒤 다시
|
||||
돌린다(`docs/jpa/migration-guide.md` "Bound the lock wait").
|
||||
- SQL·데이터 전제 조건: 전제 조건을 드러내는 새 forward 마이그레이션을 만든다. 중복된 outbox 순서 키가
|
||||
V21(`ux_outbox_event_aggregate_order`)을 막는 것이 알려진 경우다. `outbox-dead-letter.md` §8로 정리하고 다시
|
||||
돌린다. 마이그레이션은 그대로 둔다.
|
||||
- checksum 불일치: repair를 생각하기 전에 배포한 산출물과 이미 적용된 스크립트를 비교한다.
|
||||
- 동시 인덱스 마이그레이션 실패(Flyway가 트랜잭션 밖에서 돌린 `CREATE [UNIQUE] INDEX CONCURRENTLY`,
|
||||
`DROP INDEX CONCURRENTLY`, `REINDEX … CONCURRENTLY`): unique 인덱스의 중복 값, 교착, `statement_timeout`,
|
||||
또는 열린 트랜잭션을 기다리다 취소된 문장이다. 트랜잭션 밖이라 아무것도 롤백되지 않았다. 마이그레이션은
|
||||
무효 인덱스와, 그 버전의 `success = false` 이력 행을 남겼다. 그 행이 사라질 때까지 뒤의 배포는 모두 검증에서
|
||||
실패한다("Detected failed migration to version …"). 인덱스만 지워서는 풀리지 않는다. 아래 「실패한 동시
|
||||
인덱스 마이그레이션 복구」를 따른다.
|
||||
- 연결·TLS 실패: Flyway 이력을 바꾸지 않고 전송이나 자격 증명을 고친다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
1. Prefer forward recovery. Fix the environmental blocker or add a new immutable migration, then
|
||||
rerun the same owned stream with its exact history table.
|
||||
2. For an optional stream that never installed successfully, keep the capability marker absent and
|
||||
the runtime adapter disabled until migration succeeds.
|
||||
3. After a successful migration, validate:
|
||||
- the history contains only successful expected versions;
|
||||
- `core_epoch` and `feature_revision` match the readiness registry;
|
||||
- the marker is `INSTALLED_INACTIVE`;
|
||||
- owned objects and constraints exist.
|
||||
4. Change the marker to `ACTIVE` only after the compatible application revision is deployed and its
|
||||
readiness check succeeds. Disabling or rolling back application code changes the marker to
|
||||
`INSTALLED_INACTIVE`; it does not drop history or owned data.
|
||||
5. Re-run the readiness lanes before promoting (every card's scenarios, no skips):
|
||||
1. forward 복구를 먼저 쓴다. 환경 쪽 막힘을 고치거나 바뀌지 않는 새 마이그레이션을 더한 뒤, 같은 소유 stream을
|
||||
그 정확한 이력 테이블로 다시 돌린다.
|
||||
2. 한 번도 성공적으로 설치되지 않은 선택 stream은 마이그레이션이 성공할 때까지 capability 표시를 두지 않고 런타임
|
||||
어댑터를 꺼 둔다.
|
||||
3. 마이그레이션이 성공하면 확인한다.
|
||||
- 이력에 기대한 버전의 성공 행만 있다.
|
||||
- `core_epoch`와 `feature_revision`이 readiness registry와 같다.
|
||||
- 표시가 `INSTALLED_INACTIVE`다.
|
||||
- 소유 객체와 제약이 있다.
|
||||
4. 맞는 애플리케이션 revision이 배포되고 그 readiness 검사가 성공한 뒤에만 표시를 `ACTIVE`로 바꾼다.
|
||||
애플리케이션 코드를 끄거나 되돌리면 표시가 `INSTALLED_INACTIVE`로 바뀐다. 이력이나 소유 데이터는 지우지 않는다.
|
||||
5. 승격 전에 readiness lane을 다시 돌린다(모든 card의 시나리오, 건너뜀 없음).
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain
|
||||
```
|
||||
|
||||
6. Record the failed revision, stream/history table, root cause, recovery migration, elapsed time
|
||||
and verification artifact in the incident.
|
||||
6. 실패한 revision, stream·이력 테이블, 근본 원인, 복구 마이그레이션, 걸린 시간, 검증 산출물을 장애 기록에 남긴다.
|
||||
|
||||
Do not:
|
||||
하지 않을 것:
|
||||
|
||||
- edit an already applied migration;
|
||||
- delete or rewrite Flyway history to make validation green. The one exception is the failed row
|
||||
of a failed concurrent index migration, deleted as "Recover a failed concurrent index migration"
|
||||
below says — that row and nothing else;
|
||||
- run `flyway repair` before checksum provenance is proven and reviewed;
|
||||
- use `clean`, destructive rollback, or schema-wide restore as the first response;
|
||||
- mark a capability `ACTIVE` before its migration and adapter readiness succeed.
|
||||
- 이미 적용된 마이그레이션을 고친다.
|
||||
- 검증을 통과시키려고 Flyway 이력을 지우거나 다시 쓴다. 예외는 하나다. 실패한 동시 인덱스 마이그레이션의 실패
|
||||
행을 아래 「실패한 동시 인덱스 마이그레이션 복구」대로 지운다. 그 행 말고는 아무것도 지우지 않는다.
|
||||
- checksum의 출처가 증명되고 검토되기 전에 `flyway repair`를 돌린다.
|
||||
- 첫 대응으로 `clean`, 파괴적 롤백, 스키마 전체 복원을 쓴다.
|
||||
- 마이그레이션과 어댑터 readiness가 성공하기 전에 capability를 `ACTIVE`로 표시한다.
|
||||
|
||||
If commit outcome was indeterminate during the failure, reconcile by the application
|
||||
`OperationId`/idempotency reference before retrying business work. Never blind-retry a commit whose
|
||||
result is unknown.
|
||||
장애 중에 커밋 결과를 알 수 없었으면, 업무 작업을 다시 하기 전에 애플리케이션의 `OperationId`·멱등성 참조로
|
||||
맞춘다. 결과를 모르는 커밋을 그냥 다시 시도하지 않는다.
|
||||
|
||||
## Recover a failed concurrent index migration
|
||||
## 실패한 동시 인덱스 마이그레이션 복구 (Recover a failed concurrent index migration)
|
||||
|
||||
The one case where this runbook changes Flyway history (owner decision, 2026-11-06). It applies to a
|
||||
migration that holds a single concurrent index statement which Flyway ran outside a transaction —
|
||||
with the `executeInTransaction=false` the guide asks for, or on its own for `CREATE`/`DROP INDEX
|
||||
CONCURRENTLY` (`docs/jpa/migration-guide.md` "Concurrent index builds") — and whose row for this
|
||||
version in the stream's history table says `success = false`. A migration that mixed other
|
||||
statements in has already committed them: reconstruct that state with the database owner instead.
|
||||
이 runbook이 Flyway 이력을 바꾸는 유일한 경우다(소유자 결정, 2026-11-06). Flyway가 트랜잭션 밖에서 돌린 동시
|
||||
인덱스 문장 하나만 담은 마이그레이션에 쓴다. 가이드가 요구하는 `executeInTransaction=false`로 돌렸거나,
|
||||
`CREATE`/`DROP INDEX CONCURRENTLY`라서 Flyway가 알아서 그렇게 돌린 경우다(`docs/jpa/migration-guide.md`
|
||||
"Concurrent index builds"). 그리고 stream 이력 테이블의 이 버전 행이 `success = false`여야 한다. 다른 문장을 섞은
|
||||
마이그레이션은 그 문장을 이미 커밋했다. 그 상태는 DB 소유자와 함께 다시 맞춘다.
|
||||
|
||||
1. Confirm no build is still running. An index that is still being built looks invalid in the
|
||||
catalog too, and dropping it races the build. This query returns no rows when none is:
|
||||
1. 아직 도는 빌드가 없는지 확인한다. 아직 만드는 중인 인덱스도 카탈로그에서는 무효로 보이고, 그것을 지우면
|
||||
빌드와 경합한다. 도는 빌드가 없으면 이 쿼리는 행을 돌려주지 않는다.
|
||||
|
||||
<!-- runbook-sql: failed-concurrent-index-builds -->
|
||||
```sql
|
||||
@@ -130,29 +118,26 @@ FROM pg_stat_progress_create_index
|
||||
WHERE datname = current_database();
|
||||
```
|
||||
|
||||
2. Remove the cause. For a unique index, clean up the duplicate rows with the data owner (a forward
|
||||
fix, never by editing the migration). For a deadlock, a timeout or a cancelled statement, end or
|
||||
wait out the transaction that held it: a build or a rebuild waits for every transaction older
|
||||
than itself, a drop for every transaction that holds a lock on its table. Do this before step 3,
|
||||
whose `DROP INDEX CONCURRENTLY` waits for the same transactions.
|
||||
3. Drop the invalid index a failed build or rebuild left: the index a `CREATE [UNIQUE] INDEX
|
||||
CONCURRENTLY` names, or the copy a `REINDEX … CONCURRENTLY` made, named after the index with
|
||||
`_ccnew` (or `_ccold`) on the end (`docs/jpa/runbooks.md` "An invalid index exists" lists them).
|
||||
Run it on its own, not inside `BEGIN`: `CONCURRENTLY` refuses a transaction block.
|
||||
**Skip this step when the failed statement is `DROP INDEX CONCURRENTLY`.** The invalid index it
|
||||
left is the index the migration drops, and the deploy in step 5 runs the same statement, which
|
||||
drops it. Dropped by hand first, that statement fails with `42704` ("index … does not exist")
|
||||
and leaves a new failed row.
|
||||
2. 원인을 없앤다. unique 인덱스면 데이터 소유자와 중복 행을 정리한다(forward 수정이다. 마이그레이션을 고치지
|
||||
않는다). 교착, 시간 초과, 취소된 문장이면 그것을 쥔 트랜잭션을 끝내거나 끝나기를 기다린다. 빌드와 재빌드는
|
||||
자기보다 오래된 트랜잭션을 모두 기다리고, 삭제는 그 테이블에 락을 쥔 트랜잭션을 모두 기다린다. 3단계 전에
|
||||
한다. 3단계의 `DROP INDEX CONCURRENTLY`도 같은 트랜잭션을 기다린다.
|
||||
3. 실패한 빌드나 재빌드가 남긴 무효 인덱스를 지운다. `CREATE [UNIQUE] INDEX CONCURRENTLY`가 이름 붙인 인덱스,
|
||||
또는 `REINDEX … CONCURRENTLY`가 만든 사본이다. 사본은 인덱스 이름 끝에 `_ccnew`(또는 `_ccold`)가 붙는다
|
||||
(`docs/jpa/runbooks.md` "An invalid index exists"가 그 목록을 준다). `BEGIN` 안이 아니라 따로 돌린다.
|
||||
`CONCURRENTLY`는 트랜잭션 블록을 거부한다.
|
||||
**실패한 문장이 `DROP INDEX CONCURRENTLY`면 이 단계를 건너뛴다.** 그것이 남긴 무효 인덱스는 마이그레이션이
|
||||
지우는 인덱스이고, 5단계의 배포가 같은 문장을 돌려 그것을 지운다. 먼저 손으로 지우면 그 문장이 `42704`
|
||||
("index … does not exist")로 실패하고 새 실패 행을 남긴다.
|
||||
|
||||
<!-- runbook-sql: failed-concurrent-index-drop -->
|
||||
```sql
|
||||
DROP INDEX CONCURRENTLY IF EXISTS <invalid_index>;
|
||||
```
|
||||
|
||||
4. Delete that version's failed row from the stream's history table, and nothing else. `<version>`
|
||||
is the `version` column of the failed row as the Diagnosis query shows it (`22.1` for
|
||||
`V22_1__…`). It must delete exactly one row; if it deletes none, this is not the failure this
|
||||
section is for, so classify it again.
|
||||
4. stream 이력 테이블에서 그 버전의 실패 행을 지운다. 그 밖에는 아무것도 지우지 않는다. `<version>`은 진단
|
||||
쿼리가 보여 주는 실패 행의 `version` 칸이다(`V22_1__…`이면 `22.1`). 정확히 한 행을 지워야 한다. 한 행도 지우지
|
||||
않으면 이 절이 다루는 실패가 아니므로 다시 분류한다.
|
||||
|
||||
<!-- runbook-sql: failed-concurrent-index-history-row -->
|
||||
```sql
|
||||
@@ -160,28 +145,24 @@ DELETE FROM <owned_history_table>
|
||||
WHERE version = '<version>' AND NOT success;
|
||||
```
|
||||
|
||||
5. Deploy again. Flyway runs the same migration from the start: it builds the index, rebuilds it,
|
||||
or drops the index the failed drop left.
|
||||
5. 다시 배포한다. Flyway가 같은 마이그레이션을 처음부터 돌린다. 인덱스를 만들거나, 다시 만들거나, 실패한
|
||||
삭제가 남긴 인덱스를 지운다.
|
||||
|
||||
The failed row is the record of a version that never applied, so deleting it leaves the order and
|
||||
the checksum of every applied version as they were. Do not use `flyway repair` for this: it also
|
||||
rewrites the checksums and descriptions of the remaining rows to match the scripts on disk, which
|
||||
removes the evidence a checksum mismatch carries. `:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`
|
||||
runs the three SQL blocks above, read from this file, against real PostgreSQL for each statement
|
||||
this section covers: a unique build that fails on a duplicate, and a rebuild and a drop cancelled
|
||||
while they wait for an open transaction. Steps 1–4 run in order, step 3 for the build and the
|
||||
rebuild only, and the next deploy applies the version with no invalid index left and the earlier
|
||||
version's checksum unchanged.
|
||||
실패 행은 한 번도 적용되지 않은 버전의 기록이다. 그래서 지워도 적용된 모든 버전의 순서와 checksum은 그대로다.
|
||||
이 일에 `flyway repair`를 쓰지 않는다. repair는 남은 행의 checksum과 description도 디스크의 스크립트에 맞춰 다시
|
||||
쓰므로, checksum 불일치가 담은 증거를 지운다.
|
||||
`:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`가 위의 SQL 블록 셋을 이
|
||||
파일에서 읽어, 이 절이 다루는 문장마다 실제 PostgreSQL에 돌린다. 중복으로 실패하는 unique 빌드, 열린 트랜잭션을
|
||||
기다리다 취소된 재빌드와 삭제다. 1~4단계를 차례로 돌리고(3단계는 빌드와 재빌드만), 다음 배포가 무효 인덱스 없이
|
||||
그 버전을 적용하며 앞 버전의 checksum은 바뀌지 않는다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1 immediate: the required application revision cannot become ready.
|
||||
- Escalate to the database owner before Flyway history repair, destructive DDL, point-in-time
|
||||
recovery, or primary failover.
|
||||
- R3 restore/PITR and failover rehearsal requires a target-like backup topology; local
|
||||
Testcontainers evidence is not a substitute.
|
||||
- P1 즉시: 필요한 애플리케이션 revision이 ready가 되지 못한다.
|
||||
- Flyway 이력 repair, 파괴적 DDL, 시점 복구(PITR), primary failover 전에 DB 소유자에게 넘긴다.
|
||||
- R3 복원·PITR과 failover 예행연습에는 대상과 비슷한 백업 구성이 필요하다. 로컬 Testcontainers 증거로 대신하지
|
||||
않는다.
|
||||
|
||||
---
|
||||
|
||||
This runbook is forward-only. The reviewed migration artifact and the readiness lanes' JUnit
|
||||
results from CI are the audit sources.
|
||||
이 runbook은 forward 방향만 다룬다. 감사 근거는 검토한 마이그레이션 산출물과 CI의 readiness lane JUnit 결과다.
|
||||
|
||||
@@ -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`)
|
||||
|
||||
@@ -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`)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`)
|
||||
|
||||
@@ -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)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,31 +5,31 @@ error_codes: [PROFILE_MISMATCH]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: PROFILE_MISMATCH (`runbook://startup/profile-mismatch`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- Container exits with code 71 (profile mismatch exit)
|
||||
- Structured log with `error.code=PROFILE_MISMATCH`, `startup.phase=profile-check`
|
||||
- Production profile active with local-only settings enabled
|
||||
- 컨테이너가 코드 71로 끝난다(프로파일 불일치 종료).
|
||||
- 구조화 로그 `error.code=PROFILE_MISMATCH`, `startup.phase=profile-check`.
|
||||
- 운영 프로파일이 켜져 있는데 로컬 전용 설정이 켜져 있다.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check active Spring profiles (`spring.profiles.active`)
|
||||
- Identify which local-only setting is incorrectly enabled in prod profile
|
||||
- 켜진 Spring 프로파일(`spring.profiles.active`)을 확인한다.
|
||||
- 운영 프로파일에서 잘못 켜진 로컬 전용 설정을 찾는다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Remove local-only setting from production deployment config
|
||||
- Ensure prod profile does not inherit local/dev profile settings
|
||||
- 운영 배포 설정에서 로컬 전용 설정을 지운다.
|
||||
- 운영 프로파일이 local·dev 프로파일 설정을 물려받지 않게 한다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1: security risk if local settings expose debug endpoints in production
|
||||
- P1: 로컬 설정이 운영에서 디버그 엔드포인트를 열면 보안 위험이다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -4,31 +4,31 @@ category: INTERNAL
|
||||
error_codes: [REQUIRED_ADAPTER_DISABLED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
last_updated: 2026-11-07
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: REQUIRED_ADAPTER_DISABLED (`runbook://startup/required-adapter-disabled`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- Container exits with code 72 (required adapter disabled exit)
|
||||
- Structured log with `error.code=REQUIRED_ADAPTER_DISABLED`, `startup.phase=adapter-check`
|
||||
- 컨테이너가 코드 72로 끝난다(필수 어댑터 비활성화 종료).
|
||||
- 구조화 로그 `error.code=REQUIRED_ADAPTER_DISABLED`, `startup.phase=adapter-enablement`.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Identify which adapter is disabled but required
|
||||
- Check adapter enable flags in environment config
|
||||
- 필수인데 꺼진 어댑터를 찾는다.
|
||||
- 환경 설정의 어댑터 스위치를 확인한다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Enable required adapter in deployment configuration
|
||||
- If adapter is intentionally disabled, update the required/optional designation
|
||||
- 배포 설정에서 필수 어댑터를 켠다.
|
||||
- 일부러 끈 어댑터면 필수·선택 지정을 고친다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1: app cannot start; coordinate with deployment team
|
||||
- P1: 앱이 뜨지 못한다. 배포 팀과 맞춘다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
@@ -5,30 +5,30 @@ error_codes: [STARTUP_VALIDATION_FAILED]
|
||||
severity: P1
|
||||
owner: oncall
|
||||
last_updated: 2026-06-15
|
||||
status: stub
|
||||
status: 초안
|
||||
---
|
||||
|
||||
# Runbook: STARTUP_VALIDATION_FAILED (`runbook://startup/validation-failed`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- Container exits with code 78 (env validation failure exit)
|
||||
- Structured log with `error.code=STARTUP_VALIDATION_FAILED`, `startup.phase=env-validation`
|
||||
- 컨테이너가 코드 78로 끝난다(환경 변수 검증 실패 종료).
|
||||
- 구조화 로그 `error.code=STARTUP_VALIDATION_FAILED`, `startup.phase=env-validation`.
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Check which required env variable is missing or malformed
|
||||
- Review container environment and secrets injection
|
||||
- 빠졌거나 형식이 틀린 필수 환경 변수를 찾는다.
|
||||
- 컨테이너 환경과 secret 주입을 확인한다.
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Supply missing environment variables to deployment
|
||||
- Verify secrets are correctly mounted / injected
|
||||
- 빠진 환경 변수를 배포에 넣는다.
|
||||
- secret이 제대로 마운트·주입됐는지 확인한다.
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- P1: app cannot start; coordinate with deployment/secrets team
|
||||
- P1: 앱이 뜨지 못한다. 배포·secret 담당 팀과 맞춘다.
|
||||
|
||||
---
|
||||
|
||||
> **Stub**: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)
|
||||
> **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.
|
||||
|
||||
+22
-23
@@ -5,40 +5,39 @@ error_codes: [<ERROR_CODE_1>, <ERROR_CODE_2>]
|
||||
severity: <P1|P2|P3>
|
||||
owner: oncall
|
||||
last_updated: <YYYY-MM-DD>
|
||||
status: <stub|active>
|
||||
status: <초안|운영>
|
||||
---
|
||||
|
||||
# Runbook: <TITLE> (`runbook://<area>/<scenario>`)
|
||||
|
||||
## Symptoms
|
||||
## 증상
|
||||
|
||||
- What observable signals trigger this runbook?
|
||||
- Alert name, metric thresholds, log patterns
|
||||
- 이 runbook을 펴게 하는 관측 신호는 무엇인가?
|
||||
- alert 이름, 메트릭 임계값, 로그 패턴
|
||||
|
||||
## Diagnosis
|
||||
## 진단
|
||||
|
||||
- Step-by-step diagnostic commands and queries
|
||||
- Log queries (Loki/CloudWatch)
|
||||
- Metric panels to check
|
||||
- Trace investigation approach
|
||||
- 차례로 따라 하는 진단 명령과 쿼리
|
||||
- 로그 쿼리(Loki·CloudWatch)
|
||||
- 볼 메트릭 패널
|
||||
- trace 조사 방법
|
||||
|
||||
## Action
|
||||
## 조치
|
||||
|
||||
- Immediate mitigation steps
|
||||
- Configuration changes
|
||||
- Manual intervention procedures
|
||||
- 바로 하는 완화
|
||||
- 설정 변경
|
||||
- 손으로 하는 개입 절차
|
||||
|
||||
## Escalation
|
||||
## 에스컬레이션
|
||||
|
||||
- Conditions for severity upgrade (e.g., P2 → P1)
|
||||
- Who to page and when
|
||||
- Fallback procedures if on-call cannot resolve
|
||||
- 심각도를 올리는 조건(예: P2 → P1)
|
||||
- 언제 누구를 부르나
|
||||
- 당번이 풀지 못할 때의 대안
|
||||
|
||||
---
|
||||
|
||||
> **Note**: This is the canonical runbook template.
|
||||
> Copy this file, rename it to match the `runbook://area/scenario` pattern (→ `area-scenario.md`),
|
||||
> fill in the frontmatter fields, replace section bodies with operational content,
|
||||
> then set `status: active`. `LEGACY_STUB_DEBT` in `RunbookCoverageContractTest` is temporary
|
||||
> containment for existing debt only; do not add a new stub there. Complete the runbook or adopt
|
||||
> the future owned, expiring debt ledger.
|
||||
> **안내**: 이 파일이 runbook의 기준 양식이다.
|
||||
> 이 파일을 복사하고, `runbook://area/scenario` 꼴에 맞춰 이름을 바꾸고(→ `area-scenario.md`), 머리말 칸을 채우고,
|
||||
> 절 본문을 운영 내용으로 바꾼 뒤 `status: 운영`으로 둔다. 본문을 아직 쓰지 못한 runbook은 `status: 초안`이다.
|
||||
> `RunbookCoverageContractTest`의 `LEGACY_STUB_DEBT`는 이미 있는 초안만 잠시 담아 두는 목록이다. 새 초안을 거기에
|
||||
> 더하지 않는다. runbook을 끝내거나, 앞으로 생길 소유자·기한 있는 부채 장부를 쓴다.
|
||||
|
||||
@@ -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
|
||||
|
||||
+48
-9
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user