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
- [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`