chore: 컨텍스트 캐싱 효과 측정 — cachedContentTokenCount 기록

- generation_log에 cached_tokens 추가(V12) + 생성기 3종이 usageMetadata의
  cachedContentTokenCount를 캡처(댓글·답글·카드 output에 cachedTokens)
- 카드 생성도 generation_log에 기록(GenerationType.CARD 추가) — 대화당 전체 측정 가능
- 대시보드 품질 지표에 캐시 토큰·적중률 노출
- 총 토큰(totalTokenCount)은 캐싱으로 안 줄고, 실효 비용은 cached_tokens로 계산

Author: theminjunchoi

admin-web/src/pages/dashboard/quality-section.tsx

@@ -22,6 +22,8 @@ interface QualityStats {
   avgLatencyMs: number
   p95LatencyMs: number
   totalTokens: number
+  cachedTokens: number
+  cacheHitRate: number | null
   stuckPending: number
   dailyGeneration: DailyGeneration[]
 }
@@ -101,7 +103,12 @@ export function QualitySection() {
         />
         <MetricCard label="평균 지연" value={latency(stats.avgLatencyMs)} icon={<Gauge className="size-4" />} />
         <MetricCard label="p95 지연" value={latency(stats.p95LatencyMs)} hint="상위 5% 대기시간" />
-        <MetricCard label="토큰 사용량" value={stats.totalTokens.toLocaleString()} hint="최근 기간 누적" icon={<Coins className="size-4" />} />
+        <MetricCard
+          label="토큰 사용량"
+          value={stats.totalTokens.toLocaleString()}
+          hint={stats.cacheHitRate === null ? '최근 기간 누적' : `캐시 적중 ${stats.cacheHitRate}% (${stats.cachedTokens.toLocaleString()})`}
+          icon={<Coins className="size-4" />}
+        />
         <MetricCard label="총 생성 요청" value={stats.totalGenerations.toLocaleString()} hint="최근 기간" />
       </div>
 

src/main/kotlin/com/nexters/gamss/admin/controller/dto/QualityStatsResponse.kt

@@ -20,8 +20,12 @@ data class QualityStatsResponse(
     val avgLatencyMs: Long,
     @field:Schema(description = "p95 생성 지연(ms)", example = "5300")
     val p95LatencyMs: Long,
-    @field:Schema(description = "누적 토큰 사용량(최근 기간)", example = "184320")
+    @field:Schema(description = "누적 토큰 사용량(총합, 캐싱과 무관하게 처리된 전체 토큰)", example = "184320")
     val totalTokens: Long,
+    @field:Schema(description = "그중 컨텍스트 캐시로 처리돼 할인 과금된 토큰", example = "120500")
+    val cachedTokens: Long,
+    @field:Schema(description = "캐시 적중률(%). 총 토큰 대비 캐시 토큰 비율. 총 토큰이 0이면 null", example = "65.4", nullable = true)
+    val cacheHitRate: Double?,
     @field:Schema(description = "막힌 PENDING(고아 생성) 수 — 즉시 대응 필요 신호", example = "0")
     val stuckPending: Long,
     @field:Schema(description = "일별 생성 성공/실패 추이(오래된 날 → 오늘)")

src/main/kotlin/com/nexters/gamss/admin/service/QualityStatsService.kt

@@ -35,6 +35,8 @@ class QualityStatsService(
         val retried = logs.count { it.attemptCount > 1 }.toLong()
         val latencies = logs.map { it.latencyMs }.sorted()
         val stuckBefore = Instant.now().minus(conversationProperties.commentPendingTimeout)
+        val totalTokens = logs.sumOf { (it.usedTokens ?: 0).toLong() }
+        val cachedTokens = logs.sumOf { (it.cachedTokens ?: 0).toLong() }
 
         return QualityStatsResponse(
             totalGenerations = total,
@@ -45,7 +47,9 @@ class QualityStatsService(
             retryRate = percentageOrNull(retried, total),
             avgLatencyMs = if (latencies.isEmpty()) 0 else latencies.average().roundToLong(),
             p95LatencyMs = percentile(latencies, P95),
-            totalTokens = logs.sumOf { (it.usedTokens ?: 0).toLong() },
+            totalTokens = totalTokens,
+            cachedTokens = cachedTokens,
+            cacheHitRate = percentageOrNull(cachedTokens, totalTokens),
             stuckPending = messageRepository.countByCommentStatusOlderThan(CommentStatus.PENDING, stuckBefore),
             dailyGeneration = buildDailyGeneration(today, days, logs),
         )

src/main/kotlin/com/nexters/gamss/card/service/CardService.kt

@@ -10,6 +10,8 @@ import com.nexters.gamss.global.exception.BusinessException
 import com.nexters.gamss.global.exception.ErrorCode
 import com.nexters.gamss.llm.error.CardGenerationFailedException
 import com.nexters.gamss.llm.generation.CardMessageGenerator
+import com.nexters.gamss.monitoring.domain.GenerationType
+import com.nexters.gamss.monitoring.service.GenerationLogRecorder
 import org.springframework.dao.DataIntegrityViolationException
 import org.springframework.stereotype.Service
 import org.springframework.transaction.annotation.Transactional
@@ -26,6 +28,7 @@ class CardService(
     private val cardRepository: CardRepository,
     private val conversationRepository: ConversationRepository,
     private val cardMessageGenerator: CardMessageGenerator,
+    private val generationLogRecorder: GenerationLogRecorder,
 ) {
     /**
      * 종료된 대화에 대해 대표 감정 캐릭터의 한 줄 대사를 생성해 카드를 저장한다.
@@ -46,12 +49,28 @@ class CardService(
         if (cardRepository.existsByConversationId(conversationId)) {
             throw BusinessException(ErrorCode.CARD_ALREADY_EXISTS)
         }
+        val startedAt = System.currentTimeMillis()
         val output =
             try {
                 cardMessageGenerator.generate(emotion, summary)
             } catch (e: CardGenerationFailedException) {
+                generationLogRecorder.record(
+                    type = GenerationType.CARD,
+                    success = false,
+                    attemptCount = 1,
+                    latencyMs = System.currentTimeMillis() - startedAt,
+                    failureReason = (e.cause ?: e).javaClass.simpleName,
+                )
                 throw BusinessException(ErrorCode.CARD_GENERATION_FAILED, e.message)
             }
+        generationLogRecorder.record(
+            type = GenerationType.CARD,
+            success = true,
+            attemptCount = 1,
+            latencyMs = System.currentTimeMillis() - startedAt,
+            usedTokens = output.usedTokens,
+            cachedTokens = output.cachedTokens,
+        )
         val card =
             Card(
                 memberId = memberId,

src/main/kotlin/com/nexters/gamss/conversation/service/CommentGenerationService.kt

@@ -188,6 +188,7 @@ class CommentGenerationService(
                     attemptCount = attempt + 1,
                     latencyMs = System.currentTimeMillis() - startedAt,
                     usedTokens = output.usedTokens,
+                    cachedTokens = output.cachedTokens,
                 )
                 return output
             } catch (e: CommentGenerationFailedException) {
@@ -244,6 +245,7 @@ class CommentGenerationService(
                     attemptCount = attempt + 1,
                     latencyMs = System.currentTimeMillis() - startedAt,
                     usedTokens = output.usedTokens,
+                    cachedTokens = output.cachedTokens,
                 )
                 return output
             } catch (e: CommentGenerationFailedException) {

src/main/kotlin/com/nexters/gamss/llm/generation/CardMessageOutput.kt

@@ -4,4 +4,5 @@ package com.nexters.gamss.llm.generation
 data class CardMessageOutput(
     val message: String,
     val usedTokens: Int,
+    val cachedTokens: Int,
 )

src/main/kotlin/com/nexters/gamss/llm/generation/CommentGenerationOutput.kt

@@ -6,4 +6,5 @@ import com.nexters.gamss.llm.parsing.CommentFeed
 data class CommentGenerationOutput(
     val feed: CommentFeed,
     val usedTokens: Int,
+    val cachedTokens: Int,
 )

src/main/kotlin/com/nexters/gamss/llm/generation/GeminiCardMessageGenerator.kt

@@ -53,7 +53,8 @@ class GeminiCardMessageGenerator(
 
         val message = parseLine(text)
         val usedTokens = response.usageMetadata().flatMap { it.totalTokenCount() }.orElse(0)
-        return CardMessageOutput(message, usedTokens)
+        val cachedTokens = response.usageMetadata().flatMap { it.cachedContentTokenCount() }.orElse(0)
+        return CardMessageOutput(message, usedTokens, cachedTokens)
     }
 
     private fun parseLine(text: String): String {

src/main/kotlin/com/nexters/gamss/llm/generation/GeminiCommentGenerator.kt

@@ -64,7 +64,8 @@ class GeminiCommentGenerator(
 
         val feed = commentFeedJsonParser.parse(text)
         val usedTokens = response.usageMetadata().flatMap { it.totalTokenCount() }.orElse(0)
-        return CommentGenerationOutput(feed, usedTokens)
+        val cachedTokens = response.usageMetadata().flatMap { it.cachedContentTokenCount() }.orElse(0)
+        return CommentGenerationOutput(feed, usedTokens, cachedTokens)
     }
 
     override fun generateReply(
@@ -91,7 +92,8 @@ class GeminiCommentGenerator(
 
         val replyText = replyJsonParser.parse(text)
         val usedTokens = response.usageMetadata().flatMap { it.totalTokenCount() }.orElse(0)
-        return ReplyGenerationOutput(replyText, usedTokens)
+        val cachedTokens = response.usageMetadata().flatMap { it.cachedContentTokenCount() }.orElse(0)
+        return ReplyGenerationOutput(replyText, usedTokens, cachedTokens)
     }
 
     private fun buildConfig(

src/main/kotlin/com/nexters/gamss/llm/generation/ReplyGenerationOutput.kt

@@ -4,4 +4,5 @@ package com.nexters.gamss.llm.generation
 data class ReplyGenerationOutput(
     val text: String,
     val usedTokens: Int,
+    val cachedTokens: Int,
 )