Panel/RESOURCE_STATS_README.md

OGP Agent Resource Stats Collection

This document describes the integrated resource statistics collection system in the OGP agents that replaces the standalone Python collector.py script.

Overview

The OGP agents now include built-in resource monitoring that collects:

• Machine-wide statistics: CPU usage, memory, disk space, network activity, load averages
• Per-server process statistics: Memory usage, CPU usage, I/O statistics, listening ports, folder sizes

Data is automatically inserted into the same MySQL database tables used by the web panel for display.

Configuration

Database Configuration

Update the agent configuration files with your database connection details:

Linux Agent: _agent-linux/Cfg/Config.pm Windows Agent: _agent-windows/Cfg/Config.pm

# Resource stats database configuration
stats_db_host => '127.0.0.1',           # Database server hostname/IP
stats_db_user => 'panel_user',          # Database username
stats_db_pass => 'your_password_here',  # Database password
stats_db_name => 'panel_database',      # Database name (same as your web panel)
stats_table_prefix => 'gsp_',           # Table prefix (must match collector.py)
stats_frequency_minutes => '5',         # Collection frequency in minutes

Database Tables

The system uses the same database tables as the original collector.py:

-- Machine catalog
gsp_machines

-- Machine-wide samples (CPU, memory, disk, network)
gsp_machine_samples

-- Per-process/per-server samples
gsp_process_samples

Run the SQL schema from modules/resource_stats/mysql_query.sql to create these tables if they don't exist.

Required Perl Modules

The agents require these Perl modules for database connectivity:

# Ubuntu/Debian
sudo apt-get install libdbi-perl libdbd-mysql-perl

# CentOS/RHEL
sudo yum install perl-DBI perl-DBD-MySQL

# Or via CPAN
cpan DBI DBD::mysql

Features

Automatic Integration

• Runs automatically as part of the agent scheduler
• No separate cron jobs required
• Starts when the agent starts
• Stops when the agent stops

Platform Support

Linux Agent:

• Uses /proc filesystem for system stats
• Native command-line tools (df, netstat, etc.)
• Full CPU, memory, disk, and network monitoring
• Process association via working directory and command line analysis

Windows Agent:

• Uses wmic for system information
• Native Windows commands (dir, netstat)
• CPU, memory, disk monitoring (no load averages on Windows)
• Process association via executable path and command line analysis

Process Detection

The system automatically detects game server processes by:

1. Scanning for subdirectories in the agent directory
2. Finding processes whose working directory, executable path, or command line references these directories
3. Collecting detailed metrics for each associated process

Data Collection

Machine-wide metrics:

• Load averages (Linux only)
• CPU percentage
• Memory usage (used/total/percentage)
• Swap usage
• Disk usage for agent directory
• Network interface statistics
• Network throughput

Process-specific metrics:

• Process ID and name
• Command line
• CPU percentage
• Memory usage (RSS/VMS)
• I/O statistics (read/write bytes)
• Open file descriptors
• Listening network ports
• Server directory size

Monitoring and Troubleshooting

Log Messages

The agent logs resource collection activity:

Starting resource stats collection
Resource stats collection completed

Error Handling

If database modules are not available:

DBD::mysql not available - resource stats collection disabled

If database connection fails:

Failed to connect to stats database: [error details]

Verification

To verify the system is working:

1. Check agent logs for collection messages
2. Query the database tables:

   SELECT COUNT(*) FROM gsp_machine_samples WHERE ts >= NOW() - INTERVAL 1 HOUR;
   SELECT COUNT(*) FROM gsp_process_samples WHERE ts >= NOW() - INTERVAL 1 HOUR;
   

Performance Impact

• Collection runs every 5 minutes by default (configurable)
• Minimal performance overhead during collection
• Uses native system tools for maximum efficiency
• Database operations are optimized with prepared statements

Migration from collector.py

To migrate from the standalone Python collector:

1. Stop the cron job running collector.py
2. Install Perl database modules on agent machines
3. Update agent configuration with database details
4. Restart OGP agents to enable collection
5. Verify data collection is working
6. Remove collector.py and Python dependencies

The new system produces identical data to collector.py and uses the same database schema, so existing dashboards and reports will continue to work without changes.

Frequency Configuration

The collection frequency can be adjusted by changing stats_frequency_minutes in the config:

• stats_frequency_minutes => '1' - Every minute (high frequency)
• stats_frequency_minutes => '5' - Every 5 minutes (default)
• stats_frequency_minutes => '15' - Every 15 minutes (low frequency)

Note: Very high frequencies (every minute) may impact performance on busy servers.

Security Considerations

• Database credentials are stored in agent configuration files
• Use dedicated database user with minimal privileges
• Consider firewall rules if database is on separate server
• Monitor database connections and prevent connection leaks

Troubleshooting Common Issues

Collection not working:

1. Check if DBD::mysql is installed
2. Verify database connection details
3. Check database user permissions
4. Review agent logs for error messages

Missing process data:

1. Verify game servers are running from subdirectories
2. Check process detection logic matches your server layout
3. Review process association in agent logs

Performance issues:

1. Reduce collection frequency
2. Check database performance
3. Monitor agent resource usage during collection