MetricHarborDocs

Getting started

From a fresh host to a graph on screen. About fifteen minutes, most of it waiting for a poll.

This walks through monitoring one machine and one database on it. Everything here generalises: the same five steps apply whether the target is a Linux host, a database, an SNMP device or a TLS certificate.

The shape of it, because it helps to know where you are going:

  create an enrolment key   ─┐
  install the agent          ├─ on the host, once
  enrol it                  ─┘
  declare a credential      ─── in MetricHarbor: a name and a shape
  supply the secret         ─── on the host: the value, which we never see
  create a target           ─── what to monitor, and which agent reaches it
  add a check               ─── what to collect from it

The split in the middle is the part that is unusual and the part worth understanding. MetricHarbor stores the name of a credential; the secret itself only ever exists on your machine. See Credentials for why.

Commands here are written to run as root. If you work through sudo, add the prefix yourself. They are not written with sudo because it is not a dependency of the agent and is not installed by default on a minimal Debian — a copied command would fail with sudo: command not found on exactly the kind of host people install agents on. Where something must run as the service account, these pages use runuser -u metricharbor -- …, from util-linux, which is present everywhere.

1. Create an enrolment key

In MetricHarbor: Fleet → Enrolment keys → Create a key.

Give it a label describing the rollout — first-host, dc1-rollout — because that label is how you will later recognise which key let an agent in, and therefore which key to revoke if one turns up that you do not recognise.

Set a maximum enrolments and an expiry if you know them. A key that stops working once the job is done cannot leak later; the dangerous key is the one still pinned in a chat channel two years from now.

The key is shown once, immediately after creation, along with the exact command to run. Copy it now — MetricHarbor stores only a hash of it, so there is no way to show it again.

2. Install the agent

On the host you want to monitor:

# Debian, Ubuntu
curl -fsSL https://apt.metricharbor.io/metricharbor.asc \
  | gpg --dearmor -o /usr/share/keyrings/metricharbor.gpg
echo "deb [signed-by=/usr/share/keyrings/metricharbor.gpg] https://apt.metricharbor.io stable main" \
  > /etc/apt/sources.list.d/metricharbor.list
apt update && apt install metricharbor-agent

# RHEL, Rocky, Alma, CentOS Stream, Fedora
cat > /etc/yum.repos.d/metricharbor.repo <<'EOF'
[metricharbor]
name=MetricHarbor
baseurl=https://rpm.metricharbor.io/stable/$basearch
enabled=1
repo_gpgcheck=1
gpgcheck=0
gpgkey=https://rpm.metricharbor.io/metricharbor.asc
EOF
dnf install metricharbor-agent

Nothing starts yet, and that is deliberate — an agent that has not enrolled has nothing to collect, so starting it would only produce a service that restarts every ten seconds. See Installing the agent for tarball and container installs, and for what the service is allowed to do.

3. Enrol

The key page gives you this command with your key already filled in. Copy it from there rather than typing it:

metricharbor-agent enrol --url https://api.metricharbor.io --key mhk_… --name centos-tst          # whatever you will recognise in the fleet view

If it answers enrol: agent token rejected, MetricHarbor did not accept the key. Check that it was copied whole, and that Fleet → Enrolment keys still shows it as usable: a key can be revoked, expire, or reach its maximum number of enrolments.

You should see:

Enrolled as "your-hostname" (active).
Next: metricharbor-agent check

Then start it:

systemctl enable --now metricharbor-agent

Check it worked: the agent appears under Fleet within a few seconds, with a green dot, its version, its platform, and its last known address. If it does not, see When nothing is collecting.

At this point the agent is running and reporting, and collecting nothing. That is expected — you have not told it what to look at.

4. Declare a credential

Almost everything worth monitoring needs to authenticate. In MetricHarbor: Credentials → Declare credential, pick the kind, and give it a name you are willing to retype — mysql-monitor, ssh-monitor.

You are naming a credential here, not entering one. There is nowhere on this page to type a password, by design.

5. Supply the secret on the host

The credential's page now shows the exact command. On the host:

runuser -u metricharbor -- metricharbor-agent cred add mysql-monitor --type database_password

You are prompted for the username and password. A secret is never a command-line argument — /proc/<pid>/cmdline is world-readable and shell history is a file on disk — so there is no --password= form of this.

Check it worked: the credential's page changes from not on any agent to held, naming the agent, within one heartbeat. That state is the thing that stops a target silently never collecting because nobody ever supplied its secret.

6. Create a target

Targets → Add target, and pick what it is. The form is built from that kind's own requirements, so a PostgreSQL target asks for a database name and a Linux host does not.

Two fields matter beyond the obvious ones:

  • Collected by — the agent that can reach this. Leave it unassigned and nothing will collect it, which is the single most common reason for a target with no data and nothing visibly broken.
  • Labels — env=prod, team=platform. Optional now, but labels are how you scope alert rules and slice graphs later, and adding them retrospectively across fifty targets is tedious.

7. Add a check

On the target page: Add a check.

The collectors offered are the ones that target's agent has published and that can read this kind of target — so the list is short and everything in it will work. Collectors that do not apply are listed separately with what they do apply to, so you can tell "there is no such collector" from "it does not apply here".

Most checks need no configuration. Set the interval if the default does not suit; shorter means more data and more load on the thing being measured.

8. Wait one poll

The agent pulls its configuration; MetricHarbor never pushes to it. So your new check takes effect on the agent's next config poll — within about a minute.

This is the step people misread as a failure. If something you just saved has not happened yet, it is almost always this.

9. See the data

On the target page:

  • Checks shows the collector, its health, when it last ran and when it runs next.
  • Recent collections shows each run's outcome. success with a sample count is what you want.
  • Latest readings shows one row per label set — one per disk, per schema, per pod. This is the whole point of the data model: averaging them into one number is how a single full filesystem hides among eleven healthy ones.
  • Graphs needs a few polls before a line has any shape to it.

When it does not work

Four things, in the order they actually go wrong:

  1. No agent assigned to the target. The target page says so plainly.
  2. The agent is not reporting. The Fleet page shows a red dot. Remember that when an agent goes quiet, every alert that depended on it goes quiet too.
  3. No check bound. An agent and a target are not enough.
  4. The check ran and failed. Recent collections has the error, with a subject and usually the command that fixes it. This is the step people skip, and it usually contains the whole answer.

When nothing is collecting goes through each in detail.

Next