smartmetrics/readme.plan.md

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

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

2. Create Prometheus Gauges in SmartMetrics Class

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

3. Update getMetrics() Method

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

4. Add getPrometheusFormattedMetrics() Method

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

5. Add HTTP Server Properties

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

6. Implement enablePrometheusEndpoint() Method

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

7. Add disablePrometheusEndpoint() Method

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

8. Update stop() Method

• Call disablePrometheusEndpoint() to ensure clean shutdown

9. Add Tests

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

10. Update Documentation

• Add usage example in readme.md for Prometheus integration
• 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