No Metrics Showing

If your agent shows as Connected in the dashboard but no metrics appear (no containers, no CPU/memory data), work through these checks.

Check 1: Wait 30 seconds

The agent pushes metrics every 15 seconds. After first connecting, it can take up to 30 seconds for the first metrics to appear in the dashboard. If you just deployed the agent, wait a moment and refresh.

Check 2: Check agent push logs

Look for push failure messages in the agent logs:

Docker:

docker logs kubewatch-agent --tail=20

Kubernetes:

kubectl logs -n kubewatch -l app=kubewatch-agent --tail=20

The agent doesn't log a line for each successful push, only failures, so no output at all over a minute or two of --tail -f is itself a good sign, not a sign you're missing something.

Problem indicators:

push error: <details>, buffering snapshot

A push error line means the push itself failed (network issue, gateway down, or an auth problem); the snapshot is buffered and retried, so a single failure shouldn't lose data, but a continuous stream of them means metrics are not making it in. If the agent won't even start in Docker mode, look for a fatal line instead:

docker collector init failed: docker socket not found at /var/run/docker.sock: permission denied

That's a startup failure, not a silent one: the container exits and restarts in a loop (docker ps shows it repeatedly restarting) rather than sitting there connected with no data, so if your agent shows Connected in the dashboard, this specific error isn't your cause; skip to Check 4 or Check 5 instead.

Check 3: Docker socket permissions

If your agent won't start in Docker mode and its logs show the docker socket not found error above with permission denied, the agent container doesn't have access to /var/run/docker.sock.

Verify the socket exists and has group-readable permissions:

ls -la /var/run/docker.sock
# Expected: srw-rw---- 1 root docker ...

If you're running the agent with a non-root user, add it to the docker group, or run the container with --user root.

For Docker Compose, ensure the volume mount is present:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Check 4: Kubernetes RBAC (Kubernetes agents only)

For Kubernetes agents, verify the ClusterRole and ClusterRoleBinding were created by the Helm chart:

kubectl get clusterrole kubewatch-agent
kubectl get clusterrolebinding kubewatch-agent

If they don't exist, the agent can't read pod and node data from the Kubernetes API. Reinstall the Helm chart:

helm upgrade --install kubewatch-agent \
  https://raw.githubusercontent.com/lloyd-theophilus/kubewatch-releases/main/kubewatch-agent.tgz \
  --namespace kubewatch \
  --set apiKey=YOUR_API_KEY

Check 5: Correct agent selected in dashboard

Make sure you're viewing the right agent in the dashboard. Check the agent selector in the top bar. If it's set to a different agent, you won't see metrics from your newly deployed agent, so set it to All agents or select the specific agent by name.

Check 6: Ingestion service health (self-hosted only)

If you're running self-hosted KubeWatch and push requests return 502, the ingestion service may be down:

cd ~/kubewatch-erp
docker compose ps ingestion
docker compose logs ingestion --tail=30

Restart if needed:

docker compose restart ingestion

Check 7: Database connection (self-hosted only)

If the ingestion service is crashing on startup, it may be unable to connect to the database:

docker compose logs ingestion | grep -i "database\|postgres\|connection"

Verify the PostgreSQL container is healthy:

docker compose ps postgres