Cache-Control 고급 활용: stale-while-revalidate, stale-if-error로 체감 성능 높이기

Cache-Control 고급 활용: stale-while-revalidate, stale-if-error로 체감 성능 높이기

응답을 즉시 보여주면서도 완전히 오래된 데이터만 내보내지 않는 절충안이 필요할 때 `stale-while-revalidate`가 빛난다.

중급 팀에서는 캐시 시간을 늘리는 것이 아니라, '신선도와 가용성을 분리해서 다루는 방식'으로 Cache-Control을 설계해야 한다.

왜 지금 이 주제가 중요한가

• 캐시를 너무 짧게 두면 원본 서버 부하가 커지고, 너무 길게 두면 신선도 문제가 생긴다.
• `stale-if-error`는 장애 시 사용자 체감 품질을 지키는 강력한 수단이다.
• 브라우저, CDN, 프록시가 각각 캐시 헤더를 다르게 소비하기 때문에 의도를 명확히 해야 한다.

핵심 설계 포인트

• `max-age`는 일반 정상 상태의 신선도, `stale-while-revalidate`는 백그라운드 재검증 허용 범위다.
• `stale-if-error`는 원본 장애 시 얼마나 오래 이전 응답을 보여줄지 정의한다.
• ETag/Last-Modified와 함께 쓰면 네트워크 비용과 정합성 균형이 좋아진다.
• 로그인 사용자, 개인화 응답은 공용 캐시와 명확히 분리한다.

예시 구성

Cache-Control: public, max-age=60, stale-while-revalidate=300, stale-if-error=600
ETag: "post-list-v42"
Vary: Accept-Encoding

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

1. 정적/준정적/개인화 응답을 먼저 분류한다.
2. 각 응답에 허용 가능한 stale window와 오류 시 fallback 시간을 정한다.
3. 브라우저와 CDN 정책을 별도 테스트 환경에서 검증한다.
4. 배포 후 hit ratio와 origin offload 비율을 관측하며 값을 조정한다.
5. 중요 페이지는 stale 응답이 비즈니스에 미치는 영향을 제품 팀과 합의한다.

운영 체크포인트

• 개인화 응답에 `public` 캐시를 붙이지 않도록 라우트별 검증을 둔다.
• CDN이 `stale-while-revalidate`를 어떻게 해석하는지 문서와 실제 동작을 함께 확인한다.
• 원본 서버 장애 시 stale 응답 제공 여부를 대시보드에서 확인할 수 있어야 한다.

운영 지표/알람 추천

• 캐시 hit ratio와 stale 응답 비율
• 원본 저장소 QPS/지연과 캐시 도입 전후 비교
• stampede 방지 키의 lock contention
• 메모리 사용량과 eviction 비율

빠른 점검 명령/쿼리

redis-cli INFO stats | rg 'keyspace_hits|keyspace_misses'
redis-cli TTL cache:user:123
redis-cli --latency-history

구조화 로그 필드 추천

• traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
• endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
• 실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
• 민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

• 운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
• 기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
• 관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
• 팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

• 핵심 경로 에러율: 0.1% 이하
• 핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
• 중복 실행 또는 데이터 유실: 0건
• 장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

1. max-age만 키우고 끝낸다: 신선도와 장애 대응이 분리되지 않는다.
2. 캐시 가능한 응답과 아닌 응답을 라우트 수준에서 분리하지 않는다.
3. ETag 재검증 없이 stale 응답만 늘린다: 잘못된 값이 오래 남을 수 있다.

바로 적용 템플릿

Cache-Control 템플릿:
public/private
max-age=초
stale-while-revalidate=초
stale-if-error=초
ETag 또는 Last-Modified 병행

검증 방법

• 원본 서버를 의도적으로 오류 상태로 만들어 stale-if-error가 실제로 동작하는지 확인한다.
• 재검증 시 304 비율과 origin 응답시간 감소 효과를 비교한다.

장애 대응 Runbook(초안)

• 현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
• 범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
• 증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
• 임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
• 근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
• 재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

1. 실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
2. 타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
3. 관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
4. 롤백 또는 비상 스위치가 준비돼 있다.
5. 최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
6. 공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "Cache-Control 고급 활용: stale-while-revalidate, stale-if-error로 체감 성능 높이기"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

Q. 팀 합의가 자꾸 흔들립니다. 무엇을 문서로 남겨야 하나요?
A. 상태 전이, 기본값, 예외 처리, 롤백 기준 네 가지는 반드시 남겨야 한다. 이 네 가지가 없으면 장애 때 판단이 흔들린다.

참고/출처

• MDN: Cache-Control
• RFC 5861