Redis L2 캐시 + 자동완성 flat KV — Trie 퇴역과 Stateless 전환

이전 글

stress 테스트로 단일 서버 한계 확인에서 200 VU stress 테스트로 CPU 100% 포화를 확인하고, JVM/Tomcat 튜닝이 CPU-bound 병목에서 역효과를 냄을 기록했습니다.

이 글에서는 분산 전환의 첫 단계로 Redis L2 캐시를 도입하고, Trie 자동완성을 Redis flat KV로 교체하여 앱을 Stateless로 만듭니다.

이전 글 요약

stress 테스트에서 확인한 핵심 병목:

JVM/Tomcat 튜닝(스레드 200→100)은 79% 악화로 역효과. CPU-bound 병목에서 튜닝은 한계가 있으며, 분산 전환이 필요하다는 결론.

개요

분산 전환 3단계 — 왜 Redis가 먼저인가

“CPU가 병목이니 서버를 늘리자”가 아니라 인프라 준비 → 앱 확장 순서(Bottom-Up)로 진행합니다.

앱 스케일아웃을 먼저 하면 생기는 문제:

핵심 개념 — Stateless 전환: 앱이 내부에 상태(Caffeine 캐시, Trie, TokenBlacklist)를 들고 있으면 Stateful → 스케일아웃 시 상태 불일치. Redis로 상태를 외부화하면 Stateless → 인스턴스 자유롭게 추가/제거 가능.

CPU 포화의 근본 원인

Caffeine 캐시 히트율 96% → 4% 미스
최대 TPS ~110 req/s × 4% 미스 = 초당 ~4~5건의 Lucene BM25 검색
→ ARM 2코어에서 BM25 + DocValues 정렬이 CPU 집약적이므로
  초당 4~5건만으로도 CPU 포화

Redis L2 캐시를 도입하면:

1. 다중 인스턴스 캐시 공유 — Caffeine은 인스턴스별 독립. Redis는 공유 캐시이므로 히트율 유지
2. 자동완성 flat KV — Trie DFS 제거, O(1) GET, CPU 부하 감소
3. Origin 도달률 감소 — L1 + L2 2계층으로 DB/Lucene 접근 확률 감소

이 단계의 목표

인프라 구성 — 서버 2대 체제 전환

stress 테스트까지는 단일 서버에서 모든 것을 처리했습니다. 이 글부터 Oracle Cloud 추가 인스턴스를 생성하여 서버 2대 체제로 전환합니다.

서버 스펙

서버 1과 동일한 스펙(ARM 2코어, 12GB RAM)으로 서버 2를 구성합니다. 동일 스펙 2대 체제로 로드밸런싱 시 균등한 부하 분산이 가능합니다.

단계별 서버 활용 계획

왜 Redis인가 — Memcached와의 비교

분산 캐시의 양대 선택지는 Redis와 Memcached입니다.

Memcached가 더 적합한 경우: 순수 캐시만 필요하고, 수백GB 규모의 단순 key-value를 멀티스레드로 처리해야 할 때.

이 프로젝트에서 Redis가 필수인 이유:

1. 자동완성 데이터 영속성 — prefix_topk는 매시간 배치로 생성되므로 유실 시 최대 1시간 자동완성 불능
2. TokenBlacklist — JWT 로그아웃을 위한 블랙리스트를 다중 인스턴스가 공유해야 함 (Set + TTL)
3. Pub/Sub 캐시 무효화 — 스케일아웃 시 인스턴스 A의 게시글 수정 → Pub/Sub → 인스턴스 B/C의 L1 캐시 무효화
4. 후속 활용 — CDC 이벤트, 조회수 Redis INCR 등 캐시 이상의 역할

Redis 도입 비용 분석 — “Redis 없이 해결할 수 없었는가?”

Redis를 추가하기 전에, 기존 인프라 튜닝만으로 해결할 수 없는지 4가지 대안을 검토했습니다:

고정 자원 내 배분 비용

서버가 ARM 2코어, 12GB RAM으로 고정되어 있으므로 인프라 비용은 “12GB 안에서 Redis에 300MB를 할당하면 다른 곳이 300MB 줄어드는” 자원 배분 문제입니다.

Redis 도입의 자원 비용:
  Redis 컨테이너:       +300MB (maxmemory 256MB + freelist/클라이언트 버퍼 오버헤드 ~20%)
  OS 페이지 캐시 감소:   -200MB (~5G → ~4.8G)
  Lucene 인덱스 20GB 중 페이지 캐시 커버율: 25% → 24% (-1%)
  영속성 비용:          AOF 미사용 (캐시 데이터이므로 유실 허용, 최대 30초 조회수 유실)
                       RDB 스냅샷도 미사용 (재시작 시 origin에서 재로딩)

