2nd/10_Wiki/Topics/Coding/Backend_Health_Check_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-health-check-patterns	Health Check — Liveness vs Readiness	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend health kubernetes observability vibe-coding	language applicable_to Any backend / Kubernetes Backend		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 기준

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

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 (옵션)

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