fix(readme): update documentation with detailed usage instructions, API references and integration examples

changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2025-06-09 - 2.0.9 - fix(readme)
+Update documentation with detailed usage instructions, API references and integration examples.
+
+- Overhauled README to provide a clearer explanation of SmartMetrics features and API.
+- Added a quick start guide, detailed examples, and code snippets for various integrations (Express, PM2, custom dashboards).
+- Reorganized documentation sections to better highlight core concepts including process aggregation and memory limit detection.
+- Updated installation instructions and usage examples to reflect the latest functionality.
+
 ## 2025-06-09 - 2.0.8 - fix(smartmetrics)
 Refactor metrics calculation and update Prometheus integration documentation
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartmetrics",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "private": false,
   "description": "A package for easy collection and reporting of system and process metrics.",
   "main": "dist_ts/index.js",

readme.md

@@ -1,131 +1,255 @@
 # @push.rocks/smartmetrics
 
-easy system metrics
-  
-## Install
+**Powerful system metrics collection for Node.js applications with Prometheus integration**
 
-To include `@push.rocks/smartmetrics` in your project, you need a Node.js environment with support for ES Modules. Make sure that your `package.json` contains `"type": "module"`. You can install `@push.rocks/smartmetrics` using npm:
+## What is SmartMetrics?
+
+SmartMetrics is a comprehensive metrics collection library that monitors your Node.js application's resource usage in real-time. It tracks CPU usage, memory consumption, and system metrics across your main process and all child processes, providing insights through both JSON and Prometheus formats.
+
+## Key Features
+
+- 📊 **Real-time Metrics Collection** - Monitor CPU and memory usage across all processes
+- 🔄 **Automatic Child Process Tracking** - Aggregates metrics from main and child processes
+- 🐳 **Docker-Aware** - Detects container memory limits automatically
+- 📈 **Prometheus Integration** - Built-in HTTP endpoint for Prometheus scraping
+- 🔧 **Flexible Output Formats** - Get metrics as JSON objects or Prometheus text
+- 📝 **Automatic Heartbeat Logging** - Optional periodic metrics logging
+- 🚀 **Zero Configuration** - Works out of the box with sensible defaults
+
+## Installation
 
 ```bash
-npm install @push.rocks/smartmetrics --save
+npm install @push.rocks/smartmetrics
 ```
 
-Or using yarn:
-
-```bash
-yarn add @push.rocks/smartmetrics
-```
-
-## Usage
-
-The `@push.rocks/smartmetrics` package provides an easy way to collect and monitor system metrics such as CPU and memory usage within your Node.js applications. It's built with TypeScript, offering type safety and IntelliSense in editors that support it.
-
-### Getting Started
-
-Before diving into the code, ensure you have `@push.rocks/smartmetrics` installed in your project and your environment is configured to use ES Modules (ESM) and TypeScript.
-
-#### Initialization
-
-To begin using `smartmetrics`, you need to import the module and initialize it:
+## Quick Start
 
 ```typescript
-// Import dependencies
 import { SmartMetrics } from '@push.rocks/smartmetrics';
 import { Smartlog } from '@push.rocks/smartlog';
 
-// Setup a logger (or use your existing logger if applicable)
+// Create a logger instance
 const logger = new Smartlog({
-  logContext: 'applicationName',
-  minimumLogLevel: 'info',
+  logContext: 'my-app',
+  minimumLogLevel: 'info'
 });
 
-// Initialize smartmetrics with the prepared logger
-const smartMetrics = new SmartMetrics(logger, 'sourceName');
+// Initialize SmartMetrics
+const metrics = new SmartMetrics(logger, 'my-service');
+
+// Get metrics on-demand
+const currentMetrics = await metrics.getMetrics();
+console.log(`CPU Usage: ${currentMetrics.cpuUsageText}`);
+console.log(`Memory: ${currentMetrics.memoryUsageText}`);
+
+// Enable automatic heartbeat logging (every 20 seconds)
+metrics.start();
+
+// Enable Prometheus endpoint
+metrics.enablePrometheusEndpoint(9090); // Metrics available at http://localhost:9090/metrics
+
+// Clean shutdown
+metrics.stop();
 ```
 
-In this snippet, `Smartlog` is used for logging purposes. Replace `'applicationName'` and `'sourceName'` with appropriate values for your application.
+## Core Concepts
 
-#### Starting Metrics Monitoring
+### Process Aggregation
+SmartMetrics doesn't just monitor your main process - it automatically discovers and aggregates metrics from all child processes spawned by your application. This gives you a complete picture of your application's resource footprint.
 
