[Spring Cache] Actuator로 캐시 모니터링

왜 모니터링이 필요한가

캐시를 적용했다고 끝이 아니다. "정말 잘 동작하고 있는가?"를 확인해야 한다.

• 적중률이 10%면? 캐시가 거의 안 되고 있다. TTL이 너무 짧거나, 키 설계가 잘못됐을 수 있다.
• 제거 횟수가 지나치게 많으면? maximumSize가 너무 작아서 데이터가 들어오자마자 밀려나고 있다.
• 특정 캐시만 미스가 많으면? 그 캐시의 설정을 개별 튜닝해야 한다.

이런 판단을 하려면 숫자로 된 통계가 있어야 한다. Caffeine의 recordStats와 Spring Actuator를 연동하면, 캐시의 적중/미스/제거 횟수를 API로 조회할 수 있다.

Actuator가 노출하는 캐시 관련 엔드포인트와 메트릭을 한눈에 정리하면 이렇다.

설정

recordStats 활성화

Caffeine이 통계를 수집하려면 recordStats를 켜야 한다. 꺼져 있으면 Actuator에서 캐시 메트릭이 안 나온다.

application.yml로 설정하는 경우:

spring:
  cache:
    type: caffeine
    cache-names:
      - users
      - channels
      - notifications
    caffeine:
      spec: >
        maximumSize=100,
        expireAfterWrite=600s,
        recordStats

Java Config로 설정하는 경우:

Caffeine.newBuilder()
    .maximumSize(100)
    .expireAfterWrite(600, TimeUnit.SECONDS)
    .recordStats()   // 이 한 줄 추가
    .build();

Actuator 엔드포인트 노출

Actuator의 캐시 관련 엔드포인트를 노출해야 한다.

management:
  endpoints:
    web:
      exposure:
        include: health,caches,metrics

• /actuator/caches : 등록된 캐시 목록
• /actuator/metrics/cache.gets : 캐시 조회 통계 (히트/미스)
• /actuator/metrics/cache.evictions : 캐시 제거 통계
• /actuator/metrics/cache.size : 현재 캐시 항목 수

캐시 목록 조회

curl http://localhost:8080/actuator/caches

{
  "cacheManagers": {
    "cacheManager": {
      "caches": {
        "users": { "target": "com.github.benmanes.caffeine.cache.BoundedLocalCache" },
        "channels": { "target": "com.github.benmanes.caffeine.cache.BoundedLocalCache" },
        "notifications": { "target": "com.github.benmanes.caffeine.cache.BoundedLocalCache" }
      }
    }
  }
}

등록된 캐시 이름과 구현체를 확인할 수 있다. @Cacheable("users")로 사용한 캐시가 실제로 등록되어 있는지 확인하는 용도다.

적중률 분석

가장 중요한 메트릭이다. 캐시 히트와 미스 횟수를 조회한다.

curl http://localhost:8080/actuator/metrics/cache.gets?tag=cache:users

{
  "name": "cache.gets",
  "measurements": [
    { "statistic": "COUNT", "value": 150.0 }
  ],
  "availableTags": [
    { "tag": "result", "values": ["hit", "miss"] },
    { "tag": "cache", "values": ["users", "channels", "notifications"] }
  ]
}

히트와 미스를 각각 조회하려면 result 태그를 추가한다.

# 캐시 히트 횟수
curl "http://localhost:8080/actuator/metrics/cache.gets?tag=cache:users&tag=result:hit"

# 캐시 미스 횟수
curl "http://localhost:8080/actuator/metrics/cache.gets?tag=cache:users&tag=result:miss"

적중률은 이렇게 계산한다.

적중률 = hit / (hit + miss)

제거 통계

캐시에서 항목이 제거된 횟수를 확인한다.

curl http://localhost:8080/actuator/metrics/cache.evictions?tag=cache:users

{
  "name": "cache.evictions",
  "measurements": [
    { "statistic": "COUNT", "value": 25.0 }
  ]
}

제거가 빈번하면 maximumSize가 너무 작은 것이다. 데이터가 들어오자마자 밀려나고, 밀려난 데이터가 다시 요청되면 DB를 조회해야 한다. maximumSize를 늘리면 적중률이 올라간다.

캐시 크기

현재 캐시에 저장된 항목 수를 확인한다.

curl http://localhost:8080/actuator/metrics/cache.size?tag=cache:users

{
  "name": "cache.size",
  "measurements": [
    { "statistic": "VALUE", "value": 42.0 }
  ]
}

maximumSize=100으로 설정했는데 실제 크기가 항상 100 근처면, 캐시가 가득 차서 제거가 빈번하다는 뜻이다. 크기를 늘려야 한다.

모니터링 흐름 요약

캐시를 적용하고 모니터링하는 전체 흐름을 정리하면 이렇다.

초기 설정 후 Actuator 지표를 주기적으로 확인하고, 지표가 저조하면 원인을 파악해서 튜닝한다. 튜닝 후 다시 지표를 확인하는 반복 사이클이 핵심이다. 원인에 따라 조치가 달라진다.

• TTL 조정 : 적중률이 낮고 캐시 미스가 많으면 TTL이 너무 짧은 것이다.
• 크기 조정 : cache.evictions가 많으면 maximumSize를 늘려야 한다.
• 키/무효화 재설계 : 히트 수가 극히 낮으면 키가 너무 세분화되었거나, @CacheEvict가 너무 잦아서 저장하자마자 삭제되고 있다.

자주 하는 실수

면접 Q&A