Redis 도입의 이득:
  L2 캐시 히트 시 Lucene 검색 회피 → CPU 부하 감소
  자동완성 Trie(~66MB JVM 힙) 제거 → 힙 여유 확보
  TokenBlacklist 공유 → 스케일아웃 전제조건 충족

판단:
  페이지 캐시 1% 감소 < L2 캐시 + Trie 힙 절약 + 스케일아웃 준비
  → Redis 300MB 투자 가치 있음

Redis 장애 시 데이터 유실 범위: AOF/RDB를 모두 미사용하므로 Redis 재시작 시 모든 캐시 데이터가 유실된다. L2 캐시와 자동완성 KV는 origin(MySQL/Lucene)에서 재로딩되고, 조회수는 최대 30초(flush 주기) 분량만 유실된다. 토큰 블랙리스트는 JWT 만료시간(24h) 내 데이터이므로, Redis 재시작 시 로그아웃된 토큰이 만료 전까지 다시 유효해질 수 있다 — 이 보안 트레이드오프는 Redis 샤딩에서 전용 인스턴스 분리로 blast radius를 축소했다.

AWS 환경에서의 비용 비교 참고: ElastiCache(t3.micro 기준 월 ~3만원)를 추가하고, DB 부하 감소분만큼 RDS를 다운스케일(예: db.r6g.large → medium, 월 ~13만원 절감)하면 총 인프라 비용이 줄어드는지가 도입 근거가 됩니다. 관리형 서비스 여부와 관계없이 자원 배분 트레이드오프 분석은 동일한 사고 과정입니다.

1. L1(Caffeine) + L2(Redis) 2계층 캐시

아키텍처 변경

캐시 계층별 특성

왜 Redis로 “교체”가 아닌 “추가”인가

Redis만 쓰면 모든 요청에 네트워크 비용(~1-5ms)이 발생합니다. Caffeine(L1)이 있으면 같은 인스턴스에서 반복 요청 시 0.1ms에 반환됩니다. L1으로 네트워크 비용을 절약하고, L2로 인스턴스 간 일관성을 확보하는 구조입니다.

왜 Spring @Cacheable이 아닌 직접 구현인가

Spring Cache Abstraction(@Cacheable + CacheManager)은 단일 계층 캐시를 전제로 설계되어 있습니다.

따라서 TieredCacheService를 직접 구현하여 L1 → L2 → Origin 조회 순서와 양방향 저장을 제어합니다.

TieredCacheService 구현

@Component
public class TieredCacheService {

    private final Cache<String, Object> localCache;              // L1: Caffeine
    private final RedisTemplate<String, String> redisTemplate;   // L2: Redis
    private final JsonMapper jsonMapper;                          // Jackson 3
    private final MeterRegistry meterRegistry;

    public <T> T get(String cacheRegion, String key, Class<T> type,
                     Supplier<T> loader) {
        // 1. L1 확인
        Object cached = localCache.getIfPresent(key);
        if (cached != null && type.isInstance(cached)) {
            meterRegistry.counter("tiered_cache", "region", cacheRegion,
                "level", "L1").increment();
            return type.cast(cached);
        }

        // 2. L2 확인 (Redis 장애 시 스킵)
        try {
            String json = redisTemplate.opsForValue().get(key);
            if (json != null) {
                T value = jsonMapper.readValue(json, type);
                localCache.put(key, value);  // L1에 승격
                meterRegistry.counter("tiered_cache", "region", cacheRegion,
                    "level", "L2").increment();
                return value;
            }
        } catch (RedisConnectionFailureException | RedisCommandTimeoutException e) {
            log.warn("Redis L2 조회 실패, fallback: {}", e.getMessage());
        }

        // 3. Origin 조회
        T value = loader.get();

        // 4. L1 + L2 양쪽에 저장
        localCache.put(key, value);
        try {
            redisTemplate.opsForValue().set(key,
                jsonMapper.writeValueAsString(value), Duration.ofMinutes(10));
        } catch (RedisConnectionFailureException e) {
            log.warn("Redis L2 저장 실패, L1에만 캐싱: {}", e.getMessage());
        }

        meterRegistry.counter("tiered_cache", "region", cacheRegion,
            "level", "origin").increment();
        return value;
    }
}

설계 포인트:

• RedisTemplate<String, String> + JsonMapper로 직렬화/역직렬화를 직접 제어
• Java 제네릭은 런타임에 타입이 소거(type erasure)되므로 Class<T> 파라미터로 타입 정보를 명시적으로 전달
• Redis 장애 시 try-catch로 L2를 스킵하고 L1 + Origin으로 fallback
• cacheRegion 태그로 searchResults, postDetail 등 용도별 히트율 계측

L1-L2 캐시 일관성 전략

2계층 캐시에서는 L1에 stale 데이터가 남는 문제가 구조적으로 발생합니다:

시나리오: 게시글 수정 시
  1. 사용자가 post:123 수정 → DB 업데이트
  2. Redis(L2)에서 post:123 삭제
  3. 같은 인스턴스의 L1에서도 evict → 즉시 반영 ✓
  4. 다른 인스턴스의 L1에는 여전히 옛날 데이터 ✗
     → L1 TTL(5분) 만료까지 stale 데이터 서빙

무효화 전략 (단계별):

Pub/Sub의 한계 — at-most-once 전송: Redis Pub/Sub은 fire-and-forget 방식입니다. 구독자가 일시적으로 연결이 끊기면 그 사이의 메시지는 영원히 유실됩니다.

커뮤니티 게시판에서 검색 결과가 최대 5분 지연되는 것은 UX에 큰 영향이 없으므로, best-effort 무효화 + TTL 안전망 전략을 채택했습니다.

Redis 장애 시 Graceful Degradation

핵심 원칙: Redis 장애가 서비스 장애로 이어지면 안 됩니다. Redis는 “있으면 빨라지는 것”이지, “없으면 안 되는 것”이 아닙니다.

정상 상태:
  요청 → L1(Caffeine) → L2(Redis) → Lucene/MySQL

Redis 장애 시:
  요청 → L1(Caffeine) → L2(Redis) ✗ 타임아웃
                              ↓ try-catch로 L2 스킵
                     Lucene/MySQL 직접 조회
                              ↓ L1에만 저장

자동완성은 예외 — prefix_topk 데이터가 Redis에만 있으므로, Redis 장애 시 Lucene PrefixQuery fallback으로 자동 전환됩니다. Trie를 퇴역시키되 Lucene PrefixQuery를 fallback으로 유지한 이유가 여기에 있습니다.

2. 자동완성 flat KV — Trie 퇴역

Trie의 한계 (Trie 자동완성에서 확인)

접두사별 추천 결과를 미리 준비하는 구조로 전환

Trie (이전):
  "삼성" 검색 → Trie DFS → 하위 노드 순회 → Top-K 정렬 → 반환

Redis flat KV (이 글):
  "삼성" 검색 → Redis GET "prefix:삼성" → ["삼성전자","삼성물산","삼성SDI"]
  → O(1), DFS 없음, CPU 부하 없음

Trie는 검색 품질 문제를 해결하는 데는 유효했지만, 조회 시마다 탐색과 정렬 비용이 따라오는 구조였습니다. 그래서 이 단계에서는 입력마다 후보를 다시 계산하기보다, 접두사마다 상위 추천 결과를 미리 만들어두고 요청 시 바로 반환하는 구조가 더 적합하다고 판단했습니다. 이렇게 하면 조회 경로는 훨씬 단순해지고, 여러 인스턴스가 같은 결과를 공유하기도 쉬워집니다.

접두사별 추천 결과를 주기적으로 집계

자동완성 결과는 약간 늦게 반영되어도 괜찮기 때문에, 모든 입력을 실시간으로 처리하기보다 일정 주기로 모아 집계하는 방식을 택했습니다. 사용자가 입력한 검색어를 먼저 누적한 뒤, 최근 데이터를 기준으로 접두사별 상위 추천 결과를 다시 계산하고, 조회 시에는 이미 정렬된 결과를 바로 반환하는 흐름입니다.

구현은 단일 서버에서 SQL + Java 조합으로 처리합니다:

