xui-one-api-docs/docs/categories/04-logs-events.md

Logs & Events API - Monitoring & Auditing

Complete documentation for logging and monitoring endpoints in the XUI.ONE Admin API.

📋 Overview

The Logs & Events API provides comprehensive monitoring and auditing capabilities for your IPTV panel. Track user activity, monitor connections, troubleshoot issues, and maintain security through detailed logging.

Available Endpoints

Endpoint	Description	Filters Available
activity_logs	Admin/user actions	limit, offset
live_connections	Active viewer connections	-
credit_logs	Credit transactions	user_id
client_logs	Client connection attempts	line_id
user_logs	User panel activity	user_id
stream_errors	Stream failures	stream_id
watch_output	Real-time stream monitoring	stream_id (required)
system_logs	System events	limit
login_logs	Login attempts	success (0/1)
restream_logs	Restreaming activity	-
mag_events	MAG device events	mag_id

---

📊 Activity Logs

Action: activity_logs

Monitor all administrative actions and changes in your panel.

Parameters:

• limit (optional) - Number of records (default: 100)
• offset (optional) - Pagination offset (default: 0)

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=activity_logs&limit=50"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "id": "1",
      "user_id": "1",
      "username": "admin",
      "action": "edit_line",
      "details": "Modified line ID 123",
      "ip_address": "192.168.1.100",
      "timestamp": "1734048000"
    }
  ]
}

Use Cases:

• Audit trail for compliance
• Track configuration changes
• Monitor admin actions
• Security investigation
• Troubleshooting

---

🔴 Live Connections

Action: live_connections

View real-time active connections to your streams.

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=live_connections"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "line_id": "123",
      "username": "testuser",
      "stream_id": "456",
      "stream_name": "CNN HD",
      "ip_address": "203.0.113.45",
      "user_agent": "VLC/3.0.11",
      "started_at": "1734048000",
      "duration": "3600"
    }
  ]
}

Use Cases:

• Monitor concurrent viewers
• Detect connection sharing
• Track popular streams
• View geographic distribution
• Calculate bandwidth usage

---

💰 Credit Logs

Action: credit_logs

Track credit transactions for resellers.

Parameters:

• user_id (optional) - Filter by specific user

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=credit_logs&user_id=5"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "id": "1",
      "user_id": "5",
      "username": "reseller1",
      "action": "add_credits",
      "amount": "100.00",
      "balance_after": "500.00",
      "description": "Credit purchase",
      "timestamp": "1734048000"
    }
  ]
}

Use Cases:

• Financial auditing
• Track reseller spending
• Monitor credit flow
• Generate invoices
• Revenue reporting

---

📱 Client Logs

Action: client_logs

Monitor client connection attempts and history.

Parameters:

• line_id (optional) - Filter by specific line

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=client_logs&line_id=123"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "line_id": "123",
      "username": "testuser",
      "ip_address": "203.0.113.45",
      "user_agent": "Kodi/19.4",
      "connection_type": "m3u8",
      "timestamp": "1734048000"
    }
  ]
}

Use Cases:

• Track device usage
• Detect suspicious patterns
• Monitor connection types
• View client apps
• Troubleshoot connection issues

---

👤 User Logs

Action: user_logs

Monitor user actions within the panel.

Parameters:

• user_id (optional) - Filter by specific user

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_logs"

Use Cases:

• Track reseller activity
• Monitor panel usage
• Audit user changes
• Security monitoring

---

⚠️ Stream Errors

Action: stream_errors

View stream failure logs and error information.

Parameters:

• stream_id (optional) - Filter by specific stream

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=stream_errors&stream_id=456"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "stream_id": "456",
      "stream_name": "CNN HD",
      "error_type": "source_offline",
      "error_message": "Connection refused to source",
      "timestamp": "1734048000",
      "duration": "120"
    }
  ]
}

Use Cases:

• Troubleshoot stream issues
• Monitor stream reliability
• Identify problematic sources
• Track downtime
• Generate uptime reports

---

👁️ Watch Stream Output

Action: watch_output

Monitor live stream encoding details and quality.

Parameters:

• stream_id (required) - Stream ID to monitor

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=watch_output&stream_id=456"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": {
    "stream_id": "456",
    "bitrate": "4500 kbps",
    "resolution": "1920x1080",
    "fps": "30",
    "codec": "H.264",
    "audio_codec": "AAC",
    "buffer_health": "good"
  }
}

Use Cases:

• Monitor encoding quality
• Verify stream settings
• Diagnose playback issues
• Check bitrate stability
• Real-time troubleshooting

---

🖥️ System Logs

Action: system_logs

View system-level events and errors.

Parameters:

• limit (optional) - Number of records (default: 100)

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=system_logs&limit=50"

Use Cases:

• Monitor system health
• Track errors and warnings
• Performance monitoring
• Capacity planning
• Troubleshooting

---

🔐 Login Logs

Action: login_logs

Monitor login attempts to the panel.

Parameters:

• success (optional) - Filter by status (1 = successful, 0 = failed)

Request:

# Failed logins only
curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=login_logs&success=0"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "username": "admin",
      "ip_address": "203.0.113.45",
      "success": "0",
      "failure_reason": "Invalid password",
      "timestamp": "1734048000"
    }
  ]
}

Use Cases:

• Detect brute force attacks
• Monitor unauthorized access
• Track successful logins
• Security auditing
• IP blocking decisions

---

🔄 Restream Logs

Action: restream_logs

Monitor reseller restreaming activity.

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=restream_logs"

Use Cases:

• Track restream usage
• Monitor reseller activity
• Bandwidth analysis
• Performance monitoring

---

📺 MAG Events

Action: mag_events

View MAG device event logs.

Parameters:

• mag_id (optional) - Filter by specific MAG device

Request:

curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=mag_events&mag_id=202"

Response Example:

{
  "status": "STATUS_SUCCESS",
  "data": [
    {
      "mag_id": "202",
      "mac": "00:1A:79:XX:XX:XX",
      "event_type": "channel_change",
      "details": "Changed to channel CNN HD",
      "ip_address": "203.0.113.45",
      "timestamp": "1734048000"
    }
  ]
}

Use Cases:

• Track MAG usage
• Monitor device events
• Troubleshoot issues
• View viewing patterns

---

💻 Code Examples

Python - Comprehensive Monitoring Dashboard

import requests
from datetime import datetime
from collections import defaultdict

