smartmetrics/readme.hints.md

SmartMetrics Implementation Hints

Prometheus Integration

The package now supports exposing metrics in Prometheus format through two mechanisms:

1. Direct Export: getPrometheusFormattedMetrics() returns metrics in Prometheus text exposition format
2. HTTP Endpoint: enablePrometheusEndpoint(port) starts an HTTP server that exposes metrics on /metrics

Architecture Decisions

• We use the prom-client library's default collectors for standard Node.js metrics
• Custom gauges are created for our calculated metrics (CPU percentage, memory percentage, memory bytes)
• The getMetrics() method calculates values directly rather than parsing the Prometheus registry JSON
• For metrics like nodejs_active_handles_total and nodejs_active_requests_total, we return 0 in getMetrics() since these require deprecated Node.js APIs, but the Prometheus collectors still track the real values

Consolidation Approach

Initially, we were mixing two approaches:

1. Extracting values from the Prometheus registry JSON for default metrics
2. Creating custom gauges for calculated metrics

We consolidated by:

• Calculating all values directly in getMetrics() where possible
• Only using the Prometheus registry for the text exposition format
• This eliminates the dependency on parsing registry JSON and makes the code cleaner

Memory Calculation

The package tracks memory usage across the main process and all child processes using pidtree and pidusage. This provides a more comprehensive view than just the main process memory.