@Scheduled(cron = "0 0 * * * *")  // 매시간
public void buildPrefixTopK() {
    // 1. SQL GROUP BY로 인기 검색어 Top-N 추출
    List<Object[]> topQueries = searchLogRepository
        .findTopQueriesSince(LocalDateTime.now().minusDays(7), 10000);

    // 2. 각 검색어를 모든 prefix로 분해
    Map<String, PriorityQueue<ScoredQuery>> prefixMap = new HashMap<>();
    for (Object[] row : topQueries) {
        String query = (String) row[0];
        long count = ((Number) row[1]).longValue();
        for (int len = 1; len <= Math.min(query.length(), 10); len++) {
            String prefix = query.substring(0, len);
            prefixMap.computeIfAbsent(prefix, k -> new PriorityQueue<>(
                Comparator.comparingLong(ScoredQuery::score)))
                .offer(new ScoredQuery(query, count));
            if (prefixMap.get(prefix).size() > 10) {
                prefixMap.get(prefix).poll();  // Top-10 유지
            }
        }
    }

    // 3. 새 버전 네임스페이스에 적재
    long newVersion = System.currentTimeMillis();
    prefixMap.forEach((prefix, heap) -> {
        List<String> topK = heap.stream()
            .sorted(Comparator.comparingLong(ScoredQuery::score).reversed())
            .map(ScoredQuery::query).toList();
        redisTemplate.opsForValue().set(
            "prefix:v" + newVersion + ":" + prefix,
            toJson(topK), Duration.ofHours(2));
    });

    // 4. 버전 포인터 원자적 전환
    redisTemplate.opsForValue().set("prefix:current_version",
        String.valueOf(newVersion));
}

왜 RENAME이 아닌 버전 네임스페이스 전환인가

이전 버전 키가 TTL 만료까지 메모리를 차지하지만, prefix_topk 전체가 ~1MB이므로 2배(~2MB)여도 무시 가능합니다.

GET 2번 오버헤드 해결: version 값을 Caffeine에 로컬 캐싱(TTL 30초). version은 매시간 배치에서만 변경되므로 30초 캐싱해도 안전합니다. 읽기 경로: Caffeine에서 version 조회(0.1ms) → Redis GET 1번(~1ms).

Redis 메모리 추정

검색 로그가 10배 늘어나도 ~23MB. 단일 Redis로 충분합니다.

3. 직렬화 — Jackson JSON 선택

Jackson JSON을 선택한 근거:

캐시 데이터 합계 ~31MB. MessagePack으로 바꿔도 ~22MB (9MB 절감) — Redis maxmemory 256MB 대비 3.5%. 직렬화 속도 차이(~0.5μs)도 네트워크 RTT(~1ms) 대비 무시 가능합니다. redis-cli에서 사람이 읽을 수 있어 디버깅이 훨씬 쉽고, 추가 의존성도 없습니다.

전환 기준: Redis 메모리가 maxmemory의 80%(~200MB)에 도달하면 MessagePack 전환을 검토합니다. 현재 실측 28.4%(~73MB)이므로 전환은 한참 먼 상태입니다.

4. Docker에 Redis 추가

docker-compose.yml

redis:
  image: redis:7.4-alpine
  container_name: wiki-redis-prod
  restart: always
  volumes:
    - redis-data:/data
  command: >
    redis-server
    --maxmemory 256mb
    --maxmemory-policy volatile-lru
    --requirepass ${REDIS_PASSWORD}
    --slowlog-log-slower-than 10000
    --slowlog-max-len 128
  deploy:
    resources:
      limits:
        memory: 300M

왜 allkeys-lru가 아닌 volatile-lru인가

allkeys-lru는 메모리 압박 시 모든 키를 LRU 기준으로 퇴거시킵니다. 이 프로젝트에서는 삭제되면 안 되는 키가 있습니다:

volatile-lru는 TTL이 설정된 키만 퇴거 대상으로 삼습니다. TTL이 없는 prefix:current_version은 절대 퇴거되지 않습니다.

보안 — 포트 노출 제거 + 인증

Docker Compose 내부 네트워크에서 앱 컨테이너는 서비스명(redis:6379)으로 접근합니다. 호스트에 6379 포트를 노출하지 않고, requirepass로 비밀번호를 설정합니다.

5. Redis 모니터링

Redis Exporter + Grafana 대시보드

Lettuce 클라이언트 레이턴시

Redis Exporter는 서버 측 메트릭입니다. 앱→Redis 네트워크 포함 레이턴시는 Spring Boot 4.0의 LettuceObservationAutoConfiguration으로 자동 계측됩니다.

spring-boot-starter-data-redis + spring-boot-starter-actuator만으로 추가 의존성 없이 동작합니다.

L1/L2/Origin 히트율 커스텀 메트릭

기존 Caffeine의 cache_gets_total은 TieredCacheService로 전환하면 동작하지 않으므로, 3계층 비율을 직접 계측합니다:

Grafana 알림 규칙

Ansible 인프라 변경 사항

수정 파일 목록

Before 측정 (Redis 도입 전 기준선)

