ModMon.Modules.HostMetrics 1.2.0

ModMon.HostMetrics

Comprehensive host system metrics monitoring module for the ModMon framework. Provides real-time collection and analysis of CPU, memory, disk, network, and process metrics with configurable alerts, health checks, and background processing.

Features

🖥️ Comprehensive Metrics Collection

• CPU Metrics: Usage percentage, load averages, processor count, process CPU time
• Memory Metrics: Physical memory usage, process working set, managed memory, virtual memory
• Disk Metrics: Space utilization, I/O operations, read/write rates for all drives
• Network Metrics: Bandwidth usage, active connections, interface statistics
• Process Metrics: Thread count, handle count, uptime, peak memory usage
• Garbage Collection: Collection counts, heap size, GC pressure analysis
• Thread Pool: Worker threads, completion port threads, queue statistics

📊 Rich API Endpoints

• /api/host-metrics/current - Get current system metrics
• /api/host-metrics/history - Historical metrics with time range filtering
• /api/host-metrics/system-info - Static system information
• /api/host-metrics/performance - Performance summary and health indicators
• /api/host-metrics/health - Module health status
• /api/host-metrics/config - Current configuration
• /api/host-metrics/collect - Manual metrics collection trigger

🔄 Background Processing

• Automatic Collection: Configurable interval-based metrics gathering
• Data Retention: Automatic cleanup of old metrics based on retention policies
• Manual Tasks: On-demand collection and cleanup operations
• Retry Logic: Robust error handling with configurable retry mechanisms

🏥 Health Monitoring

• Integrated Health Checks: ASP.NET Core health check integration
• Performance Alerts: Configurable thresholds for critical metrics
• Status Reporting: Detailed health status with diagnostic information
• Failure Tracking: Consecutive failure monitoring and alerting

⚙️ Flexible Configuration

• Granular Control: Enable/disable individual metric types
• Performance Tuning: Configurable collection intervals and timeouts
• Storage Options: In-memory caching with size limits and retention policies
• Alert Thresholds: Customizable warning and critical thresholds

Installation

dotnet add package ModMon.HostMetrics

Quick Start

1. Register the Module

using ModMon.Hosting;
using ModMon.HostMetrics;

var app = ModMonApplication.CreateBuilder(args)
    .AddModuleDefaults()
    .AddModule<HostMetricsModule>()
    .Build();

app.Run();

2. Configure Options (Optional)

Add to your appsettings.json:

{
  "Modules": {
    "HostMetrics": {
      "Collection": {
        "EnableCollection": true,
        "EnableBackgroundCollection": true,
        "CollectionInterval": "00:01:00"
      },
      "Storage": {
        "EnableInMemoryCache": true,
        "MaxCacheSize": 1440,
        "RetentionPeriod": "7.00:00:00"
      },
      "Alerts": {
        "CpuUsageThreshold": 80.0,
        "MemoryUsageThreshold": 85.0,
        "DiskUsageThreshold": 90.0
      }
    }
  }
}

3. Use the API

# Get current metrics
curl http://localhost:5000/api/host-metrics/current

# Get historical data
curl "http://localhost:5000/api/host-metrics/history?from=2025-01-01T00:00:00Z&to=2025-01-01T23:59:59Z&intervalMinutes=5"

# Check health
curl http://localhost:5000/api/host-metrics/health

Configuration Options

Collection Settings

{
  "Collection": {
    "EnableCollection": true,
    "EnableBackgroundCollection": true,
    "CollectionInterval": "00:01:00",
    "CollectionTimeout": "00:00:30",
    "EnableCpuMetrics": true,
    "EnableMemoryMetrics": true,
    "EnableDiskMetrics": true,
    "EnableNetworkMetrics": true,
    "EnableProcessMetrics": true,
    "EnableGcMetrics": true,
    "EnableThreadPoolMetrics": true,
    "MonitoredDrives": [],
    "MonitoredNetworkInterfaces": [],
    "MaxRetries": 3,
    "RetryDelay": "00:00:05"
  }
}

Storage Settings

{
  "Storage": {
    "EnableInMemoryCache": true,
    "MaxCacheSize": 1440,
    "RetentionPeriod": "7.00:00:00",
    "EnableAutoCleanup": true,
    "CleanupInterval": "1.00:00:00",
    "EnableCompression": false
  }
}

Alert Thresholds

{
  "Alerts": {
    "EnableAlerts": true,
    "CpuUsageThreshold": 80.0,
    "MemoryUsageThreshold": 85.0,
    "DiskUsageThreshold": 90.0,
    "NetworkUsageThreshold": 104857600,
    "GcPressureThreshold": 10.0,
    "ThreadCountThreshold": 200,
    "CustomThresholds": {},
    "AlertCooldown": "00:05:00"
  }
}

Performance Analysis

{
  "Performance": {
    "EnablePerformanceAnalysis": true,
    "AnalysisWindowSize": 60,
    "EnableRecommendations": true,
    "EnableTrendAnalysis": true,
    "MinTrendDataPoints": 10,
    "EnableAnomalyDetection": false,
    "AnomalyThreshold": 2.0
  }
}

API Examples

Get Current Metrics

Request:

GET /api/host-metrics/current

Response:

