@gravito/monitor 3.0.0 → 3.1.0

package/README.md

@@ -1,14 +1,15 @@
-# @gravito/monitor
+# @gravito/monitor 🛰️
 
-Lightweight observability module for Gravito - Health Checks, Metrics, and Tracing.
+Lightweight observability module for Gravito - Health Checks, Metrics, and Tracing. Built on top of the **Galaxy Architecture**, this Orbit provides essential infrastructure for monitoring your planet's health.
 
-## Features
+## 🚀 Features
 
-- 🏥 **Health Checks** - Kubernetes-ready `/health`, `/ready`, `/live` endpoints
-- 📊 **Metrics** - Prometheus-compatible `/metrics` endpoint
-- 🔍 **Tracing** - OpenTelemetry OTLP support (via external Collector)
+- 🏥 **Health Checks** - Kubernetes-ready `/health`, `/ready`, `/live` endpoints with custom check support.
+- 📊 **Metrics** - Prometheus-compatible `/metrics` endpoint with built-in Node.js runtime and HTTP metrics.
+- 🔍 **Tracing** - OpenTelemetry OTLP support for distributed tracing across services.
+- 🛡️ **Kubernetes Native** - Seamless integration with probe configurations and Prometheus ServiceMonitors.
 
-## Installation
+## 📦 Installation
 
 ```bash
 bun add @gravito/monitor
@@ -20,7 +21,9 @@ For OpenTelemetry tracing (optional):
 bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
 ```
 
-## Quick Start
+## 🌌 Quick Start
+
+Enable observability by adding the `MonitorOrbit` to your `PlanetCore`.
 
 ```typescript
 import { PlanetCore } from '@gravito/core'
@@ -32,274 +35,136 @@ core.orbit(new MonitorOrbit({
   health: {
     enabled: true,
     path: '/health',
-    readyPath: '/ready',
-    livePath: '/live',
   },
   metrics: {
     enabled: true,
-    path: '/metrics',
     prefix: 'myapp_',
   },
   tracing: {
-    enabled: true,
-    serviceName: 'my-gravito-app',
-    endpoint: 'http://localhost:4318/v1/traces',
+    enabled: process.env.NODE_ENV === 'production',
+    serviceName: 'order-service',
   },
 }))
 
 await core.liftoff()
 ```
 
-## Health Checks
+## 🏥 Health Checks
 
-### Default Endpoints
+The health system provides three distinct probes following Kubernetes best practices:
 
-| Endpoint | Description |
-|----------|-------------|
-| `GET /health` | Full health check with all registered checks |
-| `GET /ready` | Kubernetes readiness probe |
-| `GET /live` | Kubernetes liveness probe |
+- **Liveness (`/live`)**: Indicates if the process is running.
+- **Readiness (`/ready`)**: Indicates if the app is ready to serve traffic (waits for all checks to pass).
+- **Health (`/health`)**: Full aggregated report of all registered checks.
 
 ### Registering Custom Checks
 
+You can register custom health checks via the `monitor` service.
+
 ```typescript
 const monitor = core.services.get('monitor')
 
-// Register a database check
+// Simple check
 monitor.health.register('database', async () => {
-  const isConnected = await db.ping()
-  return isConnected 
-    ? { status: 'healthy' }
-    : { status: 'unhealthy', message: 'Database disconnected' }
-})
-
-// Register a Redis check
-monitor.health.register('redis', async () => {
-  const result = await redis.ping()
-  return { status: result === 'PONG' ? 'healthy' : 'unhealthy' }
+  const isOk = await db.ping()
+  return isOk ? { status: 'healthy' } : { status: 'unhealthy', message: 'DB down' }
 })
-```
-
-### Built-in Check Factories
-
-```typescript
-import { 
-  createDatabaseCheck, 
-  createRedisCheck, 
-  createMemoryCheck,
-  createHttpCheck 
-} from '@gravito/monitor'
 
-// Database check
-monitor.health.register('db', createDatabaseCheck(() => db.isConnected()))
-
-// Memory check (warns at 90% heap usage)
-monitor.health.register('memory', createMemoryCheck({ maxHeapUsedPercent: 90 }))
-
-// External service check
-monitor.health.register('api', createHttpCheck('https://api.example.com/health'))
-```
-
-### Health Response Format
-
-```json
-{
-  "status": "healthy",
-  "timestamp": "2024-12-25T12:00:00Z",
-  "uptime": 3600,
-  "checks": {
-    "database": { "status": "healthy", "latency": 5 },
-    "redis": { "status": "healthy", "latency": 2 },
-    "memory": { 
-      "status": "healthy", 
-      "details": { "heapUsedPercent": "45.2" } 
-    }
+// Detailed check
+monitor.health.register('disk_space', () => {
+  const usage = getDiskUsage()
+  return {
+    status: usage < 90 ? 'healthy' : 'degraded',
+    details: { usage: `${usage}%` }
   }
-}
+})
 ```
 
