secubox-openwrt/package/secubox/luci-app-secubox-netifyd/REFRESH-DEBUG.md

Netifyd Dashboard - Refresh & Debug Analysis

Refresh Problem Identified

Root Cause

The dashboard polling system had a race condition where:

1. poll.add() was called before containers were created
2. When the first poll callback executed, self.statusContainer, self.statsContainer, etc. were undefined
3. DOM updates failed silently because containers didn't exist yet
4. No error handling or logging to detect the issue

Code Flow Issue (Before Fix)

// WRONG ORDER - This was the problem:
poll.add(function() {
    // Try to update containers
    if (self.statusContainer) { ... }  // undefined!
});

// Containers created AFTER poll setup
self.statusContainer = E('div');
self.statsContainer = E('div');

The Fix

// CORRECT ORDER - Fixed version:

// 1. Create containers FIRST
self.statusContainer = E('div');
self.statsContainer = E('div');
self.appsContainer = E('div');
self.protosContainer = E('div');

// 2. THEN set up polling
poll.add(function() {
    // Now containers exist!
    if (self.statusContainer) {
        dom.content(self.statusContainer, newContent);
    }
});

Debug Features Added

1. Debug Mode Toggle

Button in Header: "Enable Debug" / "Disable Debug"

• Toggles debug logging to browser console
• Shows/hides debug panel with live log entries
• Changes button color (secondary → danger when enabled)

2. Debug Panel

Visual Log Display:

• Shows last 20 log entries
• Timestamp + message + JSON data
• Auto-scrolling, newest entries at top
• Monospaced font for readability
• Hidden by default, shown when debug enabled

3. Console Logging

Browser Console Output:

[NetifydDashboard 2026-01-06T17:30:00.123Z] Loading dashboard data... {...}
[NetifydDashboard 2026-01-06T17:30:00.456Z] Dashboard data loaded {...}
[NetifydDashboard 2026-01-06T17:30:00.789Z] Rendering dashboard {...}
[NetifydDashboard 2026-01-06T17:30:05.123Z] Polling for updates... (interval: 5s)
[NetifydDashboard 2026-01-06T17:30:05.456Z] Poll update #1 {...}

4. Update Indicator

Live Status Display:

• Shows in header: "Updates: 5 | Last: 3s ago"
• Updates every second
• Counts total poll updates
• Shows seconds since last update
• Visual feedback that polling is working

5. Error Tracking

Error Handling:

• Catches poll errors with try/catch
• Logs errors to debug panel
• Counts total errors: self.errorCount
• Includes error message and stack trace
• Doesn't break polling on error

Debug Data Logged

On Load

{
  "dashboard": {
    "service": { "running": true, "uptime": 123 },
    "stats": { "active_flows": 25, "unique_devices": 6 }
  },
  "status": { "running": true, "version": "5.2.1" },
  "apps": 3,
  "protocols": 3
}

On Poll Update

{
  "flows": 25,
  "devices": 6,
  "apps": 3
}

On Error

{
  "error": "RPC call failed: Connection timeout",
  "stack": "Error: RPC call failed...\n    at ..."
}

Metrics Tracked

• updateCount: Total number of successful polls
• errorCount: Total number of failed polls
• lastUpdate: Timestamp of last successful update
• refreshInterval: Polling interval in seconds (default: 5)

How to Use Debug Mode

Enable Debug

1. Open Netifyd Dashboard
2. Click "Enable Debug" button in top-right
3. Debug panel appears below description
4. Console logs start appearing

What to Look For

Healthy Dashboard:

Updates: 12 | Last: 2s ago

• Update count increasing every 5 seconds
• Last update time stays under 5 seconds

Problem Indicators:

Updates: 0 | Last: never

• No updates happening
• Check console for errors

Updates: 5 | Last: 45s ago

• Polling stopped or stalled
• Check for JavaScript errors in console

Debug Log Entries

Normal Operation:

2026-01-06T17:30:00.123Z Loading dashboard data...
2026-01-06T17:30:00.456Z Dashboard data loaded
2026-01-06T17:30:00.789Z Rendering dashboard
2026-01-06T17:30:05.123Z Polling for updates... (interval: 5s)
2026-01-06T17:30:05.456Z Poll update #1
2026-01-06T17:30:10.456Z Poll update #2

