Agent Management

Monitoring agents are the backbone of CuliUptime's global monitoring network. They perform health checks from different geographic locations to provide accurate, consensus-based monitoring with reduced false positives.

🌍 Global Agent Network

What are Monitoring Agents?

Monitoring agents are lightweight PHP scripts deployed across multiple global locations that:

Execute HTTP/HTTPS health checks for your monitors
Report results back to your CuliUptime instance
Use HMAC authentication for secure communication
Provide geographic diversity for accurate monitoring

Agent Locations

Cloud Service Agents (Managed):

🇺🇸 US East - Virginia (us-east-1)
🇺🇸 US West - California (us-west-1)
🇪🇺 EU West - Ireland (eu-west-1)
🇸🇬 Asia Pacific - Singapore (ap-southeast-1)

Self-Hosted Agents:

Deploy PHP agents anywhere globally
Custom locations for compliance requirements
Private network monitoring capabilities
On-premises infrastructure coverage

🔧 Agent Configuration

Agent Status Dashboard

View and manage your agent network from Dashboard → Agents:

Agent Health - Online/offline status and last heartbeat
Response Times - Average response time from each location
Success Rate - Percentage of successful checks per agent
Geographic Distribution - Visual map of agent locations
Load Balancing - Request distribution across agents

Agent Assignment

Automatic Assignment (Recommended):

Mode: Auto-assign
Strategy: Geographic distribution
Load balancing: Yes
Failover: Automatic

Manual Assignment:

Mode: Manual selection
Locations: [us-east-1, eu-west-1]
Primary: us-east-1
Backup: eu-west-1

Custom Assignment:

Mode: Custom rules
Rules:
  - Monitor type: API → [us-east-1, us-west-1]
  - Monitor type: Website → [all locations]
  - Critical services → [3+ locations minimum]

🔐 Agent Security

HMAC Authentication

All agents use HMAC-SHA256 authentication for secure communication:

Security Features:

Request Signing - Every request cryptographically signed
Timestamp Validation - Prevents replay attacks
Shared Secret - Unique key per agent installation
SSL/TLS - All communication encrypted in transit

Agent Configuration (in web_agent.php):

// AGENT CONFIGURATION - SET THESE VALUES DURING DEPLOYMENT
define('AGENT_ID', 'agent-unique-identifier');
define('AGENT_SECRET_KEY', 'your-hmac-secret-key');
define('PLATFORM_API_KEY', 'your-platform-api-key');

Agent API Keys

Key Management:

Rotation - Keys should be rotated every 90 days
Scope - Each agent has unique authentication keys
Monitoring - Failed authentication attempts logged
Revocation - Instantly disable compromised agents

🚀 Self-Hosted Agent Deployment

Requirements

System Requirements:

