Troubleshooting Guide

Symptoms: Agent doesn't show up in dashboard or shows as offline

Solutions:

1. Check agent service is running:
   bash

   # Linux
   sudo systemctl status astranetmon-agent
   
   # Windows
   Get-Service "AstraNetmon Agent"
   
   # macOS
   sudo launchctl list | grep astranetmon

2. Verify API key is correct:
   • Check config.toml file
   • Compare with key from Dashboard → Settings → Agents
   • Ensure no extra spaces or quotes around the key
3. Check network connectivity:
   bash

   # Test if you can reach the API
   curl -v https://your-domain.astraid.io/api/agent/health

4. Review agent logs:
   bash

   # Linux
   sudo journalctl -u astranetmon-agent -n 50
   
   # Windows
   Get-Content "C:\ProgramData\AstraNetmon\logs\agent.log" -Tail 50
   
   # macOS
   tail -f /var/log/astranetmon-agent.log

5. Check firewall rules: Ensure outbound HTTPS (port 443) is allowed

Symptoms: Agent shows online but metrics are stale

Solutions:

• Verify poll_interval is set correctly in config
• Check agent logs for metric collection errors
• Ensure agent has permission to read system metrics
• Restart the agent service

Symptoms: Agent consuming too much CPU or memory

Solutions:

• Increase poll_interval to reduce frequency
• Disable speedtest if not needed
• Reduce number of traceroute targets
• Update to latest agent version

Solutions:

• Verify you're using the correct subdomain (multi-tenant setups)
• Check if MFA is enabled and you have your authenticator app
• Try password reset if forgotten
• Clear browser cookies and cache
• Try a different browser or incognito mode

Explanation: Sessions expire after 15 minutes of inactivity for security.

Solutions:

• This is by design for security
• Simply log in again when session expires
• Keep browser tab active to prevent expiration

Solutions:

• Refresh the page
• Check browser console for JavaScript errors
• Disable browser extensions (ad blockers, etc.)
• Ensure agent has sent data in selected time range

Solutions:

1. Check spam/junk folders
2. Whitelist noreply@your-domain.com in email client
3. Verify email addresses in Dashboard → Settings → Alerts
4. Ensure agent status notifications are enabled
5. Test by restarting an agent to trigger an alert

Solutions:

• Check webhook is enabled in dashboard
• Verify correct events are subscribed
• Test webhook URL with curl
• Review webhook failure count
• Check webhook endpoint returns 2xx status code
• Ensure endpoint responds within 30 seconds

# Test webhook manually
curl -X POST https://your-webhook-url.com \
  -H "Content-Type: application/json" \
  -d '{"event":"test","timestamp":"2025-12-17T10:00:00Z","data":{}}'

Solutions:

• Verify API key is in Authorization header
• Check format: Authorization: Bearer astra_...
• Ensure key hasn't expired
• Verify key is enabled in dashboard
• Regenerate key if copy/paste may have introduced errors

Solutions:

• Check API key has required permissions
• Verify you're accessing correct endpoint
• Ensure you're in the right tenant

Solutions:

• Implement exponential backoff in your code
• Cache API responses when possible
• Upgrade plan for higher rate limits
• Spread requests over time instead of bursting

Solutions:

• Verify speedtest_enabled = true in config
• Check speedtest_interval is set
• Ensure agent has internet connectivity
• Review agent logs for speedtest errors
• Verify plan includes speed test feature

Possible Causes:

• Network congestion during test
• Running during backup windows or heavy usage
• Distance to speed test server
• Local firewall or QoS rules

Best Practices:

• Run tests at consistent times
• Compare multiple tests over time
• Consider business hours vs. off-hours

Solutions:

• Ensure sufficient data in selected time range
• Try shorter time range
• Check browser console for errors
• Refresh page and try again
• Verify plan includes report generation

Solutions:

• Verify agent was online during report period
• Check if features were enabled (speedtest, etc.)
• Ensure data retention period covers report range
• Review agent logs for data collection issues

Solutions:

• Reduce time range for metric queries
• Filter to specific agents instead of viewing all
• Clear browser cache
• Check internet connection speed
• Try during off-peak hours