-## Metrics
-
-### Prometheus Endpoint
+## 📊 Metrics
 
-The `/metrics` endpoint exposes metrics in Prometheus text format:
+Metrics are exposed in Prometheus text format at `/metrics`. 
 
-```
-# HELP myapp_http_requests_total Total HTTP requests
-# TYPE myapp_http_requests_total counter
-myapp_http_requests_total{method="GET",path="/api/users",status="200"} 150
-
-# HELP myapp_http_request_duration_seconds HTTP request duration
-# TYPE myapp_http_request_duration_seconds histogram
-myapp_http_request_duration_seconds_bucket{le="0.01"} 50
-myapp_http_request_duration_seconds_bucket{le="0.1"} 120
-myapp_http_request_duration_seconds_sum 12.5
-myapp_http_request_duration_seconds_count 150
-```
+### Built-in Metrics
+- **Runtime**: Heap usage, uptime, active handles.
+- **HTTP**: Request total (`http_requests_total`), duration histogram (`http_request_duration_seconds`).
 
 ### Custom Metrics
 
 ```typescript
 const monitor = core.services.get('monitor')
 
-// Counter
-const requestCounter = monitor.metrics.counter({
-  name: 'api_requests_total',
-  help: 'Total API requests',
-  labels: ['endpoint', 'status'],
+// 1. Counter (Monotonically increasing)
+const orders = monitor.metrics.counter({
+  name: 'orders_total',
+  help: 'Total orders processed',
+  labels: ['status']
 })
-requestCounter.inc({ endpoint: '/users', status: '200' })
+orders.inc({ status: 'completed' })
 
-// Gauge
-const activeConnections = monitor.metrics.gauge({
-  name: 'active_connections',
-  help: 'Current active connections',
+// 2. Gauge (Can go up and down)
+const activeUsers = monitor.metrics.gauge({
+  name: 'active_users',
+  help: 'Current active users'
 })
-activeConnections.set(42)
-activeConnections.inc()
-activeConnections.dec()
-
-// Histogram
-const responseTime = monitor.metrics.histogram({
-  name: 'response_time_seconds',
-  help: 'Response time in seconds',
-  labels: ['endpoint'],
-  buckets: [0.01, 0.05, 0.1, 0.5, 1],
-})
-responseTime.observe(0.125, { endpoint: '/users' })
+activeUsers.set(42)
 
-// Timer helper
-const stopTimer = responseTime.startTimer({ endpoint: '/users' })
-// ... do work ...
-stopTimer() // Records duration automatically
+// 3. Histogram (Value distribution)
+const processTime = monitor.metrics.histogram({
+  name: 'order_processing_seconds',
+  help: 'Time to process orders',
+  buckets: [0.1, 0.5, 1, 2, 5]
+})
+const stop = processTime.startTimer()
+// ... logic ...
+stop()
 ```
 
-## Tracing
-
-### OpenTelemetry Integration
+## 🔍 Tracing
 
-@gravito/monitor uses the **OTLP (OpenTelemetry Protocol)** standard. To send traces to different backends:
-
-| Backend | Method |
-|---------|--------|
-| **Jaeger** | OTLP Collector → Jaeger |
-| **Zipkin** | OTLP Collector → Zipkin |
-| **AWS X-Ray** | AWS ADOT Collector |
-| **Google Cloud Trace** | GCP OTLP Collector |
-| **Datadog** | Datadog Agent (OTLP) |
+Distributed tracing is powered by OpenTelemetry (OTLP). It automatically propagates trace context via W3C `traceparent` headers.
 
 ### Configuration
-
 ```typescript
-new MonitorOrbit({
-  tracing: {
-    enabled: true,
-    serviceName: 'my-app',
-    serviceVersion: '1.0.0',
-    endpoint: 'http://localhost:4318/v1/traces', // OTLP HTTP
-    sampleRate: 1.0, // 100% sampling
-    resourceAttributes: {
-      'deployment.environment': 'production',
-    },
-  },
-})
+tracing: {
+  enabled: true,
+  serviceName: 'gateway',
+  endpoint: 'http://otel-collector:4318/v1/traces',
+  sampleRate: 0.1, // Sample 10% of requests
+  resourceAttributes: {
+    env: 'production'
+  }
+}
 ```
 
 ### Manual Spans
