victoriametrics-agent¶

victoriametrics-agent is the set of collectors that read a host's metrics and logs and send them to VictoriaMetrics. No host lists it, and no stack includes it. See Not in the plan.

The per-VM role belongs to system-agent. It carries the same collectors, reads Traefik's access log as well, and adds container DNS and a Dozzle agent.

To run it on a host of your own, see Applications (ap01).

What it runs¶

vlagent
vmagent
vector
cadvisor
socket-proxy

Service	Does
`vmagent`	Scrapes itself, vlagent, cadvisor, and the host's Node Exporter every 10 seconds, and forwards the metrics
`vlagent`	Receives logs from vector and forwards them
`vector`	Reads container logs, the host's journal, `.log` files under `/var/log`, and syslog on port 5140
`cadvisor`	Reports what each container uses of the CPU, memory, disk, and network
`socket-proxy`	Gives vector a filtered view of the Docker socket

The project is victoriametrics, so the containers are named victoriametrics- and the service, such as victoriametrics-vmagent.

vmagent and vlagent each keep up to 100 MB of unsent data on disk, so a short outage of the receiving end loses nothing.

vector and cadvisor run in the host's user namespace. The journal and the files under /var/log cannot be read from inside the remapped one. See Why 100000 and 101000.

vmagent reads the Node Exporter's certificate and scrape password from /etc/node-exporter on the host. The host's NixOS configuration puts both there, and the password never reaches Komodo. See system-agent.

Values it reads¶

Key	Reads	Kind	Described under
`VMAUTH_USER`	`GLOBAL_VMAUTH_USER`	Variable	Telemetry
`VMAUTH_PASS`	`GLOBAL_VMAUTH_PASS`	Secret	Telemetry
`VMAUTH_HOST`	`GLOBAL_VMAUTH_HOST`	Variable	Telemetry

It also reads the 19 operational defaults, as every stack does.

Both agents send to https:// and the value of VMAUTH_HOST, and sign in with the user and password. The three are staged on VictoriaMetrics (ci01).

What the host needs¶

The project is victoriametrics, so the stack's folders sit under /opt/docker/volumes/victoriametrics and /opt/docker/logs/victoriametrics. Both are mode 0750, owned by the admin account with group 101000.

Folder	Owner	Mode
`/opt/docker/volumes/victoriametrics/vlagent-data`	`101000:101000`	Default
`/opt/docker/volumes/victoriametrics/vmagent-data`	`101000:101000`	Default
`/opt/docker/volumes/victoriametrics/vector-data`	`101000:101000`	Default

Port	Allowed from	Comment
`5140/tcp`	The internal subnet	Vector syslog
`5140/udp`	The internal subnet	Vector syslog

The host's NixOS configuration creates the folders and opens the ports when the host is deployed. It reads them from the host's file in the private repo, nixos/hosts/<host>.json, which nixos-sync.yml writes from the stack's setup.yaml. See Host layout.

The stack has no route, so it needs no Traefik on the host.

Its vector publishes port 5140 on the host, and so does the one in system-agent. Two stacks cannot both hold the port on one host.

Verify¶

On the host, list the Stack's containers. Komodo names the Compose project after the Stack, not after PROJECT_NAME:

docker compose -p victoriametrics-agent-<host> ps

Every container shows healthy in the STATUS column. The checks on vmagent and vlagent ask each agent's own health endpoint, so healthy means the agent is up. It does not mean the receiving end accepted anything.

To see that, look for the host's metrics and logs in Grafana. See victoriametrics-server.