PHP 7.4+ with cURL and JSON extensions
Web hosting or VPS with HTTPS support
SSL certificate (Let's Encrypt or self-signed)
Web-accessible deployment capability

Network Requirements:

Access to monitored endpoints
HTTPS connectivity to CuliUptime instance
Port 443 outbound for SSL/TLS

Installation

📖 Complete Installation Guide
For detailed agent deployment instructions, see the Agent Deployment Guide

Quick Installation Steps:

1. Download Agent File

# Download web_agent.php from CuliUptime repository
wget https://raw.githubusercontent.com/chiplonton/culiuptime/main/agents/web_agent.php

2. Configure Agent Edit the configuration section at the top of web_agent.php:

// Edit these values in web_agent.php
define('AGENT_ID', 'your-agent-location-id');
define('AGENT_SECRET_KEY', 'your-agent-secret-from-culiuptime-env');
define('PLATFORM_API_KEY', 'your-platform-api-key');

3. Deploy to Web Server

# Upload to your hosting/VPS web directory
# Make accessible via HTTPS (e.g., https://yourdomain.com/agent/web_agent.php)

4. Add Agent in CuliUptime Dashboard

Go to Dashboard → Agents
Click "Add Agent"
Enter agent URL: https://yourdomain.com/agent/web_agent.php
Enter location name and test connection

Agent Configuration

Configuration is embedded in web_agent.php (lines 17-26):

// AGENT CONFIGURATION - SET THESE VALUES DURING DEPLOYMENT
define('AGENT_ID', getenv('AGENT_ID') ?: 'your-agent-uuid-here');
define('AGENT_SECRET_KEY', getenv('AGENT_SECRET_KEY') ?: 'your-shared-secret-here');
define('PLATFORM_API_KEY', getenv('PLATFORM_API_KEY') ?: 'platform-api-key-here');

$AGENT_CONFIG = [
    'version' => '0.1.0',
    'name' => 'CuliUptime Web Agent',
    'agent_id' => AGENT_ID,
    'shared_secret' => AGENT_SECRET_KEY,
    'platform_api_key' => PLATFORM_API_KEY,
    'supported_protocols' => ['http', 'https'],
    'capabilities' => [
        'max_concurrent_checks' => 100,
        'timeout_range' => ['min' => 1, 'max' => 300],
        // ... additional capabilities defined in web_agent.php
    ]
];

Configuration Methods:

Environment Variables (recommended for production)
Direct file editing of the define() statements

📊 Agent Monitoring & Health

Agent Metrics

Health Indicators:

Heartbeat - Last successful communication
Response Time - Average request processing time
Success Rate - Percentage of successful checks
Error Rate - Failed requests and timeouts
Load - Current number of active monitors

Performance Optimization

Agent Performance Tuning:

Parallel Processing - Handle multiple checks simultaneously
Connection Pooling - Reuse HTTP connections
Local Caching - Cache DNS resolutions
Timeout Optimization - Balance accuracy vs. speed

Resource Management:

// Agent performance settings
MAX_CONCURRENT_CHECKS=10
CONNECTION_TIMEOUT=10
READ_TIMEOUT=30
DNS_CACHE_TTL=300

🔍 Troubleshooting Agents

Common Issues

1. Agent Offline

# Test agent endpoint directly
curl -I https://yourdomain.com/agent/web_agent.php

# Verify network connectivity to your CuliUptime instance
curl -I https://your-instance.com/api/health

# Check web server error logs
sudo tail -f /var/log/nginx/error.log

2. High Response Times

Network latency - Choose geographically closer agents
Resource constraints - Increase server resources
DNS issues - Use faster DNS resolvers
SSL handshake - Optimize cipher suites

3. Authentication Failures

Key mismatch - Verify HMAC keys match
Time sync - Ensure system time is accurate
Key rotation - Update expired keys
SSL issues - Verify certificate validity

Agent Logs

Log Analysis:

# Check web server access logs
tail -f /var/log/nginx/access.log | grep web_agent

# Check web server error logs  
tail -f /var/log/nginx/error.log

# Check PHP error logs
tail -f /var/log/php/error.log

Log Levels:

ERROR - Authentication failures, network errors
WARN - Timeouts, retry attempts
INFO - Successful checks, configuration changes
DEBUG - Detailed request/response data

🌐 Multi-Agent Consensus

Consensus Logic

Consensus Strategies:

Majority Consensus - Service down if >50% of agents fail
Any Location - Service down if any agent fails
All Locations - Service down only if all agents fail
Custom Threshold - Define specific failure count

Example Consensus:

Agents: [us-east-1, eu-west-1, ap-southeast-1]
Strategy: Majority consensus
Results: [✅ UP, ❌ DOWN, ✅ UP]
Final Status: ✅ UP (2/3 agents report healthy)

False Positive Reduction

Benefits:

Network Issues - Local network problems don't trigger false alerts
Regional Outages - ISP or regional issues isolated
Load Balancer Behavior - Geographic routing variations detected
Geographic Isolation - Regional network issues don't affect global status

📋 Best Practices

Agent Deployment Strategy

Geographic Distribution - Deploy agents across different continents
Network Diversity - Use different ISPs and network providers
Redundancy Planning - Always have backup agents per region
Load Balancing - Distribute monitoring load evenly

Security Considerations

Key Management - Rotate HMAC keys regularly
Network Security - Use firewalls and access controls
Monitoring - Monitor agent health and authentication
Updates - Keep agent software up to date

Performance Optimization

Resource Allocation - Size agents appropriately for monitor count
Network Optimization - Use CDNs and optimized routing
Caching Strategy - Implement intelligent caching
Scaling - Add agents based on monitor growth

🚀 Next Steps

Monitor Configuration - Set up your first monitors
Dashboard Usage - Monitor agent health and performance
Getting Started: Self-Hosting - Deploy your own instance with agents

🌍 Global Agent Network​

What are Monitoring Agents?​

Agent Locations​

🔧 Agent Configuration​

Agent Status Dashboard​

Agent Assignment​

🔐 Agent Security​

HMAC Authentication​

Agent API Keys​

🚀 Self-Hosted Agent Deployment​

Requirements​

Installation​

Agent Configuration​

📊 Agent Monitoring & Health​

Agent Metrics​

Performance Optimization​

🔍 Troubleshooting Agents​

Common Issues​

Agent Logs​

🌐 Multi-Agent Consensus​

Consensus Logic​

False Positive Reduction​

📋 Best Practices​

Agent Deployment Strategy​

Security Considerations​

Performance Optimization​

🚀 Next Steps​

🌍 Global Agent Network

What are Monitoring Agents?

Agent Locations

🔧 Agent Configuration

Agent Status Dashboard

Agent Assignment

🔐 Agent Security

HMAC Authentication

Agent API Keys

🚀 Self-Hosted Agent Deployment

Requirements

Installation

Agent Configuration

📊 Agent Monitoring & Health

Agent Metrics

Performance Optimization

🔍 Troubleshooting Agents

Common Issues

Agent Logs

🌐 Multi-Agent Consensus

Consensus Logic

False Positive Reduction

📋 Best Practices

Agent Deployment Strategy

Security Considerations

Performance Optimization

🚀 Next Steps