Prometheus Metrics Implementation Plan

cat /home/philkunz/.claude/CLAUDE.md

Overview

Add Prometheus metrics exposure functionality to SmartMetrics while maintaining backward compatibility with existing getMetrics() method.

Implementation Tasks

1. Add HTTP Server Dependencies

• [x] Check if we need to add any HTTP server dependency to package.json
• [x] Import necessary modules in smartmetrics.plugins.ts

2. Create Prometheus Gauges in SmartMetrics Class

• [x] Add private properties for custom gauges:
  • [x] private cpuPercentageGauge: plugins.promClient.Gauge<string>
  • [x] private memoryPercentageGauge: plugins.promClient.Gauge<string>
  • [x] private memoryUsageBytesGauge: plugins.promClient.Gauge<string>
• [x] Initialize gauges in setup() method with appropriate names and help text:
  • [x] smartmetrics_cpu_percentage - "Current CPU usage percentage"
  • [x] smartmetrics_memory_percentage - "Current memory usage percentage"
  • [x] smartmetrics_memory_usage_bytes - "Current memory usage in bytes"

3. Update getMetrics() Method

• [x] After calculating metrics, update the Prometheus gauges:
  • [x] this.cpuPercentageGauge.set(cpuPercentage)
  • [x] this.memoryPercentageGauge.set(memoryPercentage)
  • [x] this.memoryUsageBytesGauge.set(memoryUsageBytes)
• [x] Ensure gauges are only updated if they exist (defensive programming)

4. Add getPrometheusFormattedMetrics() Method

• [x] Create new public async method getPrometheusFormattedMetrics(): Promise<string>
• [x] Call this.getMetrics() to ensure gauges are updated with latest values
• [x] Return await this.registry.metrics() to get Prometheus text format

5. Add HTTP Server Properties

• [x] Add private property for HTTP server: private prometheusServer?: any
• [x] Add private property for server port: private prometheusPort?: number

6. Implement enablePrometheusEndpoint() Method

• [x] Create new public method enablePrometheusEndpoint(port: number = 9090): void
• [x] Check if server is already running, if so, log warning and return
• [x] Create minimal HTTP server using Node.js built-in http module:
  • [x] Listen on specified port
  • [x] Handle GET requests to /metrics endpoint
  • [x] Return Prometheus-formatted metrics with correct Content-Type header
  • [x] Handle other routes with 404
• [x] Store server reference and port for later cleanup
• [x] Log info message about endpoint availability

7. Add disablePrometheusEndpoint() Method

• [x] Create new public method disablePrometheusEndpoint(): void
• [x] Check if server exists, if not, return
• [x] Close the HTTP server
• [x] Clear server reference and port
• [x] Log info message about endpoint shutdown

8. Update stop() Method

• [x] Call disablePrometheusEndpoint() to ensure clean shutdown

9. Add Tests

• [x] Add test for getPrometheusFormattedMetrics():
  • [x] Verify it returns a string
  • [x] Verify it contains expected metric names
  • [x] Verify format matches Prometheus text exposition format
• [x] Add test for enablePrometheusEndpoint():
  • [x] Start endpoint on test port (e.g., 19090)
  • [x] Make HTTP request to /metrics
  • [x] Verify response has correct Content-Type
  • [x] Verify response contains metrics
  • [x] Clean up by calling disablePrometheusEndpoint()

10. Update Documentation

• [x] Add usage example in readme.md for Prometheus integration
• [x] Document the new methods in code comments

Notes

• Using Node.js built-in http module to avoid adding unnecessary dependencies
• Default port 9090 is commonly used for metrics endpoints
• Maintaining backward compatibility - existing functionality unchanged
• Prometheus text format example: metric_name{label="value"} 123.45