When nothing is collecting
Silence has several causes and they look identical from a distance. This is the order to check them in, from most to least common. Every step has a page in the interface that answers it, so you should not need to read logs until the last one.
1. Does the target have an agent?
Targets → the target. If it says No agent is assigned, nothing is collecting it and nothing ever will. This is the most common cause of a target with no data and nothing visibly broken.
A target can be created before the agent that will reach it exists, so this is a normal state to pass through — it is only a problem when you forget. Assign one on Edit.
2. Is the agent reporting?
Fleet. A red dot means an active agent that has stopped checking in.
This matters more than it first appears: when an agent goes quiet, every alert that depended on it goes quiet too. An empty alert list is not evidence of health while an agent is silent, which is why your dashboard puts silent agents above the alert count and says so.
If an agent is silent:
systemctl status metricharbor-agent
journalctl -u metricharbor-agent -n 50
The usual causes are the host being down, egress HTTPS being blocked, or the service having been stopped and not re-enabled. The agent only ever makes outbound connections, so there is no inbound rule to check.
If the fleet page shows a buffer depth above zero, the opposite is happening: the agent is collecting fine but cannot reach us. The data is safe on its disk and will arrive when the link does. Nothing to fix on the agent.
3. Does the target have any checks?
The target page → Checks. An agent and a target are not enough; something has to be bound to collect. If it says No checks yet, so nothing is being collected, add one.
The collectors offered are the ones that target's agent has published and that can read that kind of target. If the list is empty, the agent has not published its manifests yet — give a newly installed one a minute.
4. What did the last run actually say?
The target page → Recent collections. This is the step people skip, and it usually contains the whole answer. Each run has an outcome and each error has a subject and a message, often including the command that fixes it.
Five outcomes, and they mean different things:
| Outcome | Meaning |
|---|---|
success |
Data arrived. |
partial |
Some data arrived and something also failed — nineteen disks read and one refused. Worth looking at; it is not a failure, and it is not fine. |
failed |
Nothing arrived and we know why. The error says. |
timeout |
It did not answer in time. A slow host and a broken one are different problems, which is why this is its own outcome. |
no data |
It ran, succeeded, and produced nothing. Usually a filter or a config that matches nothing. |
Common errors:
| Error | What to do |
|---|---|
authentication naming a credential |
The agent has no secret under that name. Run the cred add command from the credential's page. Check the name matches exactly. |
connection naming a host |
Listen address, firewall, or wrong port. Try it by hand from the agent host. |
permission_denied |
A grant is missing on the thing being monitored. See PostgreSQL or MySQL. |
config_invalid |
The check's configuration does not match what the agent's collector expects — usually after an agent upgrade changed a collector. Re-save the check. |
permission_denied mentioning --no-exec |
That agent was installed with script execution switched off and is refusing a script check. Intentional; see Installing the agent. |
5. Is the credential actually on the agent?
Credentials. A credential showing not on any agent means every target that needs it is collecting nothing. The page gives you the command.
This is the failure worth knowing about in advance, because it is the quietest: MetricHarbor
knows the credential's name but cannot verify its value, so a wrong password looks like a
missing one and both surface as an authentication error on the run rather than anything at
the credential level.
6. Check it from the host
Everything above can be answered from the agent host directly, which is faster when you are already logged in:
metricharbor-agent check
It verifies that the configuration parses, every credential resolves, every target is reachable, and every collector runs once — and prints the reason rather than a status code. Run it before you leave a host you have just set up.
A note on timing
The agent pulls its configuration; MetricHarbor never pushes to it. So a change you make in the interface — a new check, a changed interval, a Collect now — takes effect on the agent's next config poll, within about a minute. If something you just saved has not happened yet, that is usually why.