Redis 컨테이너는 떠 있지만 앱 코드는 아직 Caffeine + Trie를 사용하는 상태에서 k6 load 테스트(100 VU, 20분)를 수행합니다.

k6 결과

시나리오별 응답시간 + 검색 빈도별 성능

핵심 관측: 고빈도 토큰(“대한민국”, “history” 등)의 평균 75ms, P95 405ms가 전체 응답시간을 끌어올리고 있습니다. posting list가 길어 BM25 점수 계산에 CPU를 많이 소모하기 때문입니다. 이것이 Redis L2 캐시로 Lucene 접근을 줄여야 하는 직접적 근거입니다.

네트워크 상세

시스템 수치

핵심 구현 — 코드 변경

주요 코드 변경

검색 로그 기록 개선: 기존 @Cacheable은 캐시 히트 시 메서드 본문이 실행되지 않아 검색 로그가 누락됐습니다. TieredCacheService로 전환 후 searchLogCollector.record(keyword)를 캐시 밖에 배치하여 모든 검색이 기록되도록 개선했습니다. prefix_topk 인기도 데이터의 정확도가 향상됩니다.

기능 검증 (프로덕션)

After 실측 + Before 비교

Before(Caffeine + Trie)와 동일 조건(100 VU, 20분)으로 재측정합니다.

Tiered Cache 히트 분포

L1 + L2 합산 82% 히트 → Origin 도달률 19%로 Lucene/MySQL 접근이 5분의 1로 감소.

Redis 대시보드

Lettuce 레이턴시

Before vs After 종합 비교

자동완성 Before/After

핵심 성과

단일 인스턴스 100 VU에서 응답시간/CPU는 유사하지만, 이 단계의 진짜 성과는 수치 개선이 아닌 구조 전환입니다:

1. Stateless 전환 완료 — Caffeine, Trie, TokenBlacklist를 Redis로 외부화하여 App 스케일아웃의 전제조건 충족
2. Origin 도달률 19% — L1+L2 2계층으로 인스턴스를 추가해도 DB/Lucene 부하가 선형 증가하지 않는 구조 확보
3. 자동완성 Trie 퇴역 — O(1) Redis GET으로 전환, 인스턴스 간 일관성 확보, JVM 힙 ~66MB 절약
4. Redis 인프라 안정 — Eviction 0, Lettuce P95 2.5ms, 메모리 사용률 28.4%

후속 개선 — Spring Batch 전환

RedisAutocompleteService.buildPrefixTopK()의 @Scheduled 방식을 Spring Batch Job(Tasklet)으로 전환했습니다.

설계 문서의 MapReduce 배치 패턴과 부합합니다:

• Map: SQL GROUP BY → prefix 분해 (원본 + 자모 + 초성)
• Reduce: 접두사별 Top-K 집계
• Write: Redis 버전 네임스페이스 적재 → 포인터 원자적 전환

관련 파일:

• AutocompleteBatchConfig.java — Job/Step/Tasklet 정의
• AutocompleteBatchScheduler.java — 매시간 Job 트리거
• RedisAutocompleteService.java — buildPrefixTopK() 제거, 초기화만 유지

다음 글

다음 글에서 MySQL Replication(Primary-Replica)을 구성하고 DataSource 라우팅으로 읽기 부하를 분산합니다. 이것이 App 스케일아웃의 두 번째 전제조건입니다.

Previous Post

In Stress Testing Single Server Limits, we confirmed CPU 100% saturation at 200 VU and documented how JVM/Tomcat tuning backfired under CPU-bound bottleneck.

This post covers the first step of distributed transition: introducing Redis L2 cache and replacing Trie autocomplete with Redis flat KV to make the app Stateless.

Previous Posts Summary

Key bottleneck confirmed in stress testing:

JVM/Tomcat tuning (threads 200→100) resulted in 79% degradation. Tuning has limits under CPU-bound bottleneck — distributed transition is needed.

Overview

3-Phase Distributed Transition — Why Redis First

Instead of “CPU is the bottleneck, let’s add servers,” we follow a Bottom-Up order: infrastructure preparation → app expansion.

Problems if app scale-out comes first:

Key Concept — Stateless Transition: When the app holds state internally (Caffeine cache, Trie, TokenBlacklist), it’s Stateful → state inconsistency on scale-out. Externalizing state to Redis makes it Stateless → instances can be freely added/removed.

Root Cause of CPU Saturation

