Add Prometheus metrics export endpoint for monitoring integration (#80)

Author: bomanaps

apps/mcp-server/README.md

@@ -167,6 +167,139 @@ The server meets the following performance requirements:
 - **Mock Operations**: < 500ms per operation
 - **Memory Usage**: < 50MB
 
+## 📈 Prometheus Metrics Endpoint
+
+The server exposes a `/metrics` endpoint in Prometheus text format for integration with monitoring stacks like Prometheus, Grafana, and Datadog.
+
+### Enabling Metrics
+
+The metrics endpoint is enabled by default when the health check server is running. To configure:
+
+```bash
+# Enable health check server (required for /metrics)
+HEALTH_CHECK_ENABLED=true
+
+# Optionally set a custom port (default: 8080)
+HEALTH_CHECK_PORT=8080
+
+# Disable Prometheus metrics (metrics enabled by default)
+PROMETHEUS_METRICS_ENABLED=false
+```
+
+### Available Metrics
+
+#### Authentication Metrics
+
+| Metric                             | Type      | Description                                                          |
+| ---------------------------------- | --------- | -------------------------------------------------------------------- |
+| `lighthouse_auth_total{status}`    | Counter   | Total authentication attempts by status (success, failure, fallback) |
+| `lighthouse_auth_duration_seconds` | Histogram | Authentication duration distribution                                 |
+| `lighthouse_unique_api_keys`       | Gauge     | Number of unique API keys seen                                       |
+
+#### Cache Metrics
+
+| Metric                          | Type    | Description                  |
+| ------------------------------- | ------- | ---------------------------- |
+| `lighthouse_cache_hits_total`   | Counter | Total cache hits             |
+| `lighthouse_cache_misses_total` | Counter | Total cache misses           |
+| `lighthouse_cache_size`         | Gauge   | Current cache size (entries) |
+| `lighthouse_cache_max_size`     | Gauge   | Maximum cache capacity       |
+
+#### Tool Metrics
+
+| Metric                                           | Type      | Description                         |
+| ------------------------------------------------ | --------- | ----------------------------------- |
+| `lighthouse_tool_calls_total{tool}`              | Counter   | Total tool invocations by tool name |
+| `lighthouse_tools_registered`                    | Gauge     | Number of registered tools          |
+| `lighthouse_request_duration_seconds{operation}` | Histogram | Request duration by operation       |
+
+#### Security Metrics
+
+| Metric                                   | Type    | Description                                                                 |
+| ---------------------------------------- | ------- | --------------------------------------------------------------------------- |
+| `lighthouse_security_events_total{type}` | Counter | Security events by type (AUTHENTICATION_FAILURE, RATE_LIMIT_EXCEEDED, etc.) |
+
+#### Storage Metrics
+
+| Metric                           | Type  | Description                     |
+| -------------------------------- | ----- | ------------------------------- |
+| `lighthouse_storage_files`       | Gauge | Number of files in storage      |
+| `lighthouse_storage_bytes`       | Gauge | Total storage usage in bytes    |
+| `lighthouse_storage_max_bytes`   | Gauge | Maximum storage capacity        |
+| `lighthouse_storage_utilization` | Gauge | Storage utilization ratio (0-1) |
+
+#### Service Pool Metrics
+
+| Metric                             | Type  | Description                   |
+| ---------------------------------- | ----- | ----------------------------- |
+| `lighthouse_service_pool_size`     | Gauge | Current service pool size     |
+| `lighthouse_service_pool_max_size` | Gauge | Maximum service pool capacity |
+
+#### Process Metrics (Auto-collected)
+
+| Metric                                     | Type    | Description             |
+| ------------------------------------------ | ------- | ----------------------- |
+| `lighthouse_process_cpu_seconds_total`     | Counter | Total CPU time consumed |
+| `lighthouse_process_resident_memory_bytes` | Gauge   | Resident memory size    |
+| `lighthouse_nodejs_eventloop_lag_seconds`  | Gauge   | Node.js event loop lag  |
+| `lighthouse_nodejs_heap_size_total_bytes`  | Gauge   | Total heap size         |
+| `lighthouse_nodejs_heap_size_used_bytes`   | Gauge   | Used heap size          |
+
+### Example Output
+
+```prometheus
+# HELP lighthouse_auth_total Total authentication attempts
+# TYPE lighthouse_auth_total counter
+lighthouse_auth_total{status="success"} 1542
+lighthouse_auth_total{status="failure"} 23
+lighthouse_auth_total{status="fallback"} 156
+
+# HELP lighthouse_cache_hits_total Total cache hits
+# TYPE lighthouse_cache_hits_total counter
+lighthouse_cache_hits_total 12453
+
+# HELP lighthouse_cache_misses_total Total cache misses
+# TYPE lighthouse_cache_misses_total counter
+lighthouse_cache_misses_total 1847
+
+# HELP lighthouse_request_duration_seconds Request duration in seconds
+# TYPE lighthouse_request_duration_seconds histogram
+lighthouse_request_duration_seconds_bucket{operation="lighthouse_upload_file",le="0.1"} 234
+lighthouse_request_duration_seconds_bucket{operation="lighthouse_upload_file",le="0.5"} 892
+lighthouse_request_duration_seconds_bucket{operation="lighthouse_upload_file",le="1"} 1023
+lighthouse_request_duration_seconds_bucket{operation="lighthouse_upload_file",le="+Inf"} 1024
+lighthouse_request_duration_seconds_sum{operation="lighthouse_upload_file"} 342.87
+lighthouse_request_duration_seconds_count{operation="lighthouse_upload_file"} 1024
+
+# HELP lighthouse_security_events_total Total security events by type
+# TYPE lighthouse_security_events_total counter
+lighthouse_security_events_total{type="AUTHENTICATION_FAILURE"} 23
+lighthouse_security_events_total{type="RATE_LIMIT_EXCEEDED"} 5
+```
+
+### Prometheus Configuration
+
+Add this scrape configuration to your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+  - job_name: "lighthouse-mcp-server"
+    static_configs:
+      - targets: ["localhost:8080"]
+    metrics_path: /metrics
+    scrape_interval: 15s
+```
+
+### Grafana Dashboard
+
+Import the metrics into Grafana and create dashboards to visualize:
+
+- Authentication success/failure rates
+- Cache hit rate over time
+- Tool usage patterns
+- Storage utilization trends
+- Security event alerts
+
 ## 🧪 Testing
 
 ```bash

apps/mcp-server/package.json

@@ -21,7 +21,8 @@
     "@lighthouse-tooling/shared": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "better-sqlite3": "^11.7.0",
-    "dotenv": "^16.4.5"
+    "dotenv": "^16.4.5",
+    "prom-client": "^15.1.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",

apps/mcp-server/src/auth/AuthManager.ts

@@ -6,16 +6,19 @@ import { AuthConfig, ValidationResult, AuthenticationResult } from "./types.js";
 import { KeyValidationCache } from "./KeyValidationCache.js";
 import { RateLimiter } from "./RateLimiter.js";
 import { SecureKeyHandler } from "./SecureKeyHandler.js";
+import { MetricsCollector } from "./MetricsCollector.js";
 
 export class AuthManager {
   private config: AuthConfig;
   private cache: KeyValidationCache;
   private rateLimiter: RateLimiter;
+  private metricsCollector: MetricsCollector;
 
   constructor(config: AuthConfig) {
     this.config = config;
     this.cache = new KeyValidationCache(config.keyValidationCache);
     this.rateLimiter = new RateLimiter(config.rateLimiting);
+    this.metricsCollector = new MetricsCollector();
   }
 
   /**
@@ -38,8 +41,10 @@ export class AuthManager {
     // Check cache first
     const cached = this.cache.get(keyHash);
     if (cached) {
+      this.metricsCollector.recordCacheAccess(true);
       return cached;
     }
+    this.metricsCollector.recordCacheAccess(false);
 
     // Check rate limiting
     const rateLimitResult = this.rateLimiter.isAllowed(keyHash);
@@ -115,23 +120,33 @@ export class AuthManager {
 
       const validation = await this.validateApiKey(effectiveKey);
 
-      return {
+      const result: AuthenticationResult = {
         success: validation.isValid,
         keyHash: validation.keyHash,
         usedFallback,
         rateLimited: validation.rateLimitInfo?.remaining === 0 || false,
         authTime: Date.now() - startTime,
         errorMessage: validation.errorMessage,
       };
+
+      // Record metrics
+      this.metricsCollector.recordAuthentication(result);
+
+      return result;
     } catch (error) {
-      return {
+      const result: AuthenticationResult = {
         success: false,
         keyHash: "unknown",
         usedFallback: false,
         rateLimited: false,
         authTime: Date.now() - startTime,
         errorMessage: error instanceof Error ? error.message : "Authentication failed",
       };
+
+      // Record failed authentication
+      this.metricsCollector.recordAuthentication(result);
+
+      return result;
     }
   }
 
@@ -166,6 +181,13 @@ export class AuthManager {
     return this.cache.getStats();
   }
 
+  /**
+   * Get metrics collector for Prometheus export
+   */
+  getMetricsCollector(): MetricsCollector {
+    return this.metricsCollector;
+  }
+
   /**
    * Get rate limiter status for a key
    */
@@ -204,5 +226,6 @@ export class AuthManager {
   destroy(): void {
     this.cache.destroy();
     this.rateLimiter.destroy();
+    this.metricsCollector.destroy();
   }
 }

apps/mcp-server/src/auth/MetricsCollector.ts

@@ -215,6 +215,16 @@ export class MetricsCollector {
     };
   }
 
+  /**
+   * Get raw cache counters for Prometheus export
+   */
+  getCacheCounters(): { hits: number; misses: number } {
+    return {
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+    };
+  }
+
   /**
    * Get security events within time range
    */

apps/mcp-server/src/config/server-config.ts

@@ -96,6 +96,7 @@ export const DEFAULT_HEALTH_CHECK_CONFIG: HealthCheckConfig = {
   lighthouseApiUrl: process.env.LIGHTHOUSE_API_URL || "https://api.lighthouse.storage",
   connectivityCheckInterval: 30000,
   connectivityTimeout: 5000,
+  metricsEnabled: process.env.PROMETHEUS_METRICS_ENABLED !== "false", // Enabled by default
 };
 
 export const DEFAULT_ORGANIZATION_SETTINGS: OrganizationSettings = {

apps/mcp-server/src/health/HealthCheckServer.ts

@@ -1,7 +1,7 @@
 /**
  * Health Check HTTP Server
  *
- * Provides /health (liveness) and /ready (readiness) endpoints
+ * Provides /health (liveness), /ready (readiness), and /metrics (Prometheus) endpoints
  * on a configurable port, separate from the MCP stdio transport.
  */
 
@@ -14,6 +14,7 @@ import { ILighthouseService } from "../services/ILighthouseService.js";
 import { ToolRegistry } from "../registry/ToolRegistry.js";
 import { ServerConfig } from "../config/server-config.js";
 import { HealthCheckConfig, HealthStatus, ReadinessCheck, ReadinessStatus } from "./types.js";
+import { PrometheusExporter } from "./PrometheusExporter.js";
 
 export interface HealthCheckDependencies {
   authManager: AuthManager;
@@ -30,6 +31,7 @@ export class HealthCheckServer {
   private deps: HealthCheckDependencies;
   private healthConfig: HealthCheckConfig;
   private logger: Logger;
+  private prometheusExporter: PrometheusExporter | null = null;
 
   private lastConnectivityCheck: {
     up: boolean;
@@ -41,6 +43,16 @@ export class HealthCheckServer {
     this.deps = deps;
     this.healthConfig = healthConfig;
     this.logger = deps.logger;
+
+    // Initialize Prometheus exporter if metrics are enabled
+    if (healthConfig.metricsEnabled !== false) {
+      this.prometheusExporter = new PrometheusExporter({
+        metricsCollector: deps.authManager.getMetricsCollector(),
+        registry: deps.registry,
+        serviceFactory: deps.serviceFactory,
+        lighthouseService: deps.lighthouseService,
+      });
+    }
   }
 
   async start(): Promise<void> {
@@ -109,6 +121,12 @@ export class HealthCheckServer {
           this.sendJSON(res, 500, { error: "Internal server error" });
         });
         break;
+      case "/metrics":
+        this.handleMetrics(res).catch((err) => {
+          this.logger.error("Metrics export failed", err);
+          this.sendJSON(res, 500, { error: "Internal server error" });
+        });
+        break;
       default:
         this.sendJSON(res, 404, { error: "Not found" });
         break;
@@ -154,6 +172,27 @@ export class HealthCheckServer {
     this.sendJSON(res, allUp ? 200 : 503, status);
   }
 
+  private async handleMetrics(res: http.ServerResponse): Promise<void> {
+    if (!this.prometheusExporter) {
+      this.sendJSON(res, 404, { error: "Metrics endpoint not enabled" });
+      return;
+    }
+
+    try {
+      const metrics = await this.prometheusExporter.getMetrics();
+      const contentType = this.prometheusExporter.getContentType();
+
+      res.writeHead(200, {
+        "Content-Type": contentType,
+        "Cache-Control": "no-cache, no-store",
+      });
+      res.end(metrics);
+    } catch (err) {
+      this.logger.error("Failed to generate metrics", err as Error);
+      this.sendJSON(res, 500, { error: "Failed to generate metrics" });
+    }
+  }
+
   private checkSDK(): ReadinessCheck {
     try {
       const stats = this.deps.lighthouseService.getStorageStats();