[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/Backend_Health_Check_Patterns.md

@@ -0,0 +1,121 @@
+---
+id: backend-health-check-patterns
+title: Health Check — Liveness vs Readiness
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [backend, health, kubernetes, observability, vibe-coding]
+tech_stack: { language: "Any backend / Kubernetes", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [liveness probe, readiness probe, startup probe, /healthz]
+---
+
+# Health Check — Liveness vs Readiness
+
+> 두 종류 — **Liveness = "살아있나? 죽었으면 재시작"**, **Readiness = "트래픽 받을 준비됐나? 안 됐으면 LB에서 빼라"**. 두 개를 같은 endpoint 로 하면 cascading failure.
+
+## 📖 핵심 개념
+- **Liveness**: 프로세스 자체. 단순. 외부 의존성 검사 X.
+- **Readiness**: 트래픽 처리 가능. DB / 캐시 / 의존 서비스 검사 OK.
+- **Startup**: 초기화 오래 걸리는 앱용. liveness 무시 기간.
+
+## 💻 코드 패턴
+
+### Express 기준
+```ts
+let isReady = false;
+
+app.get('/healthz', (req, res) => res.status(200).json({ status: 'ok' })); // liveness
+
+app.get('/ready', async (req, res) => {
+  if (!isReady) return res.status(503).json({ ready: false });
+  const checks = await Promise.allSettled([
+    pingDB(),       // 1s timeout
+    pingRedis(),
+    pingDownstream(),
+  ]);
+  const failed = checks.filter(c => c.status === 'rejected');
+  if (failed.length > 0) {
+    return res.status(503).json({ ready: false, failed: failed.length });
+  }
+  res.status(200).json({ ready: true });
+});
+
+// 부팅 끝나면
+async function bootstrap() {
+  await db.connect();
+  await loadCaches();
+  await warmup();
+  isReady = true;
+}
+
+// graceful shutdown
+process.on('SIGTERM', async () => {
+  isReady = false;          // LB 빼지게
+  setTimeout(async () => {  // 진행 중 요청 처리 후 종료
+    await db.disconnect();
+    process.exit(0);
+  }, 30_000);
+});
+```
+
+### Kubernetes manifest
+```yaml
+livenessProbe:
+  httpGet: { path: /healthz, port: 8080 }
+  periodSeconds: 30
+  failureThreshold: 3
+  timeoutSeconds: 1
+readinessProbe:
+  httpGet: { path: /ready, port: 8080 }
+  periodSeconds: 5
+  failureThreshold: 2
+  timeoutSeconds: 3
+startupProbe:
+  httpGet: { path: /healthz, port: 8080 }
+  periodSeconds: 10
+  failureThreshold: 30   # 5분 init 허용
+```
+
+### Detailed health (옵션)
+```ts
+app.get('/health/detail', async (req, res) => {
+  const [db, redis, queue] = await Promise.allSettled([dbCheck(), redisCheck(), queueCheck()]);
+  res.status(200).json({
+    db: db.status === 'fulfilled' ? db.value : 'down',
+    redis: redis.status === 'fulfilled' ? redis.value : 'down',
+    queue: queue.status === 'fulfilled' ? queue.value : 'down',
+    version: process.env.GIT_SHA,
+    uptime: process.uptime(),
+  });
+});
+```
+
+## 🤔 의사결정 기준
+| 의존 | Readiness 포함 |
+|---|---|
+| 핵심 DB (없으면 절대 안 됨) | ✅ |
+| 보조 서비스 (analytics, search) | ❌ — degraded 모드 |
+| 외부 SaaS (이메일 provider) | ❌ — 큐로 흡수 |
+| Cache (Redis) | 보통 ❌ — fallback to DB |
+| 의존 마이크로서비스 | depends — 핵심이면 ✅ |
+
+## ❌ 안티패턴
+- **Liveness 가 DB ping**: DB 일시 장애 → 모든 pod 재시작 → 폭주. liveness 는 프로세스만.
+- **Readiness 가 너무 무거움**: probe 자체가 부하. 캐시 + 짧은 timeout.
+- **graceful shutdown 없음**: SIGTERM 즉시 죽음 → 진행 중 요청 cut. preStop hook + drain.
+- **probe timeout = period**: 마지막 호출이 끝나기 전 다음 호출 → 누적.
+- **dependency 트리 따라 cascading liveness**: A 가 B 보고, B 가 C 보면 C 일시 장애가 A 까지 재시작.
+- **버전 / git SHA 노출 안 함**: 어떤 빌드가 도는지 디버깅 어려움.
+- **public / private 구분 안 함**: 외부 노출 시 정보 누설. internal /metrics 와 분리.
+
+## 🤖 LLM 활용 힌트
+- liveness = simple, readiness = dependency-aware 분리.
+- SIGTERM → readiness false → drain → exit 표준 시퀀스.
+
+## 🔗 관련 문서
+- [[Backend_Circuit_Breaker]]
+- [[Observability_RED_USE_Metrics]]