-
 ```typescript
 const tracer = core.services.get('tracing')
 
-// Start a span
-const span = tracer.startSpan('process-order', {
-  attributes: { 'order.id': '12345' },
-})
-
+const span = tracer.startSpan('compute_heavy_logic')
 try {
-  // Do work...
-  tracer.addEvent(span, 'payment-processed')
-  tracer.setAttribute(span, 'order.total', 99.99)
+  // ... work ...
+  tracer.setAttribute(span, 'items_count', 100)
   tracer.endSpan(span, 'ok')
-} catch (error) {
+} catch (e) {
   tracer.endSpan(span, 'error')
-  throw error
 }
 ```
 
-### Trace Context Propagation
-
-The tracing middleware automatically:
-- Extracts `traceparent` header from incoming requests
-- Injects trace context into outgoing requests
-- Records HTTP method, path, status code
-
-## Kubernetes Integration
-
-### Deployment Example
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: my-gravito-app
-spec:
-  template:
-    spec:
-      containers:
-        - name: app
-          image: my-app:latest
-          ports:
-            - containerPort: 3000
-          livenessProbe:
-            httpGet:
-              path: /live
-              port: 3000
-            initialDelaySeconds: 5
-            periodSeconds: 10
-          readinessProbe:
-            httpGet:
-              path: /ready
-              port: 3000
-            initialDelaySeconds: 5
-            periodSeconds: 5
-```
-
-### ServiceMonitor for Prometheus
-
-```yaml
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: my-gravito-app
-spec:
-  selector:
-    matchLabels:
-      app: my-gravito-app
-  endpoints:
-    - port: http
-      path: /metrics
-      interval: 15s
-```
-
-## Configuration Reference
+## ⚙️ Configuration Reference
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `health.enabled` | boolean | `true` | Enable health endpoints |
-| `health.path` | string | `/health` | Full health check path |
-| `health.readyPath` | string | `/ready` | Readiness probe path |
-| `health.livePath` | string | `/live` | Liveness probe path |
-| `health.timeout` | number | `5000` | Check timeout (ms) |
-| `health.cacheTtl` | number | `0` | Cache duration (ms) |
-| `metrics.enabled` | boolean | `true` | Enable metrics endpoint |
-| `metrics.path` | string | `/metrics` | Metrics endpoint path |
-| `metrics.prefix` | string | `gravito_` | Metric name prefix |
-| `metrics.defaultMetrics` | boolean | `true` | Collect default metrics |
-| `tracing.enabled` | boolean | `false` | Enable tracing |
-| `tracing.serviceName` | string | `gravito-app` | Service name |
-| `tracing.endpoint` | string | `http://localhost:4318/v1/traces` | OTLP endpoint |
-| `tracing.sampleRate` | number | `1.0` | Sample rate (0.0-1.0) |
-
-## License
-
-MIT
+| `health.enabled` | `boolean` | `true` | Enable health endpoints |
+| `health.path` | `string` | `/health` | Path for aggregated health check |
+| `health.timeout` | `number` | `5000` | Timeout for checks in ms |
+| `health.cacheTtl` | `number` | `0` | Cache results in ms (0 = disabled) |
+| `metrics.enabled` | `boolean` | `true` | Enable Prometheus endpoint |
+| `metrics.prefix` | `string` | `gravito_` | Metric name prefix |
+| `metrics.defaultMetrics` | `boolean` | `true` | Collect Node.js runtime metrics |
+| `tracing.enabled` | `boolean` | `false` | Enable OpenTelemetry tracing |
+| `tracing.endpoint` | `string` | `http://localhost:4318/v1/traces` | OTLP Collector URL |
+| `tracing.sampleRate` | `number` | `1.0` | Probability sampling (0.0 - 1.0) |
+
+## 📄 License
+
+MIT © Carl Lee

package/README.zh-TW.md