-With `smartMetrics` initialized, you can start the metrics monitoring process:
+### Memory Limit Detection
+The library automatically detects available memory whether running on bare metal, in Docker containers, or with Node.js heap restrictions. It uses the most restrictive limit to ensure accurate percentage calculations.
 
+### Dual Output Formats
+- **JSON Format**: Ideal for application monitoring, custom dashboards, and programmatic access
+- **Prometheus Format**: Perfect for integration with Prometheus/Grafana monitoring stacks
+
+## API Reference
+
+### Constructor
+
+```typescript
+new SmartMetrics(logger: Smartlog, sourceName: string)
+```
+- `logger`: Smartlog instance for output
+- `sourceName`: Identifier for your service/application
+
+### Methods
+
+#### `async getMetrics(): Promise<IMetricsSnapshot>`
+Retrieves current system metrics as a JSON object.
+
+**Returns:**
+```typescript
+{
+  process_cpu_seconds_total: number;    // Total CPU time in seconds
+  nodejs_active_handles_total: number;   // Active handles count
+  nodejs_active_requests_total: number;  // Active requests count
+  nodejs_heap_size_total_bytes: number;  // Heap size in bytes
+  cpuPercentage: number;                 // Current CPU usage (0-100)
+  cpuUsageText: string;                  // Human-readable CPU usage
+  memoryPercentage: number;              // Memory usage percentage
+  memoryUsageBytes: number;              // Memory usage in bytes
+  memoryUsageText: string;               // Human-readable memory usage
+}
+```
+
+**Example:**
+```typescript
+const metrics = await smartMetrics.getMetrics();
+if (metrics.cpuPercentage > 80) {
+  console.warn('High CPU usage detected!');
+}
+```
+
+#### `start(): void`
+Starts automatic metrics collection and heartbeat logging. Logs metrics every 20 seconds.
+
+**Example:**
 ```typescript
 smartMetrics.start();
+// Logs: "sending heartbeat for my-service with metrics" every 20 seconds
 ```
 
-This starts the collection and monitoring of various system metrics. By default, `smartMetrics` sends heartbeat messages including these metrics at a regular interval.
+#### `stop(): void`
+Stops automatic metrics collection and closes any open endpoints.
 
-#### Metrics Collection
-
-To manually collect metrics at any point, you can call the `getMetrics` method. This could be useful for logging or sending metrics to a monitoring tool:
+#### `async getPrometheusFormattedMetrics(): Promise<string>`
+Returns metrics in Prometheus text exposition format.
 
+**Example:**
 ```typescript
-async function logMetrics() {
+const promMetrics = await smartMetrics.getPrometheusFormattedMetrics();
+// Returns:
+// # HELP smartmetrics_cpu_percentage Current CPU usage percentage
+// # TYPE smartmetrics_cpu_percentage gauge
+// smartmetrics_cpu_percentage 15.2
+// ...
+```
+
+#### `enablePrometheusEndpoint(port?: number): void`
+Starts an HTTP server that exposes metrics for Prometheus scraping.
+
+**Parameters:**
+- `port`: Port number (default: 9090)
+
+**Example:**
+```typescript
+smartMetrics.enablePrometheusEndpoint(3000);
+// Metrics now available at http://localhost:3000/metrics
+```
+
+#### `disablePrometheusEndpoint(): void`
+Stops the Prometheus HTTP endpoint.
+
+## Use Cases
+
+### 1. Application Performance Monitoring
+```typescript
+// Monitor performance during critical operations
+const metricsBefore = await smartMetrics.getMetrics();
+await performHeavyOperation();
+const metricsAfter = await smartMetrics.getMetrics();
+
+console.log(`Operation consumed ${
+  metricsAfter.process_cpu_seconds_total - metricsBefore.process_cpu_seconds_total
+} CPU seconds`);
+```
+
+### 2. Resource Limit Enforcement
+```typescript
+// Prevent operations when resources are constrained
+async function checkResources() {
   const metrics = await smartMetrics.getMetrics();
-  console.log(metrics);
+  
+  if (metrics.memoryPercentage > 90) {
+    throw new Error('Memory usage too high, refusing new operations');
+  }
+  
+  if (metrics.cpuPercentage > 95) {
+    await delay(1000); // Back off when CPU is stressed
+  }
 }
-
-logMetrics();
 ```
 
