feat(observability): 모니터링 API 공용 기반 + Redis 인프라 #29

kotlin.MODULE.bazel

@@ -24,4 +24,16 @@ maven.artifact(artifact = "protobuf-java", group = "com.google.protobuf", versio
 maven.artifact(artifact = "protobuf-kotlin", group = "com.google.protobuf", version = "4.30.2")
 maven.artifact(artifact = "javax.annotation-api", group = "javax.annotation", version = "1.3.2")
 
+# Redis
+maven.artifact(artifact = "spring-boot-starter-data-redis", group = "org.springframework.boot", version = "4.0.1")
+
+# JWT
+maven.artifact(artifact = "jjwt-api", group = "io.jsonwebtoken", version = "0.13.0")
+maven.artifact(artifact = "jjwt-impl", group = "io.jsonwebtoken", version = "0.13.0")
+maven.artifact(artifact = "jjwt-jackson", group = "io.jsonwebtoken", version = "0.13.0")
+
+# 리포트 생성 (xlsx)
+maven.artifact(artifact = "poi", group = "org.apache.poi", version = "5.4.0")
+maven.artifact(artifact = "poi-ooxml", group = "org.apache.poi", version = "5.4.0")
+
 use_repo(maven, "maven")

systems/observability/observability-adapter-in/BUILD.bazel

@@ -17,5 +17,5 @@ kt_jvm_test(
     javac_opts = "//:javac_options",
     kotlinc_opts = "//:kotlinc_options",
     test_class = "hs.kr.entrydsm.observability.adapterin.ObservabilityAdapterInModuleTest",
-    deps = MODULE_DEPS + TEST_DEPS,
+    deps = [":main"] + MODULE_DEPS + TEST_DEPS,
 )

systems/observability/observability-adapter-in/deps.bzl

@@ -1,4 +1,14 @@
-KOTLIN_DEPS = []
+KOTLIN_DEPS = [
+    "@maven//:org_springframework_boot_spring_boot_starter_web",
+    "@maven//:org_springframework_boot_spring_boot_starter_validation",
+    "@maven//:io_jsonwebtoken_jjwt_api",
+    "@maven//:io_jsonwebtoken_jjwt_impl",
+    "@maven//:io_jsonwebtoken_jjwt_jackson",
+    "@maven//:org_apache_poi_poi",
+    "@maven//:org_apache_poi_poi_ooxml",
+    "//systems/observability/observability-application:main",
+    "//systems/observability/observability-domain:main",
+]
 
 TEST_DEPS = [
     "@maven//:junit_junit",

systems/observability/observability-adapter-in/src/main/kotlin/hs/kr/entrydsm/observability/adapterin/web/dto/common/ApiResponse.kt

@@ -0,0 +1,7 @@
+package hs.kr.entrydsm.observability.adapterin.web.dto.common
+
+data class ApiResponse<T>(
+    val success: Boolean = true,
+    val data: T?,
+    val error: ErrorDetail? = null,
+)

systems/observability/observability-adapter-in/src/main/kotlin/hs/kr/entrydsm/observability/adapterin/web/dto/common/ErrorDetail.kt

@@ -0,0 +1,17 @@
+package hs.kr.entrydsm.observability.adapterin.web.dto.common
+
+import hs.kr.entrydsm.observability.domain.enum.ErrorCode
+
+data class ErrorDetail(
+    val code: String,
+    val message: String,
+    val status: Int,
+) {
+    companion object {
+        fun from(errorCode: ErrorCode) = ErrorDetail(
+            errorCode.name,
+            errorCode.message,
+            errorCode.status,
+        )
+    }
+}

systems/observability/observability-adapter-in/src/main/kotlin/hs/kr/entrydsm/observability/adapterin/web/dto/common/ErrorResponse.kt

@@ -0,0 +1,9 @@
+package hs.kr.entrydsm.observability.adapterin.web.dto.common
+
+import java.time.Instant
+
+data class ErrorResponse(
+    val success: Boolean = false,
+    val error: ErrorDetail,
+    val timestamp: Instant = Instant.now(),
+)

systems/observability/observability-adapter-in/src/main/kotlin/hs/kr/entrydsm/observability/adapterin/web/exception/GlobalExceptionHandler.kt

@@ -0,0 +1,62 @@
+package hs.kr.entrydsm.observability.adapterin.web.exception
+
+import hs.kr.entrydsm.observability.adapterin.web.dto.common.ErrorDetail
+import hs.kr.entrydsm.observability.adapterin.web.dto.common.ErrorResponse
+import hs.kr.entrydsm.observability.domain.enum.ErrorCode
+import hs.kr.entrydsm.observability.domain.exception.MonitorException
+import jakarta.validation.ConstraintViolationException
+import org.slf4j.LoggerFactory
+import org.slf4j.MDC
+import org.springframework.http.ResponseEntity
+import org.springframework.http.converter.HttpMessageNotReadableException
+import org.springframework.validation.BindException
+import org.springframework.web.bind.MethodArgumentNotValidException
+import org.springframework.web.bind.MissingPathVariableException
+import org.springframework.web.bind.MissingRequestHeaderException
+import org.springframework.web.bind.MissingServletRequestParameterException
+import org.springframework.web.bind.annotation.ExceptionHandler
+import org.springframework.web.bind.annotation.RestControllerAdvice
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException
+import org.springframework.web.multipart.support.MissingServletRequestPartException
+
+@RestControllerAdvice
+class GlobalExceptionHandler {
+    private val logger = LoggerFactory.getLogger(javaClass)
+
+    @ExceptionHandler(MonitorException::class)
+    fun handleMonitorException(exception: MonitorException): ResponseEntity<ErrorResponse> =
+        response(exception.errorCode)
+
+    @ExceptionHandler(
+        HttpMessageNotReadableException::class,
+        BindException::class,
+        ConstraintViolationException::class,
+        MethodArgumentNotValidException::class,
+        MissingPathVariableException::class,
+        MissingRequestHeaderException::class,
+        MissingServletRequestParameterException::class,
+        MissingServletRequestPartException::class,
+        MethodArgumentTypeMismatchException::class,
+    )
+    fun handleInvalidRequest(exception: Exception): ResponseEntity<ErrorResponse> =
+        response(ErrorCode.INVALID_PAYLOAD)
+
+    @ExceptionHandler(Exception::class)
+    fun handleUnhandledException(exception: Exception): ResponseEntity<ErrorResponse> =
+        response(ErrorCode.INTERNAL_SERVER_ERROR).also {
+            logger.error(
+                "Unhandled exception [X-trace-Id={}]",
+                MDC.get("X-trace-Id") ?: "unknown",
+                exception,
+            )
+        }
+
+    private fun response(errorCode: ErrorCode): ResponseEntity<ErrorResponse> =
+        ResponseEntity
+            .status(errorCode.status)
+            .body(
+                ErrorResponse(
+                    error = ErrorDetail.from(errorCode)
+                ),
+            )
+}

systems/observability/observability-adapter-in/src/test/kotlin/hs/kr/entrydsm/TestMain.kt

@@ -1,11 +1,11 @@
 package hs.kr.entrydsm.observability.adapterin
 
-import org.junit.Assert.assertTrue
-import org.junit.Test
+import hs.kr.entrydsm.observability.adapterin.web.exception.GlobalExceptionHandlerTest
+import org.junit.runner.RunWith
+import org.junit.runners.Suite
 
-class ObservabilityAdapterInModuleTest {
-    @Test
-    fun moduleLoads() {
-        assertTrue(true)
-    }
-}
+@RunWith(Suite::class)
+@Suite.SuiteClasses(
+    GlobalExceptionHandlerTest::class,
+)
+class ObservabilityAdapterInModuleTest

systems/observability/observability-adapter-in/src/test/kotlin/hs/kr/entrydsm/observability/adapterin/web/exception/GlobalExceptionHandlerTest.kt

@@ -0,0 +1,57 @@
+package hs.kr.entrydsm.observability.adapterin.web.exception
+
+import hs.kr.entrydsm.observability.domain.enum.ErrorCode
+import hs.kr.entrydsm.observability.domain.exception.MonitorDomainException
+import jakarta.validation.ConstraintViolationException
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.slf4j.MDC
+import org.springframework.validation.BindException
+
+class GlobalExceptionHandlerTest {
+    private val handler = GlobalExceptionHandler()
+
+    @Test
+    fun mapsMonitorExceptionToItsErrorResponse() {
+        val response = handler.handleMonitorException(MonitorDomainException(ErrorCode.SESSION_NOT_FOUND))
+
+        assertEquals(404, response.statusCode.value())
+        assertEquals("SESSION_NOT_FOUND", response.body?.error?.code)
+        assertEquals(ErrorCode.SESSION_NOT_FOUND.message, response.body?.error?.message)
+    }
+
+    @Test
+    fun mapsInvalidRequestToBadRequestResponse() {
+        val response = handler.handleInvalidRequest(IllegalArgumentException())
+
+        assertEquals(400, response.statusCode.value())
+        assertEquals("INVALID_PAYLOAD", response.body?.error?.code)
+    }
+
+    @Test
+    fun mapsValidationExceptionsToBadRequestResponse() {
+        val responses = listOf(
+            handler.handleInvalidRequest(BindException(this, "request")),
+            handler.handleInvalidRequest(ConstraintViolationException(emptySet())),
+        )
+
+        responses.forEach { response ->
+            assertEquals(400, response.statusCode.value())
+            assertEquals("INVALID_PAYLOAD", response.body?.error?.code)
+        }
+    }
+
+    @Test
+    fun keepsGenericResponseAndLogsCorrelationContextForUnhandledException() {
+        MDC.put("X-trace-Id", "test-trace-id")
+        try {
+            val response = handler.handleUnhandledException(IllegalStateException("internal detail"))
+
+            assertEquals(500, response.statusCode.value())
+            assertEquals("INTERNAL_SERVER_ERROR", response.body?.error?.code)
+            assertEquals(ErrorCode.INTERNAL_SERVER_ERROR.message, response.body?.error?.message)
+        } finally {
+            MDC.remove("X-trace-Id")
+        }
+    }
+}

systems/observability/observability-adapter-out/BUILD.bazel

@@ -17,5 +17,5 @@ kt_jvm_test(
     javac_opts = "//:javac_options",
     kotlinc_opts = "//:kotlinc_options",
     test_class = "hs.kr.entrydsm.observability.adapterout.ObservabilityAdapterOutModuleTest",
-    deps = MODULE_DEPS + TEST_DEPS,
+    deps = [":main"] + MODULE_DEPS + TEST_DEPS,
 )

systems/observability/observability-adapter-out/deps.bzl

@@ -1,4 +1,8 @@
-KOTLIN_DEPS = []
+KOTLIN_DEPS = [
+    "@maven//:org_springframework_boot_spring_boot_starter_data_redis",
+    "//systems/observability/observability-application:main",
+    "//systems/observability/observability-domain:main",
+]
 
 TEST_DEPS = [
     "@maven//:junit_junit",

systems/observability/observability-adapter-out/src/main/kotlin/hs/kr/entrydsm/observability/adapterout/redis/RedisRateLimitAdapter.kt

@@ -0,0 +1,22 @@
+package hs.kr.entrydsm.observability.adapterout.redis
+
+import hs.kr.entrydsm.observability.application.port.out.RateLimitPort
+import java.time.Duration
+import org.springframework.data.redis.core.StringRedisTemplate
+import org.springframework.stereotype.Component
+
+/** IP 기준 고정 윈도우 카운터. 이미 Redis를 쓰므로 별도 rate-limit 라이브러리 없이 INCR+EXPIRE로 구현한다. */
+@Component
+class RedisRateLimitAdapter(
+    private val redis: StringRedisTemplate,
+) : RateLimitPort {
+    override fun tryAcquire(key: String, limit: Long, windowSeconds: Long): Boolean {
+        val bucket = System.currentTimeMillis() / (windowSeconds * 1000)
+        val redisKey = "monitor:ratelimit:$key:$bucket"
+        val count = redis.opsForValue().increment(redisKey) ?: 1L
+        if (count == 1L) {
+            redis.expire(redisKey, Duration.ofSeconds(windowSeconds))
+        }
+        return count <= limit
+    }
+}

systems/observability/observability-adapter-out/src/main/kotlin/hs/kr/entrydsm/observability/adapterout/redis/RedisSessionStoreAdapter.kt

@@ -0,0 +1,124 @@
+package hs.kr.entrydsm.observability.adapterout.redis
+
+import hs.kr.entrydsm.observability.application.port.out.SessionStorePort
+import hs.kr.entrydsm.observability.domain.enum.DeviceType
+import hs.kr.entrydsm.observability.domain.enum.ServiceName
+import java.time.Duration
+import java.time.Instant
+import org.springframework.data.redis.core.StringRedisTemplate
+import org.springframework.stereotype.Component
+
+/**
+ * 세션·트래픽 집계를 Redis에 저장한다.
+ * ponytail: 다중 인스턴스에서도 Redis가 단일 소스라 별도 확장 작업 없이 그대로 동작한다.
+ */
+@Component
+class RedisSessionStoreAdapter(
+    private val redis: StringRedisTemplate,
+) : SessionStorePort {
+
+    override fun enter(sessionId: String, service: ServiceName, deviceType: DeviceType, now: Instant) {
+        val nowMillis = now.toEpochMilli()
+        val hashOps = redis.opsForHash<String, String>()
+        hashOps.putAll(
+            metaKey(sessionId),
+            mapOf(
+                FIELD_SERVICE to service.name,
+                FIELD_ENTERED_AT to nowMillis.toString(),
+                FIELD_LAST_HEARTBEAT_AT to nowMillis.toString(),
+            ),
+        )
+        redis.expire(metaKey(sessionId), SESSION_TTL)
+        touchWindow(sessionId, service, nowMillis)
+        redis.opsForSet().add(VISITORS_KEY, sessionId)
+        hashOps.increment(DEVICE_COUNTS_KEY, deviceType.name, 1)
+    }
+
+    override fun heartbeat(sessionId: String, service: ServiceName, now: Instant): Boolean {
+        if (!redis.hasKey(metaKey(sessionId))) return false
+        val nowMillis = now.toEpochMilli()
+        val hashOps = redis.opsForHash<String, String>()
+        hashOps.put(metaKey(sessionId), FIELD_SERVICE, service.name)
+        hashOps.put(metaKey(sessionId), FIELD_LAST_HEARTBEAT_AT, nowMillis.toString())
+        redis.expire(metaKey(sessionId), SESSION_TTL)
+        touchWindow(sessionId, service, nowMillis)
+        return true
+    }
+
+    override fun leave(sessionId: String, service: ServiceName, now: Instant): Boolean {
+        val meta = redis.opsForHash<String, String>().entries(metaKey(sessionId))
+        if (meta.isEmpty()) return false
+        meta[FIELD_ENTERED_AT]?.toLongOrNull()?.let { enteredAt ->
+            val durationSeconds = (now.toEpochMilli() - enteredAt) / 1000
+            redis.opsForValue().increment(DURATION_SUM_KEY, durationSeconds)
+            redis.opsForValue().increment(DURATION_COUNT_KEY)
+        }
+        redis.delete(metaKey(sessionId))
+        ServiceName.entries.forEach { redis.opsForZSet().remove(windowKey(it), sessionId) }
+        redis.opsForZSet().remove(ALL_WINDOW_KEY, sessionId)
+        return true
+    }
+
+    override fun concurrentUsers(service: ServiceName?, now: Instant, windowSeconds: Long): Int {
+        val key = service?.let { windowKey(it) } ?: ALL_WINDOW_KEY
+        val min = (now.toEpochMilli() - windowSeconds * 1000).toDouble()
+        return (redis.opsForZSet().count(key, min, Double.MAX_VALUE) ?: 0L).toInt()
+    }
+
+    override fun totalVisitors(): Long = redis.opsForSet().size(VISITORS_KEY) ?: 0L
+
+    override fun avgSessionDurationSeconds(): Long {
+        val sum = redis.opsForValue().get(DURATION_SUM_KEY)?.toLongOrNull() ?: 0L
+        val count = redis.opsForValue().get(DURATION_COUNT_KEY)?.toLongOrNull() ?: 0L
+        return if (count == 0L) 0L else sum / count
+    }
+
+    override fun deviceBreakdown(): Map<DeviceType, Long> {
+        val entries = redis.opsForHash<String, String>().entries(DEVICE_COUNTS_KEY)
+        return DeviceType.entries.associateWith { entries[it.name]?.toLongOrNull() ?: 0L }
+    }
+
+    override fun sampleConcurrency(now: Instant, windowSeconds: Long) {
+        val current = concurrentUsers(null, now, windowSeconds)
+        val currentMax = redis.opsForValue().get(CONCURRENT_MAX_KEY)?.toIntOrNull() ?: 0
+        if (current > currentMax) {
+            redis.opsForValue().set(CONCURRENT_MAX_KEY, current.toString())
+        }
+        redis.opsForValue().increment(CONCURRENT_SUM_KEY, current.toLong())
+        redis.opsForValue().increment(CONCURRENT_SAMPLES_KEY)
+    }
+
+    override fun concurrentMax(): Int = redis.opsForValue().get(CONCURRENT_MAX_KEY)?.toIntOrNull() ?: 0
+
+    override fun concurrentAvg(): Int {
+        val sum = redis.opsForValue().get(CONCURRENT_SUM_KEY)?.toLongOrNull() ?: 0L
+        val samples = redis.opsForValue().get(CONCURRENT_SAMPLES_KEY)?.toLongOrNull() ?: 0L
+        return if (samples == 0L) 0 else (sum / samples).toInt()
+    }
+
+    private fun touchWindow(sessionId: String, service: ServiceName, nowMillis: Long) {
+        redis.opsForZSet().add(windowKey(service), sessionId, nowMillis.toDouble())
+        redis.opsForZSet().add(ALL_WINDOW_KEY, sessionId, nowMillis.toDouble())
+        redis.expire(windowKey(service), SESSION_TTL)
+        redis.expire(ALL_WINDOW_KEY, SESSION_TTL)
+    }
+
+    private fun metaKey(sessionId: String) = "monitor:session:meta:$sessionId"
+
+    private fun windowKey(service: ServiceName) = "monitor:session:window:${service.name}"
+
+    companion object {
+        private const val VISITORS_KEY = "monitor:visitors:all"
+        private const val DEVICE_COUNTS_KEY = "monitor:device:counts"
+        private const val DURATION_SUM_KEY = "monitor:duration:sum"
+        private const val DURATION_COUNT_KEY = "monitor:duration:count"
+        private const val CONCURRENT_MAX_KEY = "monitor:concurrent:max"
+        private const val CONCURRENT_SUM_KEY = "monitor:concurrent:sum"
+        private const val CONCURRENT_SAMPLES_KEY = "monitor:concurrent:samples"
+        private const val ALL_WINDOW_KEY = "monitor:session:window:ALL"
+        private const val FIELD_SERVICE = "service"
+        private const val FIELD_ENTERED_AT = "enteredAt"
+        private const val FIELD_LAST_HEARTBEAT_AT = "lastHeartbeatAt"
+        private val SESSION_TTL: Duration = Duration.ofHours(6)
+    }
+}

systems/observability/observability-application/BUILD.bazel

@@ -17,5 +17,5 @@ kt_jvm_test(
     javac_opts = "//:javac_options",
     kotlinc_opts = "//:kotlinc_options",
     test_class = "hs.kr.entrydsm.observability.application.ObservabilityApplicationModuleTest",
-    deps = MODULE_DEPS + TEST_DEPS,
+    deps = [":main"] + MODULE_DEPS + TEST_DEPS,
 )

systems/observability/observability-application/deps.bzl

@@ -1,4 +1,7 @@
-KOTLIN_DEPS = []
+KOTLIN_DEPS = [
+    "@maven//:org_springframework_boot_spring_boot_starter",
+    "//systems/observability/observability-domain:main",
+]
 
 TEST_DEPS = [
     "@maven//:junit_junit",