@@ -0,0 +1,170 @@
+# @gravito/monitor 🛰️
+
+輕量級的 Gravito 可觀測性模組 (Observability) - 包含健康檢查 (Health Checks)、指標監控 (Metrics) 與鏈路追蹤 (Tracing)。基於 **Galaxy Architecture** 設計，此 Orbit 為您的星球提供必備的監控基礎設施。
+
+## 🚀 核心特性
+
+- 🏥 **健康檢查 (Health Checks)** - 支援 Kubernetes 標準的 `/health`、`/ready`、`/live` 端點，並可自定義檢查項。
+- 📊 **指標監控 (Metrics)** - 相容 Prometheus 格式的 `/metrics` 端點，內建 Node.js 執行階段與 HTTP 監控。
+- 🔍 **鏈路追蹤 (Tracing)** - 支援 OpenTelemetry OTLP 標準，實現跨服務的分散式追蹤。
+- 🛡️ **雲原生整合** - 完美適配 Kubernetes Probe 設定與 Prometheus ServiceMonitor。
+
+## 📦 安裝
+
+```bash
+bun add @gravito/monitor
+```
+
+如需使用 OpenTelemetry 追蹤功能（選用）：
+
+```bash
+bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
+```
+
+## 🌌 快速上手
+
+只需將 `MonitorOrbit` 加入您的 `PlanetCore` 即可啟用。
+
+```typescript
+import { PlanetCore } from '@gravito/core'
+import { MonitorOrbit } from '@gravito/monitor'
+
+const core = new PlanetCore()
+
+core.orbit(new MonitorOrbit({
+  health: {
+    enabled: true,
+    path: '/health',
+  },
+  metrics: {
+    enabled: true,
+    prefix: 'myapp_',
+  },
+  tracing: {
+    enabled: process.env.NODE_ENV === 'production',
+    serviceName: 'order-service',
+  },
+}))
+
+await core.liftoff()
+```
+
+## 🏥 健康檢查 (Health Checks)
+
+健康檢查系統提供三個符合 Kubernetes 最佳實踐的端點：
+
+- **Liveness (`/live`)**: 指示程序是否正常運行。
+- **Readiness (`/ready`)**: 指示應用是否準備好接收流量（需通過所有註冊的檢查項）。
+- **Health (`/health`)**: 完整的健康報告，包含所有註冊的細節。
+
+### 註冊自定義檢查項
+
+您可以透過 `monitor` 服務註冊自定義檢查邏輯。
+
+```typescript
+const monitor = core.services.get('monitor')
+
+// 簡單檢查
+monitor.health.register('database', async () => {
+  const isOk = await db.ping()
+  return isOk ? { status: 'healthy' } : { status: 'unhealthy', message: '資料庫連線中斷' }
+})
+
+// 詳細報告
+monitor.health.register('disk_space', () => {
+  const usage = getDiskUsage()
+  return {
+    status: usage < 90 ? 'healthy' : 'degraded',
+    details: { usage: `${usage}%` }
+  }
+})
+```
+
+## 📊 指標監控 (Metrics)
+
+指標會以 Prometheus 文字格式暴露於 `/metrics` 端點。
+
+### 內建指標
+- **執行階段 (Runtime)**: 堆積記憶體 (Heap usage)、運行時間 (Uptime)、活躍控制代碼 (Active handles)。
+- **HTTP**: 請求總數 (`http_requests_total`)、請求耗時分佈 (`http_request_duration_seconds`)。
+
+### 自定義指標
+
+```typescript
+const monitor = core.services.get('monitor')
+
+// 1. Counter (單調遞增的計數器)
+const orders = monitor.metrics.counter({
+  name: 'orders_total',
+  help: '處理的訂單總數',
+  labels: ['status']
+})
+orders.inc({ status: 'completed' })
+
+// 2. Gauge (可增可減的量表)
+const activeUsers = monitor.metrics.gauge({
+  name: 'active_users',
+  help: '當前活躍使用者數'
+})
+activeUsers.set(42)
+
+// 3. Histogram (數值分佈統計)
+const processTime = monitor.metrics.histogram({
+  name: 'order_processing_seconds',
+  help: '訂單處理耗時',
+  buckets: [0.1, 0.5, 1, 2, 5]
+})
+const stop = processTime.startTimer()
+// ... 執行邏輯 ...
+stop()
+```
+
+## 🔍 鏈路追蹤 (Tracing)
+
+鏈路追蹤由 OpenTelemetry (OTLP) 驅動，會自動透過 W3C `traceparent` Header 傳遞追蹤上下文。
+
+### 配置範例
+```typescript
+tracing: {
+  enabled: true,
+  serviceName: 'gateway',
+  endpoint: 'http://otel-collector:4318/v1/traces',
+  sampleRate: 0.1, // 取樣 10% 的請求
+  resourceAttributes: {
+    env: 'production'
+  }
+}
+```
+
+### 手動建立 Span
+```typescript
+const tracer = core.services.get('tracing')
+
+const span = tracer.startSpan('compute_heavy_logic')
+try {
+  // ... 執行複雜運算 ...
+  tracer.setAttribute(span, 'items_count', 100)
+  tracer.endSpan(span, 'ok')
+} catch (e) {
+  tracer.endSpan(span, 'error')
+}
+```
+
+## ⚙️ 配置參數參考
+
+| 參數 | 類型 | 預設值 | 說明 |
+|--------|------|---------|-------------|
+| `health.enabled` | `boolean` | `true` | 是否啟用健康檢查端點 |
+| `health.path` | `string` | `/health` | 完整健康報告路徑 |
+| `health.timeout` | `number` | `5000` | 檢查項逾時時間 (ms) |
+| `health.cacheTtl` | `number` | `0` | 結果快取時間 (ms, 0 代表不快取) |
+| `metrics.enabled` | `boolean` | `true` | 是否啟用 Prometheus 指標端點 |
+| `metrics.prefix` | `string` | `gravito_` | 指標名稱前綴 |
+| `metrics.defaultMetrics` | `boolean` | `true` | 是否收集 Node.js 執行階段指標 |
+| `tracing.enabled` | `boolean` | `false` | 是否啟用 OpenTelemetry 追蹤 |
+| `tracing.endpoint` | `string` | `http://localhost:4318/v1/traces` | OTLP Collector 路徑 |
+| `tracing.sampleRate` | `number` | `1.0` | 取樣率 (0.0 - 1.0) |
+
+## 📄 授權協議
+
+MIT © Carl Lee