-#### Customizing Monitoring
-
-The `start` method begins an unattended process of collecting and logging metrics. If you require more control over how and when metrics are collected or reported, you can use the `getMetrics` method in combination with your logic.
-
-#### Stopping Metrics Monitoring
-
-To stop the automatic metrics monitoring, simply call:
-
+### 3. Prometheus + Grafana Monitoring
 ```typescript
-smartMetrics.stop();
-```
-
-This stops the internal loop that periodically collects and logs metrics. It's useful for clean shutdowns of your application or when metrics monitoring is only needed during specific intervals.
-
-### Understanding the Metrics
-
-The `getMetrics` method returns a snapshot of various system metrics, including CPU and memory usage. Here's a brief overview of the information provided:
-
-- `process_cpu_seconds_total`: Total CPU time spent by the process.
-- `nodejs_active_handles_total`: Number of active handles.
-- `nodejs_active_requests_total`: Number of active requests.
-- `nodejs_heap_size_total_bytes`: Total size of the heap.
-- `cpuPercentage`: Overall CPU usage percentage.
-- `cpuUsageText`: Readable string representation of CPU usage.
-- `memoryPercentage`: Percentage of memory used.
-- `memoryUsageBytes`: Total memory used in bytes.
-- `memoryUsageText`: Readable string representation of memory usage.
-
-### Prometheus Integration
-
-`smartmetrics` can expose metrics in Prometheus format for scraping:
-
-```typescript
-// Enable Prometheus endpoint on port 9090 (default)
+// Expose metrics for Prometheus
 smartMetrics.enablePrometheusEndpoint();
 
-// Or specify a custom port
-smartMetrics.enablePrometheusEndpoint(3000);
-
-// The metrics will be available at http://localhost:9090/metrics
-
-// To get Prometheus-formatted metrics programmatically
-const prometheusMetrics = await smartMetrics.getPrometheusFormattedMetrics();
-console.log(prometheusMetrics);
-
-// Disable the endpoint when done
-smartMetrics.disablePrometheusEndpoint();
+// In your Prometheus config:
+// scrape_configs:
+//   - job_name: 'my-app'
+//     static_configs:
+//       - targets: ['localhost:9090']
 ```
 
-The Prometheus endpoint exposes both default Node.js metrics (via prom-client) and custom calculated metrics:
-- `smartmetrics_cpu_percentage` - Current CPU usage percentage
-- `smartmetrics_memory_percentage` - Current memory usage percentage  
-- `smartmetrics_memory_usage_bytes` - Current memory usage in bytes
-- Plus all default Node.js metrics collected by prom-client
+### 4. Development and Debugging
+```typescript
+// Track memory leaks during development
+setInterval(async () => {
+  const metrics = await smartMetrics.getMetrics();
+  console.log(`Heap: ${metrics.nodejs_heap_size_total_bytes / 1024 / 1024}MB`);
+}, 5000);
+```
 
-### Conclusion
+### 5. Container Resource Monitoring
+```typescript
+// Automatically detects container limits
+const metrics = await smartMetrics.getMetrics();
+console.log(metrics.memoryUsageText);
+// Output: "45% | 920 MB / 2 GB" (detects container limit)
+```
 
-`@push.rocks/smartmetrics` offers a straightforward and efficient way to monitor essential system metrics of your Node.js application. By integrating it, you gain valuable insights into the performance and health of your system, aiding in diagnosis and optimization efforts.
+## Integration Examples
+
+### With Express
+```typescript
+import express from 'express';
+
+const app = express();
+
+app.get('/health', async (req, res) => {
+  const metrics = await smartMetrics.getMetrics();
+  
+  res.json({
+    status: metrics.memoryPercentage < 90 ? 'healthy' : 'degraded',
+    metrics: {
+      cpu: metrics.cpuUsageText,
+      memory: metrics.memoryUsageText
+    }
+  });
+});
+```
+
+### With PM2
+```typescript
+// Graceful shutdown on high memory
+setInterval(async () => {
+  const metrics = await smartMetrics.getMetrics();
+  
+  if (metrics.memoryPercentage > 95) {
+    console.error('Memory limit reached, requesting restart');
+    process.exit(0); // PM2 will restart the process
+  }
+}, 10000);
+```
+
+### With Custom Dashboards
+```typescript
+// Stream metrics to your monitoring service
+setInterval(async () => {
+  const metrics = await smartMetrics.getMetrics();
+  
+  await sendToMonitoringService({
+    timestamp: Date.now(),
+    service: 'my-service',
+    cpu: metrics.cpuPercentage,
+    memory: metrics.memoryUsageBytes,
+    memoryLimit: metrics.memoryUsageBytes / (metrics.memoryPercentage / 100)
+  });
+}, 60000);
+```
 
 ## License and Legal Information
 
@@ -144,4 +268,4 @@ Registered at District court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartmetrics',
-  version: '2.0.8',
+  version: '2.0.9',
   description: 'A package for easy collection and reporting of system and process metrics.'
 }