With Errors:

2026-01-06T17:30:05.123Z Polling for updates... (interval: 5s)
2026-01-06T17:30:05.456Z Poll error #1
  {
    "error": "RPC call failed",
    "stack": "Error: ..."
  }

Polling Configuration

Current Settings

• Interval: 5 seconds (refreshInterval: 5)
• Data Sources:
  • Dashboard stats (flows, devices, traffic)
  • Service status (running, uptime, version)
  • Top applications (DPI detected apps)
  • Top protocols (TCP/UDP/ICMP breakdown)

Changing Poll Interval

Edit dashboard.js:

return view.extend({
    refreshInterval: 10,  // Change to 10 seconds
    // ...
});

Valid range: 1-60 seconds (recommended: 5-10)

Troubleshooting

Dashboard Not Updating

1. Enable debug mode
2. Check update indicator
3. Look for errors in console
4. Check RPC backend is responding:

   ssh root@router 'ubus call luci.secubox-netifyd get_dashboard'
   

High Update Count, No Data Changes

Possible causes:

• Netifyd service running but no network traffic
• Network interfaces not being monitored
• Flow data not being captured

Solutions:

• Check netifyd -s output on router
• Verify interfaces are configured
• Generate some network traffic (ping, wget, etc.)

Errors in Debug Log

Common errors:

• "RPC call failed" → Backend not responding
• "Connection timeout" → Network issue
• "Method not found" → RPC method missing

Performance Considerations

Debug Mode Impact

• Console logging: Minimal (<1% CPU)
• Debug panel: Small DOM updates (~0.5 KB per entry)
• Memory: Max 20 entries × ~200 bytes = 4 KB

Polling Impact

• Network: ~1 KB per poll (4 RPC calls)
• CPU: <1% (JSON parsing + DOM updates)
• Recommended for: Production use

Reducing Impact

If needed, increase interval:

refreshInterval: 10,  // Less frequent updates

Code Architecture

Component Structure

dashboard.js
├── State Management
│   ├── debugMode (boolean)
│   ├── updateCount (number)
│   ├── errorCount (number)
│   └── lastUpdate (Date)
│
├── Debug Functions
│   ├── debug(message, data) - Log entry
│   └── toggleDebug(ev) - Toggle on/off
│
├── Data Loading
│   ├── load() - Initial load with debug
│   └── poll callback - Auto-refresh with debug
│
└── Rendering
    ├── render() - Main layout + debug panel
    ├── renderServiceStatus() - Status card
    ├── renderStatistics() - Metrics cards
    ├── renderTopApplications() - App chart
    └── renderTopProtocols() - Protocol chart

Polling Flow

[Page Load]
    ↓
load() - Fetch initial data
    ↓
render() - Create DOM + containers
    ↓
poll.add() - Register polling callback
    ↓
[Every 5 seconds]
    ↓
Poll callback executes
    ↓
Fetch fresh data (4 RPC calls)
    ↓
Update containers via dom.content()
    ↓
Update debug log & indicator
    ↓
[Repeat]

Future Enhancements

Potential Additions

1. Export Debug Log - Download as JSON/text file
2. Pause/Resume Polling - Manual control
3. Poll Interval Slider - UI control (1-60s)
4. Health Score - Green/yellow/red indicator
5. Network Stats Graph - Real-time chart
6. Alert Thresholds - Notify on high traffic
7. Debug Filters - Show only errors/warnings
8. Performance Metrics - RPC response times

API Enhancement Ideas

1. Batch RPC Calls - Single call for all data
2. Delta Updates - Only send changed data
3. Compression - Reduce network overhead
4. Caching - Client-side data retention

Summary

The refresh problem was caused by a race condition where polling started before DOM containers existed. The fix ensures containers are created first, then polling is initialized. Debug mode provides comprehensive visibility into the polling system, making future issues easy to diagnose.

Key Improvements:

• ✅ Fixed container creation order
• ✅ Added error handling to polls
• ✅ Added visual debug panel
• ✅ Added console logging
• ✅ Added update indicator
• ✅ Added error counting
• ✅ Zero production impact when debug disabled