PoolMetrics 추가 (metrics() method)

PythonEmbedPool에 PoolMetrics 레코드와 metrics() 메서드를 추가합니다.

- PoolMetrics: poolSize, activeCount, idleCount, minPool, maxPool, uptimeMs 레코드
- PythonEmbedPool: createdAt 필드와 metrics() 퍼블릭 메서드 추가
- PythonEmbedPoolTest: 스냅샷, busy/idle, scale-up, uptime 검증 4개 테스트 추가

Author: white

python-embed-runtime/src/main/java/io/github/howtis/pythonembed/PoolMetrics.java

@@ -0,0 +1,17 @@
+package io.github.howtis.pythonembed;
+
+/**
+ * A point-in-time snapshot of {@link PythonEmbedPool} metrics.
+ *
+ * <p>Obtained via {@link PythonEmbedPool#metrics()}. All values reflect
+ * the pool's state at the moment of the call and may change immediately
+ * afterward.
+ */
+public record PoolMetrics(
+        int poolSize,
+        int activeCount,
+        int idleCount,
+        int minPool,
+        int maxPool,
+        long uptimeMs) {
+}

python-embed-runtime/src/main/java/io/github/howtis/pythonembed/PythonEmbedPool.java

@@ -80,6 +80,7 @@ public class PythonEmbedPool implements AutoCloseable {
     private final Condition instanceAvailable = instanceLock.newCondition();
     private volatile long lastHealthCheckAt;
     private volatile boolean closed;
+    private final long createdAt;
 
     private final Map<String, CallbackHandler> callbackHandlers = new ConcurrentHashMap<>();
     private final Map<String, PushHandler> pushHandlers = new ConcurrentHashMap<>();
@@ -195,6 +196,7 @@ private PythonEmbedPool(Builder b) {
         this.healthCheckIntervalMs = b.healthCheckIntervalMs;
         this.options = b.options;
         this.onInstanceRemoved = b.onInstanceRemoved;
+        this.createdAt = System.currentTimeMillis();
 
         this.instances = new ConcurrentLinkedDeque<>();
         this.currentSize = new AtomicInteger(0);
@@ -781,6 +783,27 @@ public int maxPool() {
         return maxPool;
     }
 
+    /**
+     * Returns a point-in-time snapshot of pool metrics.
+     *
+     * <p>The returned {@link PoolMetrics} reflects the pool's state
+     * at the moment of the call. Values may change immediately afterward
+     * due to concurrent activity.
+     *
+     * @return a snapshot of current pool metrics
+     */
+    public PoolMetrics metrics() {
+        int size = size();
+        int active = activeCount();
+        return new PoolMetrics(
+                size,
+                active,
+                size - active,
+                minPool,
+                maxPool,
+                System.currentTimeMillis() - createdAt);
+    }
+
     // ------------------------------------------------------------------
     // Lifecycle
     // ------------------------------------------------------------------

python-embed-runtime/src/test/java/io/github/howtis/pythonembed/PythonEmbedPoolTest.java

@@ -1694,6 +1694,121 @@ void close_timeout_zero() throws Exception {
                 "close(0, SECONDS) should return quickly, elapsed=" + elapsed + "ms");
     }
 
+    // ---- D4: Pool Metrics ----
+
+    @Test
+    void metrics_snapshotAfterBuild() throws Exception {
+        PythonEmbedPool pool = PythonEmbedPool.builder().minPool(2).maxPool(4).build();
+        try {
+            waitForPoolSize(pool, 2, 5000);
+
+            PoolMetrics m = pool.metrics();
+            assertEquals(2, m.poolSize());
+            assertEquals(0, m.activeCount());
+            assertEquals(2, m.idleCount());
+            assertEquals(2, m.minPool());
+            assertEquals(4, m.maxPool());
+            assertTrue(m.uptimeMs() >= 0, "uptimeMs should be non-negative");
+        } finally {
+            pool.close();
+        }
+    }
+
+    @Test
+    @Timeout(value = 30, unit = TimeUnit.SECONDS)
+    void metrics_idleCount_reflectsBusyInstances() throws Exception {
+        PythonEmbedPool pool = PythonEmbedPool.builder().maxPool(2).build();
+        try {
+            // Use exec instead of eval because Python eval() does not
+            // allow statement-level constructs like import + sleep.
+            CompletableFuture<Void> task = pool.exec(
+                    "import time; time.sleep(3)");
+
+            // Poll until the task is acquired and instance becomes busy
+            long deadline = System.currentTimeMillis() + 5000;
+            while (pool.activeCount() == 0 && System.currentTimeMillis() < deadline) {
+                Thread.sleep(50);
+            }
+
+            PoolMetrics m = pool.metrics();
+            assertEquals(1, m.poolSize());
+            assertEquals(1, m.activeCount(), "Instance should be busy while task runs");
+            assertEquals(0, m.idleCount());
+
+            task.get(10, TimeUnit.SECONDS);
+
+            // Poll until instance is released
+            deadline = System.currentTimeMillis() + 5000;
+            while (pool.activeCount() > 0 && System.currentTimeMillis() < deadline) {
+                Thread.sleep(50);
+            }
+            m = pool.metrics();
+            assertEquals(1, m.poolSize());
+            assertEquals(0, m.activeCount(), "Instance should be idle after task completes");
+            assertEquals(1, m.idleCount());
+        } finally {
+            pool.close();
+        }
+    }
+
+    @Test
+    @Timeout(value = 30, unit = TimeUnit.SECONDS)
+    void metrics_idleCount_afterScaleUp() throws Exception {
+        PythonEmbedPool pool = PythonEmbedPool.builder().minPool(1).maxPool(2).build();
+        try {
+            // Submit two long-running tasks to trigger scale-up
+            CompletableFuture<Void> t1 = pool.exec(
+                    "import time; time.sleep(3)");
+            // Poll until first task makes the instance busy
+            long deadline = System.currentTimeMillis() + 5000;
+            while (pool.activeCount() == 0 && System.currentTimeMillis() < deadline) {
+                Thread.sleep(50);
+            }
+            CompletableFuture<Void> t2 = pool.exec(
+                    "import time; time.sleep(3)");
+
+            waitForPoolSize(pool, 2, 5000);
+
+            PoolMetrics m = pool.metrics();
+            assertEquals(2, m.poolSize());
+            assertEquals(2, m.activeCount(),
+                    "Both instances should be busy during concurrent execution");
+            assertEquals(0, m.idleCount());
+
+            t1.get(10, TimeUnit.SECONDS);
+            t2.get(10, TimeUnit.SECONDS);
+
+            // Poll until both instances are released
+            deadline = System.currentTimeMillis() + 5000;
+            while (pool.activeCount() > 0 && System.currentTimeMillis() < deadline) {
+                Thread.sleep(50);
+            }
+            m = pool.metrics();
+            assertEquals(0, m.activeCount(),
+                    "All instances should be idle after tasks complete");
+            assertEquals(2, m.idleCount());
+        } finally {
+            pool.close();
+        }
+    }
+
+    @Test
+    void metrics_uptimeMs_increases() throws Exception {
+        PythonEmbedPool pool = PythonEmbedPool.builder().maxPool(1).build();
+        try {
+            PoolMetrics m1 = pool.metrics();
+            Thread.sleep(200);
+            PoolMetrics m2 = pool.metrics();
+
+            assertTrue(m2.uptimeMs() > m1.uptimeMs(),
+                    "uptimeMs should increase over time");
+            assertTrue(m2.uptimeMs() >= 200,
+                    "uptimeMs should be at least the sleep duration");
+        } finally {
+            pool.close();
+        }
+    }
+
     /**
      * Waits for the pool to reach the given size, polling every 100ms.
      */