Caffeine cache hit rate 96% → 4% misses
Max TPS ~110 req/s × 4% misses = ~4-5 Lucene BM25 searches per second
→ BM25 + DocValues sorting is CPU-intensive on ARM 2 cores
  Even 4-5 searches/sec saturates CPU

Redis L2 cache benefits:

1. Shared cache across instances — Caffeine is per-instance; Redis is shared, maintaining hit rate
2. Autocomplete flat KV — Eliminates Trie DFS, O(1) GET, reduces CPU load
3. Reduced Origin access — L1 + L2 two-tier reduces DB/Lucene access probability

Goals for This Phase

Infrastructure — Dual Server Setup

Up to Stress Test, everything ran on a single server. Starting from this post, we create an additional Oracle Cloud instance for a dual server setup.

Server Specs

Server 2 is configured with the same specs (ARM 2 cores, 12GB RAM) as Server 1. Identical specs across both servers enable even load distribution during load balancing.

Phased Server Utilization Plan

Why Redis — Comparison with Memcached

The two main distributed cache options are Redis and Memcached.

When Memcached is better: When only pure caching is needed, and large-scale simple key-value must be processed with multi-threading.

Why Redis is essential for this project:

1. Autocomplete data persistence — prefix_topk is built hourly; loss means up to 1 hour autocomplete outage
2. TokenBlacklist — JWT logout blacklist must be shared across instances (Set + TTL)
3. Pub/Sub cache invalidation — On scale-out: post edit on instance A → Pub/Sub → invalidate L1 on instances B/C
4. Future use — CDC events, view count Redis INCR, roles beyond caching

Redis Cost Analysis — “Couldn’t We Solve This Without Redis?”

Before adding Redis, we evaluated 4 alternatives using existing infrastructure tuning:

Resource Allocation Cost

With the server fixed at ARM 2 cores, 12GB RAM, infrastructure cost is “allocating 300MB to Redis means 300MB less elsewhere within 12GB” — a resource allocation problem.

Redis resource cost:
  Redis container:           +300MB (maxmemory 256MB + overhead)
  OS page cache reduction:   -200MB (~5G → ~4.8G)
  Lucene 20GB index page cache coverage: 25% → 24% (-1%)

Redis benefits:
  L2 cache hits avoid Lucene search → CPU load reduction
  Trie removal (~66MB JVM heap) → heap freed
  TokenBlacklist shared → scale-out prerequisite met

Decision:
  1% page cache loss < L2 cache + Trie heap savings + scale-out readiness
  → Redis 300MB investment worthwhile

AWS cost comparison reference: Adding ElastiCache (t3.micro ~₩30K/month) and downscaling RDS (e.g., db.r6g.large → medium, ~₩130K/month savings) to check if total infrastructure cost decreases would be the justification. Regardless of managed vs self-hosted, the resource allocation tradeoff analysis is the same thought process.

1. L1(Caffeine) + L2(Redis) Tiered Cache

Architecture Change

Cache Tier Characteristics

Why “Add” Not “Replace” with Redis

Using only Redis means every request incurs network cost (~1-5ms). With Caffeine(L1), repeated requests from the same instance return in 0.1ms. L1 saves network cost; L2 ensures cross-instance consistency.

Why Custom Implementation Instead of Spring @Cacheable

Spring Cache Abstraction (@Cacheable + CacheManager) is designed for single-tier caching.

Therefore, TieredCacheService was implemented directly to control L1 → L2 → Origin lookup order and bidirectional storage.

TieredCacheService Implementation

@Component
public class TieredCacheService {

    private final Cache<String, Object> localCache;              // L1: Caffeine
    private final RedisTemplate<String, String> redisTemplate;   // L2: Redis
    private final JsonMapper jsonMapper;                          // Jackson 3
    private final MeterRegistry meterRegistry;

    public <T> T get(String cacheRegion, String key, Class<T> type,
                     Supplier<T> loader) {
        // 1. Check L1
        Object cached = localCache.getIfPresent(key);
        if (cached != null && type.isInstance(cached)) {
            meterRegistry.counter("tiered_cache", "region", cacheRegion,
                "level", "L1").increment();
            return type.cast(cached);
        }

        // 2. Check L2 (skip on Redis failure)
        try {
            String json = redisTemplate.opsForValue().get(key);
            if (json != null) {
                T value = jsonMapper.readValue(json, type);
                localCache.put(key, value);  // Promote to L1
                meterRegistry.counter("tiered_cache", "region", cacheRegion,
                    "level", "L2").increment();
                return value;
            }
        } catch (RedisConnectionFailureException | RedisCommandTimeoutException e) {
            log.warn("Redis L2 lookup failed, fallback: {}", e.getMessage());
        }

        // 3. Origin lookup
        T value = loader.get();

        // 4. Store in both L1 + L2
        localCache.put(key, value);
        try {
            redisTemplate.opsForValue().set(key,
                jsonMapper.writeValueAsString(value), Duration.ofMinutes(10));
        } catch (RedisConnectionFailureException e) {
            log.warn("Redis L2 store failed, L1 only: {}", e.getMessage());
        }

        meterRegistry.counter("tiered_cache", "region", cacheRegion,
            "level", "origin").increment();
        return value;
    }
}

