Skip to main content

Troubleshooting

Almost everything is visible in the log:

tail -f /var/log/wakora/agent.log

The host does not appear in the console​

  1. Confirm the service is running: systemctl status wakora-agent (or the service equivalent on macOS or Windows).
  2. Confirm the agent registered: the log should show a server UUID after wakora --key. If it says "no identity yet", you installed the service before entering the key. Run wakora --key <TEAM_KEY> and it starts within 15 seconds, no restart needed.
  3. Confirm the WebSocket connects: look for the heartbeat and definitions received: N in the log. A repeated dial ... : line means the agent cannot reach the endpoint. Check outbound connectivity to the gateway. The agent needs only outbound access, no inbound ports.

"identity key is not decryptable on this machine"​

The identity file was created on a different machine, or the machine id or the root-only seed changed. Identity is bound to the machine, so a copied identity file will not decrypt elsewhere. Re-register on this host:

wakora --key <TEAM_KEY>

The agent does not crash-loop on this: it idles and logs the reason, then starts once a decryptable identity is present.

A service is not being monitored​

The agent only activates definitions that match its facts. Check discovery:

  • Is the service actually running as a process the definition matches? A host running mod_php does not match a php-fpm definition, for example.
  • Is the port listening and owned by the expected process?

If a probe needs a credential and it is missing, the check fails with a clear message to run wakora secret set. If a probe needs a non-standard path, set a location override.

An APM capability shows "staged, awaiting activation"​

That is expected. The agent staged a change that needs a service reload and will not apply it for you. Run the exact command from the "action required" event (or click the console button) during a maintenance window. The agent detects the reload and flips the capability to active. See Never restart your services.

SNMP polling fails after a collector failover​

Secrets are never transferred between hosts. If you set the SNMP credential only on the primary collector, the backup cannot poll. Set the secret on every listed collector. See SNMP and network.

Metrics stopped, then came back with a gap filled​

That is the offline buffer working. When the connection drops, the agent spools metrics to disk and replays them on reconnect, so the gap backfills. A dead link is detected within about 30 seconds.

Checking resource usage​

The agent should sit under 1% CPU and well under 100 MB RAM. If it does not, capture the log and the output of wakora --version and open a support request.