Troubleshooting & FAQ

This guide contains common issues, debugging procedures, and frequently asked questions when configuring the CollectorCtrl Management Server and Supervisor Agents.

---

1. Supervisor Agent Won't Connect to Server

Symptoms

• The agent doesn't appear in the Agents inventory tab in the Web UI.
• Supervisor log file displays WebSocket connection failed or dial tcp [IP]:4320: connect: connection refused.

Debugging Steps

1. Verify Port Accessibility: Ensure target supervisors can reach the Management Server on port 4320 (the default OpAMP gateway). You can verify network routing using telnet or Test-NetConnection:

   # Windows PowerShell
   Test-NetConnection -ComputerName YOUR_SERVER_IP -Port 4320
   

   # Linux
   nc -zv YOUR_SERVER_IP 4320
   

2. Check Endpoint Protocol Scheme: The endpoint in supervisor.yaml must use the ws:// (unencrypted) or wss:// (secure SSL) scheme:
   • Correct: endpoint: "wss://YOUR_SERVER_IP:4320/v1/opamp"
   • Incorrect: endpoint: "http://YOUR_SERVER_IP:4320"
3. Verify API Enrollment Token: Check that the token parameter inside /etc/collectorctrl/supervisor.yaml (Linux) or C:\Program Files\CollectorCtrl Supervisor\supervisor.yaml (Windows) matches the API token generated in the Admin UI.

---

2. Configuration Policy Updates Are Not Applying

Symptoms

• The agent status displays a orange Reconciling warning state.
• Live configuration changes do not propagate to the local OTel Collector processes.

Debugging Steps

1. Dry-Run Syntax Verification: Before the Supervisor applies any configuration, it runs a syntax pre-flight check. Check the supervisor logs for validation errors (e.g., invalid YAML indentation, unsupported receivers).
2. Verify otelcol Binary Path: Ensure the agent.executable parameter in the supervisor.yaml file points to a valid, working OpenTelemetry Collector binary:
   • Windows: Must point to the absolute path of otelcol.exe (e.g., C:\Program Files\otelcol\otelcol.exe). Escape backslashes as \\.
   • Linux: Must have execute permissions (chmod +x /usr/local/bin/otelcol).
3. Verify Health Port Access: The Supervisor checks collector health using http://localhost:13133. Ensure that your base OTel Collector configuration includes the health_check extension on port 13133.

---

3. High CPU or Memory Usage on Edge Nodes

Symptoms

• CPU spikes on server virtualization hosts running the supervisor or collector daemons.

Debugging Steps

1. Throttling via cgroups (Linux): You can limit the resources consumed by the collector process using cgroups. Edit the /etc/systemd/system/collectorctrl-supervisor.service unit file to add boundaries:

   [Service]
   MemoryMax=512M
   CPUQuota=20%
   

2. Adjust Heartbeat Intervals: High-frequency status logs can increase overhead. Under /etc/collectorctrl/supervisor.yaml, make sure heartbeat logs are only sent at standard intervals:

   telemetry:
     logs:
       level: warn
   

---

4. Where to Find System Logs

When contacting support or diagnosing issues, refer to the following log locations:

Component	OS Platform	Default Log File Path
Management Server	Windows	C:\ProgramData\CollectorCtrl\logs\server.log
Management Server	Linux	/var/log/collectorctrl/server.log (or journalctl -u collectorctrl)
Supervisor Service	Windows	C:\ProgramData\CollectorCtrlSupervisor\supervisor.log
Supervisor Daemon	Linux	/var/log/collectorctrl/supervisor.log (or journalctl -u collectorctrl-supervisor)
Managed Collector	All	Captured dynamically and streamable in the Admin UI Console