Design points:

• RedisTemplate<String, String> + JsonMapper for direct serialization/deserialization control
• Java generics undergo type erasure at runtime, so Class<T> parameter explicitly passes type information
• Redis failures caught with try-catch, skipping L2 and falling back to L1 + Origin
• cacheRegion tag enables per-purpose hit rate measurement (searchResults, postDetail)

L1-L2 Cache Consistency Strategy

In tiered caching, stale data in L1 is a structural issue:

Scenario: Post edit
  1. User edits post:123 → DB updated
  2. post:123 deleted from Redis(L2)
  3. L1 on same instance also evicted → immediately reflected ✓
  4. L1 on other instances still has old data ✗
     → Serves stale data until L1 TTL(5min) expires

Invalidation strategy (by phase):

Pub/Sub limitation — at-most-once delivery: Redis Pub/Sub is fire-and-forget. If a subscriber momentarily disconnects, messages published during that time are permanently lost.

For a community forum, max 5-minute delay in search results has negligible UX impact, so best-effort invalidation + TTL safety net was adopted.

Graceful Degradation on Redis Failure

Core principle: Redis failure must not become service failure. Redis is “makes things faster when available,” not “required for operation.”

Normal:
  Request → L1(Caffeine) → L2(Redis) → Lucene/MySQL

Redis down:
  Request → L1(Caffeine) → L2(Redis) ✗ timeout
                              ↓ try-catch skips L2
                     Lucene/MySQL direct query
                              ↓ Store in L1 only

Autocomplete is the exception — prefix_topk data exists only in Redis, so on Redis failure, it auto-switches to Lucene PrefixQuery fallback. This is why Trie was retired but Lucene PrefixQuery was kept as fallback.

2. Autocomplete Flat KV — Retiring Trie

Trie Limitations (Identified in Trie Autocomplete)

Transition to Redis Flat KV

Trie (before):
  "삼성" search → Trie DFS → traverse child nodes → Top-K sort → return

Redis flat KV (this post):
  "삼성" search → Redis GET "prefix:삼성" → ["삼성전자","삼성물산","삼성SDI"]
  → O(1), no DFS, no CPU load

prefix_topk Data Generation — SQL GROUP BY + Prefix Decomposition

Processed with SQL + Java on a single server, no MapReduce/Spark:

@Scheduled(cron = "0 0 * * * *")  // hourly
public void buildPrefixTopK() {
    // 1. SQL GROUP BY to extract top-N popular queries
    List<Object[]> topQueries = searchLogRepository
        .findTopQueriesSince(LocalDateTime.now().minusDays(7), 10000);

    // 2. Decompose each query into all prefixes
    Map<String, PriorityQueue<ScoredQuery>> prefixMap = new HashMap<>();
    for (Object[] row : topQueries) {
        String query = (String) row[0];
        long count = ((Number) row[1]).longValue();
        for (int len = 1; len <= Math.min(query.length(), 10); len++) {
            String prefix = query.substring(0, len);
            prefixMap.computeIfAbsent(prefix, k -> new PriorityQueue<>(
                Comparator.comparingLong(ScoredQuery::score)))
                .offer(new ScoredQuery(query, count));
            if (prefixMap.get(prefix).size() > 10) {
                prefixMap.get(prefix).poll();  // Maintain Top-10
            }
        }
    }

    // 3. Load into new version namespace
    long newVersion = System.currentTimeMillis();
    prefixMap.forEach((prefix, heap) -> {
        List<String> topK = heap.stream()
            .sorted(Comparator.comparingLong(ScoredQuery::score).reversed())
            .map(ScoredQuery::query).toList();
        redisTemplate.opsForValue().set(
            "prefix:v" + newVersion + ":" + prefix,
            toJson(topK), Duration.ofHours(2));
    });

    // 4. Atomic version pointer switch
    redisTemplate.opsForValue().set("prefix:current_version",
        String.valueOf(newVersion));
}

