---
name: metrics_agent
lang: go
domain: infra
version: 0.1.0
description: "Agente de monitorización por nodo: recolecta métricas de host (CPU/RAM/swap/disco/red/temp/procesos) y las empuja a VictoriaMetrics en formato Prometheus con basic auth."
tags: [fleet-metrics, monitoring, daemon]
uses_functions:
  - collect_host_metrics_go_infra
  - format_prom_exposition_go_infra
  - push_prom_remote_go_infra
uses_types:
  - PromSample_go_infra
framework: ""
entry_point: "main.go"
dir_path: "projects/fleet_monitoring/apps/metrics_agent"
repo_url: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/metrics_agent"
---

# metrics_agent

Agente ligero que corre en cada equipo de la flota. En un bucle de intervalo fijo recolecta
métricas de sistema y las empuja al hub central (VictoriaMetrics en magnus). Es el componente
por nodo del project `fleet_monitoring`.

## Qué hace

Compone tres funciones del registry (grupo `fleet-metrics`), no reimplementa nada:

1. `collect_host_metrics_go_infra` — lee CPU (global + por core), memoria, swap, disco (uso +
   I/O), red (por interfaz), temperaturas (best-effort) y top procesos, devolviendo `[]PromSample`.
2. `format_prom_exposition_go_infra` — serializa los samples en texto formato Prometheus exposition.
3. `push_prom_remote_go_infra` — hace POST del texto al endpoint de ingesta con basic auth,
   añadiendo la label `instance=<node>` a todas las series vía `extra_label`.

## Por qué no lleva el tag `service`

Es un daemon, pero no encaja en el modelo `service:`/`services_monitor` (un endpoint HTTP con
health check monitorizado por SSH). El agente se replica en N nodos y su liveness la vigila el
propio sistema de monitorización: si un nodo deja de empujar, su serie `up` se vuelve stale y
salta la alerta. Por eso se etiqueta `daemon` y no `service`.

## Configuración

Config por archivo JSON (`-config`) con override por variables de entorno. Campos:

| campo / env | descripción | default |
|---|---|---|
| `node` / `FLEET_NODE` | valor de la label `instance` | hostname |
| `hub_url` / `FLEET_HUB_URL` | URL completa de ingesta (`…/api/v1/import/prometheus`) | — (obligatorio) |
| `user` / `FLEET_USER` | usuario basic-auth | "" |
| `pass` / `FLEET_PASS` | password basic-auth | "" |
| `interval_sec` / `FLEET_INTERVAL` | periodo de push en segundos | 15 |

## Ejemplo

```bash
# Build
cd projects/fleet_monitoring/apps/metrics_agent
go build -o metrics_agent .

# Push único de prueba (lee config + empuja una vez y sale)
FLEET_NODE=lucas \
FLEET_HUB_URL="https://metrics-dxaqj3ina6eqd5pjt85wkrrj.organic-machine.com/api/v1/import/prometheus" \
FLEET_USER=fleet \
FLEET_PASS="$(pass show fleet/ingest-pass | head -1)" \
./metrics_agent -once

# Bucle continuo con archivo de config
./metrics_agent -config /etc/fleet-agent/agent.json
```

## Cuando usarla

Despliégalo en cualquier máquina nueva que quieras ver en Grafana: copia el binario, escribe
`/etc/fleet-agent/agent.json` con su `node` y los secretos, instala el unit systemd y arranca.
No hay que tocar el hub central.

## Cross-compilación (para layla / Termux arm64)

gopsutil es Go puro, así que cross-compila sin CGO:

```bash
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o metrics_agent_arm64 .
```

## Gotchas

- `hub_url` debe ser la URL **completa** incluyendo `/api/v1/import/prometheus`.
- El push lleva la label `instance` vía `extra_label`; no la pongas tú en las métricas.
- Las temperaturas son best-effort: en VPS y en Android/Termux puede no haber sensores y el
  grupo `node_temp_celsius` simplemente se omite.
- El binario importa el paquete `fn-registry/functions/infra` completo (vía `replace` al
  registry), por lo que arrastra las dependencias de ese paquete. El linker elimina el código
  no usado, pero el árbol de compilación es grande.