class XUIMonitor:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.api_key = api_key
    
    def _make_request(self, action, params=None):
        """Make API request"""
        request_params = {
            "api_key": self.api_key,
            "action": action
        }
        if params:
            request_params.update(params)
        
        response = requests.get(self.base_url, params=request_params)
        result = response.json()
        
        if result["status"] != "STATUS_SUCCESS":
            raise Exception(f"API Error: {result.get('error', 'Unknown')}")
        
        return result["data"]
    
    def get_live_connections(self):
        """Get current live connections"""
        return self._make_request("live_connections")
    
    def get_activity_logs(self, limit=100):
        """Get recent activity logs"""
        return self._make_request("activity_logs", {"limit": limit})
    
    def get_stream_errors(self, stream_id=None):
        """Get stream error logs"""
        params = {}
        if stream_id:
            params["stream_id"] = stream_id
        return self._make_request("stream_errors", params)
    
    def get_failed_logins(self):
        """Get failed login attempts"""
        return self._make_request("login_logs", {"success": 0})
    
    def generate_dashboard(self):
        """Generate monitoring dashboard"""
        print("=" * 60)
        print("XUI.ONE Monitoring Dashboard")
        print("=" * 60)
        print(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
        print()
        
        # Live Connections
        connections = self.get_live_connections()
        print(f"🔴 Live Connections: {len(connections)}")
        
        # Group by stream
        streams = defaultdict(int)
        for conn in connections:
            streams[conn.get('stream_name', 'Unknown')] += 1
        
        print("\nTop Streams:")
        for stream, count in sorted(streams.items(), key=lambda x: x[1], reverse=True)[:5]:
            print(f"  • {stream}: {count} viewers")
        
        # Failed Logins
        failed_logins = self.get_failed_logins()
        if failed_logins:
            print(f"\n⚠️  Failed Login Attempts: {len(failed_logins)}")
            
            # Group by IP
            ips = defaultdict(int)
            for login in failed_logins:
                ips[login['ip_address']] += 1
            
            suspicious = [(ip, count) for ip, count in ips.items() if count > 5]
            if suspicious:
                print("\n🚨 Suspicious IPs (5+ failed attempts):")
                for ip, count in sorted(suspicious, key=lambda x: x[1], reverse=True):
                    print(f"  • {ip}: {count} attempts")
        
        # Stream Errors
        errors = self.get_stream_errors()
        if errors:
            print(f"\n⚠️  Stream Errors: {len(errors)}")
            
            # Recent errors
            recent = sorted(errors, key=lambda x: x['timestamp'], reverse=True)[:5]
            print("\nRecent Errors:")
            for error in recent:
                time = datetime.fromtimestamp(int(error['timestamp']))
                print(f"  • {error['stream_name']}: {error['error_message']} ({time.strftime('%H:%M:%S')})")
        
        print("\n" + "=" * 60)

# Usage
monitor = XUIMonitor(
    base_url="http://your-server.com/cSbuFLhp/",
    api_key="8D3135D30437F86EAE2FA4A2A8345000"
)

# Generate dashboard
monitor.generate_dashboard()

---

Python - Connection Sharing Detection

from collections import defaultdict
from datetime import datetime

def detect_connection_sharing(monitor):
    """Detect potential connection sharing by analyzing concurrent connections"""
    connections = monitor.get_live_connections()
    
    # Group by line_id
    lines = defaultdict(list)
    for conn in connections:
        lines[conn['line_id']].append(conn)
    
    # Find violations
    violations = []
    for line_id, conns in lines.items():
        if len(conns) > 1:
            # Check if from different IPs
            ips = set(c['ip_address'] for c in conns)
            if len(ips) > 1:
                violations.append({
                    'line_id': line_id,
                    'username': conns[0]['username'],
                    'connection_count': len(conns),
                    'unique_ips': len(ips),
                    'ips': list(ips)
                })
    
    if violations:
        print(f"⚠️  Found {len(violations)} potential sharing violations:")
        for v in violations:
            print(f"\n  Line: {v['username']} (ID: {v['line_id']})")
            print(f"  Connections: {v['connection_count']}")
            print(f"  Unique IPs: {v['unique_ips']}")
            print(f"  IPs: {', '.join(v['ips'])}")
    else:
        print("✓ No connection sharing detected")
    
    return violations

---

Python - Stream Health Monitor

from datetime import datetime, timedelta

def monitor_stream_health(monitor):
    """Monitor stream reliability and generate health report"""
    errors = monitor.get_stream_errors()
    
    # Group by stream
    stream_errors = defaultdict(list)
    for error in errors:
        stream_errors[error['stream_id']].append(error)
    
    print("Stream Health Report")
    print("=" * 50)
    
    for stream_id, error_list in stream_errors.items():
        if not error_list:
            continue
        
        stream_name = error_list[0].get('stream_name', f'Stream {stream_id}')
        error_count = len(error_list)
        
        # Calculate total downtime
        total_downtime = sum(int(e.get('duration', 0)) for e in error_list)
        
        # Recent errors
        recent = [e for e in error_list 
                 if int(e['timestamp']) > (datetime.now().timestamp() - 86400)]
        
        print(f"\n📺 {stream_name}")
        print(f"  Total Errors: {error_count}")
        print(f"  Errors (24h): {len(recent)}")
        print(f"  Total Downtime: {total_downtime // 60} minutes")
        
        if error_count > 10:
            print(f"  🚨 HIGH ERROR COUNT - Investigate source!")

---

Python - Security Alert System

def security_monitor(monitor):
    """Monitor for security issues"""
    alerts = []
    
    # Check failed logins
    failed = monitor.get_failed_logins()
    
    # Group by IP
    ip_attempts = defaultdict(int)
    for login in failed:
        ip_attempts[login['ip_address']] += 1
    
    # Alert on brute force attempts
    for ip, count in ip_attempts.items():
        if count >= 5:
            alerts.append({
                'type': 'brute_force',
                'severity': 'high' if count >= 10 else 'medium',
                'ip': ip,
                'attempts': count,
                'message': f"Brute force detected from {ip} ({count} attempts)"
            })
    
    # Check activity logs for suspicious actions
    activity = monitor.get_activity_logs(limit=100)
    
    # Alert on mass deletions
    deletes = [a for a in activity if 'delete' in a.get('action', '').lower()]
    if len(deletes) > 10:
        alerts.append({
            'type': 'mass_deletion',
            'severity': 'high',
            'count': len(deletes),
            'message': f"Mass deletion detected: {len(deletes)} items deleted recently"
        })
    
    # Display alerts
    if alerts:
        print("🚨 Security Alerts")
        print("=" * 50)
        for alert in alerts:
            severity_icon = "🔴" if alert['severity'] == 'high' else "🟡"
            print(f"\n{severity_icon} {alert['type'].upper()}")
            print(f"  {alert['message']}")
    else:
        print("✅ No security issues detected")
    
    return alerts

---

PHP - Real-time Connection Monitor

<?php
class XUIMonitor {
    private $baseUrl;
    private $apiKey;
    
    public function __construct($baseUrl, $apiKey) {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
    }
    
    private function makeRequest($action, $params = []) {
        $url = $this->baseUrl . "?api_key=" . $this->apiKey . "&action=" . $action;
        
        if (!empty($params)) {
            $url .= "&" . http_build_query($params);
        }
        
        $response = file_get_contents($url);
        $result = json_decode($response, true);
        
        if ($result['status'] !== 'STATUS_SUCCESS') {
            throw new Exception("API Error: " . ($result['error'] ?? 'Unknown'));
        }
        
        return $result['data'];
    }
    
    public function getLiveConnections() {
        return $this->makeRequest('live_connections');
    }
    
    public function getConnectionStats() {
        $connections = $this->getLiveConnections();
        
        $stats = [
            'total' => count($connections),
            'by_stream' => [],
            'by_user' => [],
            'unique_ips' => []
        ];
        
        foreach ($connections as $conn) {
            // Count by stream
            $stream = $conn['stream_name'] ?? 'Unknown';
            $stats['by_stream'][$stream] = ($stats['by_stream'][$stream] ?? 0) + 1;
            
            // Count by user
            $user = $conn['username'] ?? 'Unknown';
            $stats['by_user'][$user] = ($stats['by_user'][$user] ?? 0) + 1;
            
            // Track IPs
            $stats['unique_ips'][] = $conn['ip_address'];
        }
        
        $stats['unique_ips'] = array_unique($stats['unique_ips']);
        
        return $stats;
    }
}

// Usage
$monitor = new XUIMonitor(
    "http://your-server.com/cSbuFLhp/",
    "8D3135D30437F86EAE2FA4A2A8345000"
);

$stats = $monitor->getConnectionStats();

echo "Live Connection Statistics\n";
echo "==========================\n";
echo "Total Connections: " . $stats['total'] . "\n";
echo "Unique IPs: " . count($stats['unique_ips']) . "\n\n";

echo "Top Streams:\n";
arsort($stats['by_stream']);
foreach (array_slice($stats['by_stream'], 0, 5) as $stream => $count) {
    echo "  • $stream: $count viewers\n";
}
?>

---

JavaScript - Live Dashboard (Node.js)

const fetch = require('node-fetch');

class XUIMonitor {
    constructor(baseUrl, apiKey) {
        this.baseUrl = baseUrl;
        this.apiKey = apiKey;
    }
    
    async makeRequest(action, params = {}) {
        const url = new URL(this.baseUrl);
        url.searchParams.append('api_key', this.apiKey);
        url.searchParams.append('action', action);
        
        for (const [key, value] of Object.entries(params)) {
            url.searchParams.append(key, value);
        }
        
        const response = await fetch(url);
        const result = await response.json();
        
        if (result.status !== 'STATUS_SUCCESS') {
            throw new Error(`API Error: ${result.error || 'Unknown'}`);
        }
        
        return result.data;
    }
    
    async getLiveConnections() {
        return this.makeRequest('live_connections');
    }
    
    async getStreamErrors() {
        return this.makeRequest('stream_errors');
    }
    
    async displayDashboard() {
        console.clear();
        console.log('═'.repeat(60));
        console.log('XUI.ONE Live Dashboard');
        console.log('═'.repeat(60));
        console.log(`Updated: ${new Date().toLocaleString()}\n`);
        
        // Live connections
        const connections = await this.getLiveConnections();
        console.log(`🔴 Live Connections: ${connections.length}`);
        
        // Stream breakdown
        const streams = connections.reduce((acc, conn) => {
            const name = conn.stream_name || 'Unknown';
            acc[name] = (acc[name] || 0) + 1;
            return acc;
        }, {});
        
        const topStreams = Object.entries(streams)
            .sort((a, b) => b[1] - a[1])
            .slice(0, 5);
        
        if (topStreams.length > 0) {
            console.log('\nTop Streams:');
            topStreams.forEach(([stream, count]) => {
                console.log(`  • ${stream}: ${count} viewers`);
            });
        }
        
        // Stream errors
        const errors = await this.getStreamErrors();
        const recentErrors = errors.filter(e => 
            parseInt(e.timestamp) > (Date.now() / 1000 - 3600)
        );
        
        if (recentErrors.length > 0) {
            console.log(`\n⚠️  Recent Errors (1h): ${recentErrors.length}`);
        }
        
        console.log('\n' + '═'.repeat(60));
    }
    
    startAutoRefresh(interval = 10000) {
        this.displayDashboard();
        setInterval(() => this.displayDashboard(), interval);
    }
}

// Usage
const monitor = new XUIMonitor(
    'http://your-server.com/cSbuFLhp/',
    '8D3135D30437F86EAE2FA4A2A8345000'
);

// Auto-refresh every 10 seconds
monitor.startAutoRefresh(10000);

---

🎯 Common Use Cases

1. Daily Security Report

def generate_security_report(monitor):
    """Generate daily security summary"""
    from datetime import datetime, timedelta
    
    yesterday = datetime.now() - timedelta(days=1)
    
    print("Daily Security Report")
    print("=" * 50)
    print(f"Date: {datetime.now().strftime('%Y-%m-%d')}")
    print()
    
    # Failed logins
    failed = monitor.get_failed_logins()
    print(f"Failed Login Attempts: {len(failed)}")
    
    # Activity summary
    activity = monitor.get_activity_logs(limit=1000)
    print(f"Admin Actions: {len(activity)}")
    
    # Connection sharing
    violations = detect_connection_sharing(monitor)
    print(f"Connection Violations: {len(violations)}")

2. Stream Performance Report

def stream_performance_report(monitor):
    """Generate stream uptime and performance report"""
    errors = monitor.get_stream_errors()
    
    # Calculate uptime percentage
    total_time = 24 * 3600  # 24 hours
    downtime = sum(int(e.get('duration', 0)) for e in errors)
    uptime_pct = ((total_time - downtime) / total_time) * 100
    
    print(f"Overall Uptime: {uptime_pct:.2f}%")
    print(f"Total Downtime: {downtime // 60} minutes")

3. Real-time Alerts

import time

def monitor_realtime_alerts(monitor):
    """Monitor for issues and send alerts"""
    last_check = {}
    
    while True:
        # Check for new stream errors
        errors = monitor.get_stream_errors()
        for error in errors:
            error_id = f"{error['stream_id']}_{error['timestamp']}"
            if error_id not in last_check:
                print(f"🚨 ALERT: Stream {error['stream_name']} - {error['error_message']}")
                last_check[error_id] = True
                # Send email/webhook here
        
        time.sleep(60)  # Check every minute

---

📚 Related Documentation

• GET INFO API - Query Data
• Line API - Management
• Authentication Guide

---

🆘 Need Help?

• GitHub Issues: Report problems
• Community: World of IPTV Forums
• Documentation: Getting Started Guide