81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# 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` |