{
  "timestamp": "2025-08-22T16:30:00Z",
  "machineName": "web-server-01",
  "cpu": {
    "usagePercent": 45.2,
    "logicalProcessors": 8,
    "loadAverages": [1.2, 1.5, 1.8],
    "processCpuTime": "01:23:45",
    "systemUptime": "5.12:34:56"
  },
  "memory": {
    "totalBytes": 17179869184,
    "availableBytes": 8589934592,
    "usedBytes": 8589934592,
    "usagePercent": 50.0,
    "processWorkingSet": 134217728,
    "processPrivateMemory": 268435456,
    "managedMemory": 67108864,
    "virtualMemoryUsage": 536870912
  },
  "disks": [
    {
      "driveName": "C:",
      "fileSystem": "NTFS",
      "totalBytes": 1099511627776,
      "freeBytes": 549755813888,
      "usedBytes": 549755813888,
      "usagePercent": 50.0,
      "readOpsPerSecond": 15.2,
      "writeOpsPerSecond": 8.7,
      "readBytesPerSecond": 1048576,
      "writeBytesPerSecond": 524288
    }
  ],
  "network": {
    "bytesReceivedPerSecond": 1048576,
    "bytesSentPerSecond": 524288,
    "totalBytesReceived": 1099511627776,
    "totalBytesSent": 549755813888,
    "activeConnections": 42,
    "interfaces": [
      {
        "name": "Ethernet",
        "description": "Intel Ethernet Controller",
        "isUp": true,
        "bytesReceived": 1099511627776,
        "bytesSent": 549755813888,
        "speed": 1000000000
      }
    ]
  },
  "process": {
    "processId": 1234,
    "processName": "MyApp",
    "startTime": "2025-08-22T12:00:00Z",
    "uptime": "04:30:00",
    "threadCount": 15,
    "handleCount": 456,
    "peakWorkingSet": 268435456,
    "peakVirtualMemory": 1073741824
  },
  "garbageCollection": {
    "totalCollections": 1250,
    "collectionsByGeneration": [800, 350, 100],
    "totalAllocatedBytes": 5368709120,
    "heapSizeBytes": 134217728,
    "timeInGcPercent": 2.5,
    "largeObjectHeapSize": 16777216
  },
  "threadPool": {
    "workerThreads": 12,
    "completionPortThreads": 4,
    "maxWorkerThreads": 32,
    "maxCompletionPortThreads": 32,
    "queuedWorkItems": 3,
    "completedWorkItems": 98765
  },
  "customMetrics": {}
}

Get Performance Summary

Request:

GET /api/host-metrics/performance

Response:

{
  "generatedAt": "2025-08-22T16:30:00Z",
  "overallStatus": "Good",
  "indicators": [
    {
      "name": "CPU Usage",
      "value": 45.2,
      "unit": "%",
      "status": "Good",
      "description": "Current CPU utilization percentage",
      "threshold": 80.0
    },
    {
      "name": "Memory Usage",
      "value": 50.0,
      "unit": "%",
      "status": "Good",
      "description": "Current memory utilization percentage",
      "threshold": 85.0
    }
  ],
  "alerts": [],
  "keyMetrics": {
    "CpuUsage": 45.2,
    "MemoryUsage": 50.0,
    "ProcessWorkingSet": 128.0,
    "ThreadCount": 15,
    "HandleCount": 456,
    "GcCollections": 1250,
    "GcHeapSize": 128.0,
    "ActiveConnections": 42,
    "ProcessUptime": 4.5
  },
  "recommendations": []
}

Background Tasks

The module automatically registers background tasks:

• HostMetricsCollectionTask: Runs every minute (configurable) to collect metrics
• HostMetricsCleanupTask: Runs daily at 2 AM to clean up old data
• ManualHostMetricsCollectionTask: On-demand collection for testing
• ManualHostMetricsCleanupTask: On-demand cleanup

Monitor task execution through the ModMon background task system.

Health Checks

The module registers with ASP.NET Core health checks:

# Check overall application health (includes HostMetrics)
curl http://localhost:5000/health

# Check detailed health with HostMetrics info
curl http://localhost:5000/health/detailed

Health check validates:

• Metrics collector functionality
• Cache health and data freshness
• Service health and error rates
• Performance thresholds
• Configuration validity

Platform Support

• Windows: Full support with performance counters
• Linux: Core metrics with /proc filesystem integration
• macOS: Basic metrics support

Performance Considerations

Memory Usage

• Default cache size: 1440 metrics (24 hours at 1-minute intervals)
• Estimated memory: ~3MB for default cache size
• Configurable retention and cleanup

CPU Impact

• Collection overhead: <1% CPU on typical systems
• Configurable collection intervals (default: 1 minute)
• Async collection with timeouts

Disk I/O

• In-memory caching reduces I/O
• Optional compression for storage
• Configurable cleanup intervals

Troubleshooting

Common Issues

Metrics not collecting:

# Check module configuration
curl http://localhost:5000/api/host-metrics/config

# Check health status
curl http://localhost:5000/api/host-metrics/health

# Check logs for errors

High memory usage:

{
  "Storage": {
    "MaxCacheSize": 720,  // Reduce cache size
    "RetentionPeriod": "3.00:00:00"  // Reduce retention
  }
}

Performance impact:

{
  "Collection": {
    "CollectionInterval": "00:05:00",  // Collect less frequently
    "EnableNetworkMetrics": false,     // Disable expensive metrics
    "EnableDiskMetrics": false
  }
}

Logging

Enable detailed logging:

{
  "Logging": {
    "LogLevel": {
      "ModMon.HostMetrics": "Debug"
    }
  }
}

Contributing

This module follows ModMon framework patterns:

1. Interfaces: Define contracts in Contracts folder
2. Models: Data structures in Models folder
3. Implementation: Core logic in Implementation folder
4. Options: Configuration in Options folder
5. Tasks: Background tasks in Tasks folder

License

MIT License - see the LICENSE file for details.