package/dist/index.cjs

@@ -65,8 +65,15 @@ var HealthController = class {
    */
   async health(c) {
     const report = await this.registry.check();
+    const cacheStats = this.registry.getCacheStats();
     const status = report.status === "healthy" ? 200 : report.status === "degraded" ? 200 : 503;
-    return c.json(report, status);
+    return c.json(
+      {
+        ...report,
+        cache: cacheStats
+      },
+      status
+    );
   }
   /**
    * GET /ready - Kubernetes readiness probe
@@ -101,6 +108,8 @@ var HealthRegistry = class {
   cacheExpiry = 0;
   timeout;
   cacheTtl;
+  cacheHits = 0;
+  cacheMisses = 0;
   constructor(config = {}) {
     this.timeout = config.timeout ?? DEFAULTS.timeout;
     this.cacheTtl = config.cacheTtl ?? DEFAULTS.cacheTtl;
@@ -158,8 +167,10 @@ var HealthRegistry = class {
    */
   async check() {
     if (this.cacheTtl > 0 && this.cachedReport && Date.now() < this.cacheExpiry) {
+      this.cacheHits++;
       return this.cachedReport;
     }
+    this.cacheMisses++;
     const results = await Promise.all(
       Array.from(this.checks.entries()).map(([name, check]) => this.executeCheck(name, check))
     );
@@ -209,6 +220,19 @@ var HealthRegistry = class {
     }
     return { status: "healthy" };
   }
+  /**
+   * Get cache statistics
+   *
+   * Useful for monitoring cache effectiveness and tuning cacheTtl
+   */
+  getCacheStats() {
+    const total = this.cacheHits + this.cacheMisses;
+    return {
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      hitRate: total > 0 ? this.cacheHits / total : 0
+    };
+  }
 };
 
 // src/health/index.ts
@@ -342,6 +366,7 @@ var MetricsController = class {
    * GET /metrics - Prometheus metrics endpoint
    */
   async metrics(_c) {
+    this.updateHealthCacheMetrics();
     const prometheusFormat = this.registry.toPrometheus();
     return new Response(prometheusFormat, {
       status: 200,
@@ -350,6 +375,19 @@ var MetricsController = class {
       }
     });
   }
+  /**
+   * 更新 health cache metrics
+   *
+   * 從 HealthRegistry 讀取最新的 cache 統計並更新 gauges
+   */
+  updateHealthCacheMetrics() {
+    const healthMetrics = this.registry._healthCacheMetrics;
+    if (!healthMetrics) return;
+    const stats = healthMetrics.registry.getCacheStats();
+    healthMetrics.hits.set(stats.hits);
+    healthMetrics.misses.set(stats.misses);
+    healthMetrics.hitRate.set(stats.hitRate);
+  }
 };
 
 // src/metrics/MetricsRegistry.ts