Why Version Namespace Instead of RENAME

Previous version keys occupy memory until TTL expiry, but total prefix_topk is ~1MB, so even doubled (~2MB) is negligible.

Solving 2-GET overhead: Version value is locally cached in Caffeine (TTL 30sec). Version changes only on hourly batch, so 30sec caching is safe. Read path: Caffeine version lookup (0.1ms) → 1 Redis GET (~1ms).

Redis Memory Estimate

Even with 10x search log growth, ~23MB. Single Redis is sufficient.

3. Serialization — Jackson JSON Selected

Jackson JSON rationale: Total cache data ~31MB. MessagePack saves ~9MB — only 3.5% of Redis maxmemory 256MB. Serialization speed difference (~0.5μs) is negligible vs network RTT (~1ms). Human-readable in redis-cli for easy debugging, no extra dependencies.

Switch threshold: When Redis memory reaches 80% (~200MB) of maxmemory. Current measured usage is 28.4% (~73MB), so the switch point is far off.

4. Adding Redis to Docker

docker-compose.yml

redis:
  image: redis:7.4-alpine
  container_name: wiki-redis-prod
  restart: always
  volumes:
    - redis-data:/data
  command: >
    redis-server
    --maxmemory 256mb
    --maxmemory-policy volatile-lru
    --requirepass ${REDIS_PASSWORD}
    --slowlog-log-slower-than 10000
    --slowlog-max-len 128
  deploy:
    resources:
      limits:
        memory: 300M

Why volatile-lru Instead of allkeys-lru

allkeys-lru evicts all keys by LRU under memory pressure. This project has keys that must not be deleted:

volatile-lru only targets keys with TTL set for eviction. prefix:current_version without TTL is never evicted.

Security — No Port Exposure + Authentication

App containers access Redis via service name (redis:6379) on Docker Compose internal network. Port 6379 is not exposed to the host. requirepass enforces password authentication.

5. Redis Monitoring

Redis Exporter + Grafana Dashboard

Lettuce Client Latency

Redis Exporter provides server-side metrics. App→Redis latency including network is auto-instrumented by Spring Boot 4.0’s LettuceObservationAutoConfiguration.

Works with just spring-boot-starter-data-redis + spring-boot-starter-actuator, no extra dependencies needed.

L1/L2/Origin Hit Rate Custom Metrics

Existing Caffeine’s cache_gets_total stops working after TieredCacheService migration, so 3-tier ratios are directly instrumented:

Grafana Alert Rules

Ansible Infrastructure Changes

Modified Files

Before Measurement (Baseline Before Redis)

Redis container is running but app code still uses Caffeine + Trie. k6 load test (100 VU, 20min).

k6 Results

Per-Scenario Response Time + Search Frequency Performance

Key observation: High-frequency tokens (“대한민국”, “history”) with avg 75ms, P95 405ms are pulling up overall response time. Longer posting lists consume more CPU for BM25 scoring. This is the direct justification for reducing Lucene access via Redis L2 cache.

Network Detail

System Metrics

Core Implementation — Code Changes

Key Code Changes

Search log recording improvement: Previous @Cacheable skipped method body on cache hit, causing search log omissions. After TieredCacheService migration, searchLogCollector.record(keyword) was placed outside the cache, ensuring all searches are recorded. This improves prefix_topk popularity data accuracy.

Functional Verification (Production)

After Measurement + Before Comparison

Re-measured under identical conditions (100 VU, 20min) as Before (Caffeine + Trie).

Tiered Cache Hit Distribution

L1 + L2 combined 82% hit → Origin access reduced to 19%, Lucene/MySQL access cut to 1/5th.

Redis Dashboard

Lettuce Latency

Before vs After Comprehensive Comparison

Autocomplete Before/After

Key Achievements

Response time/CPU at 100 VU single instance are similar, but the real achievement is structural transition, not metric improvement:

1. Stateless transition complete — Caffeine, Trie, TokenBlacklist externalized to Redis, fulfilling App scale-out prerequisites
2. Origin access rate 19% — With L1+L2 two-tier, DB/Lucene load won’t increase linearly when adding instances
3. Trie retired — Switched to O(1) Redis GET, cross-instance consistency achieved, ~66MB JVM heap saved
4. Redis infra stable — Eviction 0, Lettuce P95 2.5ms, memory usage 28.4%

Next Post

The next post configures MySQL Replication (Primary-Replica) with DataSource routing to distribute read load. This is the second prerequisite for App Scale-out.