@@ -705,7 +743,7 @@ function createHttpMetricsMiddleware(registry) {
   });
   return async (c, next) => {
     const method = c.req.method;
-    const path = normalizePath(c.req.path);
+    const path = c.req.routePattern ?? normalizePath(c.req.path);
     const start = performance.now();
     await next();
     const duration = (performance.now() - start) / 1e3;
@@ -986,10 +1024,10 @@ var MonitorOrbit = class {
       metrics: this.metricsRegistry,
       tracing: this.tracingManager
     };
-    core.services.set("monitor", monitorService);
-    core.services.set("health", this.healthRegistry);
-    core.services.set("metrics", this.metricsRegistry);
-    core.services.set("tracing", this.tracingManager);
+    core.container.instance("monitor", monitorService);
+    core.container.instance("health", this.healthRegistry);
+    core.container.instance("metrics", this.metricsRegistry);
+    core.container.instance("tracing", this.tracingManager);
     const router = core.router;
     if (healthEnabled && this.healthRegistry) {
       const healthController = new HealthController(this.healthRegistry);
@@ -1002,9 +1040,37 @@ var MonitorOrbit = class {
       const metricsController = new MetricsController(this.metricsRegistry);
       router.get(metricsPath, (c) => metricsController.metrics(c));
       console.log(`[Monitor] Metrics endpoint: ${metricsPath}`);
+      if (healthEnabled && this.healthRegistry) {
+        this.registerHealthCacheMetrics(this.metricsRegistry, this.healthRegistry);
+      }
     }
     console.log("[Monitor] Observability services initialized");
   }
+  /**
+   * 註冊 health cache metrics
+   *
+   * 建立 metrics 來追蹤 health check cache 的效能
+   */
+  registerHealthCacheMetrics(metricsRegistry, healthRegistry) {
+    const cacheHitsGauge = metricsRegistry.gauge({
+      name: "health_cache_hits_total",
+      help: "Total number of health check cache hits"
+    });
+    const cacheMissesGauge = metricsRegistry.gauge({
+      name: "health_cache_misses_total",
+      help: "Total number of health check cache misses"
+    });
+    const cacheHitRateGauge = metricsRegistry.gauge({
+      name: "health_cache_hit_rate",
+      help: "Health check cache hit rate (0.0 to 1.0)"
+    });
+    metricsRegistry._healthCacheMetrics = {
+      hits: cacheHitsGauge,
+      misses: cacheMissesGauge,
+      hitRate: cacheHitRateGauge,
+      registry: healthRegistry
+    };
+  }
   /**
    * Shutdown hook
    */

package/dist/index.d.cts

@@ -101,6 +101,10 @@ declare function defineMonitorConfig(config: MonitorConfig): MonitorConfig;
  * Manages health check registrations and executions
  */
 
+/**
+ * Aggregated health check report.
+ * @public
+ */
 interface HealthReport {
     status: 'healthy' | 'unhealthy' | 'degraded';
     timestamp: string;
@@ -109,6 +113,14 @@ interface HealthReport {
         name: string;
     }>;
 }
+/**
+ * Cache statistics
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
 /**
  * HealthRegistry manages all health checks
  */
@@ -119,6 +131,8 @@ declare class HealthRegistry {
     private cacheExpiry;
     private timeout;
     private cacheTtl;
+    private cacheHits;
+    private cacheMisses;
     constructor(config?: HealthConfig);
     /**
      * Register a health check
@@ -154,6 +168,12 @@ declare class HealthRegistry {
         status: 'healthy' | 'unhealthy';
         reason?: string;
     }>;
+    /**
+     * Get cache statistics
+     *
+     * Useful for monitoring cache effectiveness and tuning cacheTtl
+     */
+    getCacheStats(): CacheStats;
 }
 
 /**
@@ -224,6 +244,10 @@ declare function createDiskCheck(options?: {
  * Manages metric collection and Prometheus exposition
  */
 
+/**
+ * Represents a single metric data point with labels.
+ * @public
+ */
 interface MetricValue {
     value: number;
     labels: Record<string, string>;
@@ -365,6 +389,12 @@ declare class MetricsController {
      * GET /metrics - Prometheus metrics endpoint
      */
     metrics(_c: GravitoContext): Promise<Response>;
+    /**
+     * 更新 health cache metrics
+     *
+     * 從 HealthRegistry 讀取最新的 cache 統計並更新 gauges
+     */
+    private updateHealthCacheMetrics;
 }
 
 /**
@@ -396,6 +426,10 @@ interface Span {
     status: 'ok' | 'error' | 'unset';
     events: SpanEvent[];
 }
+/**
+ * Event recorded within a span.
+ * @public
+ */
 interface SpanEvent {
     name: string;
     timestamp: number;
@@ -507,6 +541,12 @@ declare class MonitorOrbit implements GravitoOrbit {
      * Install the orbit (required by GravitoOrbit interface)
      */
     install(core: PlanetCore): Promise<void>;
+    /**
+     * 註冊 health cache metrics
+     *
+     * 建立 metrics 來追蹤 health check cache 的效能
+     */
+    private registerHealthCacheMetrics;
     /**
      * Shutdown hook
      */

package/dist/index.d.ts

@@ -101,6 +101,10 @@ declare function defineMonitorConfig(config: MonitorConfig): MonitorConfig;
  * Manages health check registrations and executions
  */
 
+/**
+ * Aggregated health check report.
+ * @public
+ */
 interface HealthReport {
     status: 'healthy' | 'unhealthy' | 'degraded';
     timestamp: string;
@@ -109,6 +113,14 @@ interface HealthReport {
         name: string;
     }>;
 }
+/**
+ * Cache statistics
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
 /**
  * HealthRegistry manages all health checks
  */
@@ -119,6 +131,8 @@ declare class HealthRegistry {
     private cacheExpiry;
     private timeout;
     private cacheTtl;
+    private cacheHits;
+    private cacheMisses;
     constructor(config?: HealthConfig);
     /**
      * Register a health check
@@ -154,6 +168,12 @@ declare class HealthRegistry {
         status: 'healthy' | 'unhealthy';
         reason?: string;
     }>;
+    /**
+     * Get cache statistics
+     *
+     * Useful for monitoring cache effectiveness and tuning cacheTtl
+     */
+    getCacheStats(): CacheStats;
 }
 
 /**
@@ -224,6 +244,10 @@ declare function createDiskCheck(options?: {
  * Manages metric collection and Prometheus exposition
  */
 
+/**
+ * Represents a single metric data point with labels.
+ * @public
+ */
 interface MetricValue {
     value: number;
     labels: Record<string, string>;
@@ -365,6 +389,12 @@ declare class MetricsController {
      * GET /metrics - Prometheus metrics endpoint
      */
     metrics(_c: GravitoContext): Promise<Response>;
+    /**
+     * 更新 health cache metrics
+     *
+     * 從 HealthRegistry 讀取最新的 cache 統計並更新 gauges
+     */
+    private updateHealthCacheMetrics;
 }
 
 /**
@@ -396,6 +426,10 @@ interface Span {
     status: 'ok' | 'error' | 'unset';
     events: SpanEvent[];
 }
+/**
+ * Event recorded within a span.
+ * @public
+ */
 interface SpanEvent {
     name: string;
     timestamp: number;
@@ -507,6 +541,12 @@ declare class MonitorOrbit implements GravitoOrbit {
      * Install the orbit (required by GravitoOrbit interface)
      */
     install(core: PlanetCore): Promise<void>;
+    /**
+     * 註冊 health cache metrics
+     *
+     * 建立 metrics 來追蹤 health check cache 的效能
+     */
+    private registerHealthCacheMetrics;
     /**
      * Shutdown hook
      */

package/dist/index.js

@@ -13,8 +13,15 @@ var HealthController = class {
    */
   async health(c) {
     const report = await this.registry.check();
+    const cacheStats = this.registry.getCacheStats();
     const status = report.status === "healthy" ? 200 : report.status === "degraded" ? 200 : 503;
-    return c.json(report, status);
+    return c.json(
+      {
+        ...report,
+        cache: cacheStats
+      },
+      status
+    );
   }
   /**
    * GET /ready - Kubernetes readiness probe
@@ -49,6 +56,8 @@ var HealthRegistry = class {
   cacheExpiry = 0;
   timeout;
   cacheTtl;
+  cacheHits = 0;
+  cacheMisses = 0;
   constructor(config = {}) {
     this.timeout = config.timeout ?? DEFAULTS.timeout;
     this.cacheTtl = config.cacheTtl ?? DEFAULTS.cacheTtl;
@@ -106,8 +115,10 @@ var HealthRegistry = class {
    */
   async check() {
     if (this.cacheTtl > 0 && this.cachedReport && Date.now() < this.cacheExpiry) {
+      this.cacheHits++;
       return this.cachedReport;
     }
+    this.cacheMisses++;
     const results = await Promise.all(
       Array.from(this.checks.entries()).map(([name, check]) => this.executeCheck(name, check))
     );
@@ -157,6 +168,19 @@ var HealthRegistry = class {
     }
     return { status: "healthy" };
   }
+  /**
+   * Get cache statistics
+   *
+   * Useful for monitoring cache effectiveness and tuning cacheTtl
+   */
+  getCacheStats() {
+    const total = this.cacheHits + this.cacheMisses;
+    return {
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      hitRate: total > 0 ? this.cacheHits / total : 0
+    };
+  }
 };
 
 // src/health/index.ts
@@ -290,6 +314,7 @@ var MetricsController = class {
    * GET /metrics - Prometheus metrics endpoint
    */
   async metrics(_c) {
+    this.updateHealthCacheMetrics();
     const prometheusFormat = this.registry.toPrometheus();
     return new Response(prometheusFormat, {
       status: 200,
@@ -298,6 +323,19 @@ var MetricsController = class {
       }
     });
   }
+  /**
+   * 更新 health cache metrics
+   *
+   * 從 HealthRegistry 讀取最新的 cache 統計並更新 gauges
+   */
+  updateHealthCacheMetrics() {
+    const healthMetrics = this.registry._healthCacheMetrics;
+    if (!healthMetrics) return;
+    const stats = healthMetrics.registry.getCacheStats();
+    healthMetrics.hits.set(stats.hits);
+    healthMetrics.misses.set(stats.misses);
+    healthMetrics.hitRate.set(stats.hitRate);
+  }
 };
 
 // src/metrics/MetricsRegistry.ts
@@ -653,7 +691,7 @@ function createHttpMetricsMiddleware(registry) {
   });
   return async (c, next) => {
     const method = c.req.method;
-    const path = normalizePath(c.req.path);
+    const path = c.req.routePattern ?? normalizePath(c.req.path);
     const start = performance.now();
     await next();
     const duration = (performance.now() - start) / 1e3;
@@ -934,10 +972,10 @@ var MonitorOrbit = class {
       metrics: this.metricsRegistry,
       tracing: this.tracingManager
     };
-    core.services.set("monitor", monitorService);
-    core.services.set("health", this.healthRegistry);
-    core.services.set("metrics", this.metricsRegistry);
-    core.services.set("tracing", this.tracingManager);
+    core.container.instance("monitor", monitorService);
+    core.container.instance("health", this.healthRegistry);
+    core.container.instance("metrics", this.metricsRegistry);
+    core.container.instance("tracing", this.tracingManager);
     const router = core.router;
     if (healthEnabled && this.healthRegistry) {
       const healthController = new HealthController(this.healthRegistry);
@@ -950,9 +988,37 @@ var MonitorOrbit = class {
       const metricsController = new MetricsController(this.metricsRegistry);
       router.get(metricsPath, (c) => metricsController.metrics(c));
       console.log(`[Monitor] Metrics endpoint: ${metricsPath}`);
+      if (healthEnabled && this.healthRegistry) {
+        this.registerHealthCacheMetrics(this.metricsRegistry, this.healthRegistry);
+      }
     }
     console.log("[Monitor] Observability services initialized");
   }
+  /**
+   * 註冊 health cache metrics
+   *
+   * 建立 metrics 來追蹤 health check cache 的效能
+   */
+  registerHealthCacheMetrics(metricsRegistry, healthRegistry) {
+    const cacheHitsGauge = metricsRegistry.gauge({
+      name: "health_cache_hits_total",
+      help: "Total number of health check cache hits"
+    });
+    const cacheMissesGauge = metricsRegistry.gauge({
+      name: "health_cache_misses_total",
+      help: "Total number of health check cache misses"
+    });
+    const cacheHitRateGauge = metricsRegistry.gauge({
+      name: "health_cache_hit_rate",
+      help: "Health check cache hit rate (0.0 to 1.0)"
+    });
+    metricsRegistry._healthCacheMetrics = {
+      hits: cacheHitsGauge,
+      misses: cacheMissesGauge,
+      hitRate: cacheHitRateGauge,
+      registry: healthRegistry
+    };
+  }
   /**
    * Shutdown hook
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/monitor",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Observability module for Gravito - Health checks, Metrics, and Tracing",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,9 +25,11 @@
   "scripts": {
     "build": "bun run build.ts",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "test:ci": "bun test --coverage --coverage-threshold=80"
+    "test": "bun test --timeout=10000",
+    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:unit": "bun test tests/ --timeout=10000",
+    "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "peerDependencies": {
     "@gravito/core": "workspace:*",