---
name: collect_host_metrics
kind: function
lang: go
domain: infra
version: "1.0.0"
purity: impure
signature: "func CollectHostMetrics() ([]PromSample, error)"
description: "Recolecta metricas del host actual (uptime, load, CPU global y por nucleo, memoria, swap, disco por particion fisica e I/O por dispositivo, red por interfaz, temperaturas best-effort y procesos: total + top 5 por CPU) y las devuelve como slice de PromSample con nombres estilo node_exporter simplificados. Robusta: cada grupo de colector tiene manejo de error local; si un colector secundario falla se omite ese grupo sin abortar. Funciona en Linux amd64 y Android/Termux (linux arm64)."
tags: [prometheus, metrics, node-exporter, gopsutil, fleet-metrics, infra, monitoring, host]
uses_functions: []
uses_types: ["PromSample_go_infra"]
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["fmt", "sort", "strconv", "time", "github.com/shirou/gopsutil/v4/cpu", "github.com/shirou/gopsutil/v4/disk", "github.com/shirou/gopsutil/v4/host", "github.com/shirou/gopsutil/v4/load", "github.com/shirou/gopsutil/v4/mem", "github.com/shirou/gopsutil/v4/net", "github.com/shirou/gopsutil/v4/process", "github.com/shirou/gopsutil/v4/sensors"]
params: []
output: "slice de PromSample con las metricas del host. Cada sample lleva nombre estilo node_exporter (node_cpu_percent, node_disk_used_bytes{mount}, etc.) y sus labels. Error solo si falla el uptime de host (informacion basica imprescindible)."
tested: true
tests:
  - "TestCollectHostMetrics_ReturnsBasics"
  - "TestCollectHostMetrics_SamplesWellFormed"
test_file_path: "functions/infra/collect_host_metrics_test.go"
file_path: "functions/infra/collect_host_metrics.go"
---

## Ejemplo

```go
samples, err := CollectHostMetrics()
if err != nil {
    log.Fatal(err)
}
// Formatear a exposition Prometheus y enviar a VictoriaMetrics:
body := FormatPromExposition(samples, time.Now().UnixMilli())
err = PushPromRemote(
    "https://metrics-xxxx.organic-machine.com/api/v1/import/prometheus",
    "user", "pass",
    body,
    map[string]string{"instance": "lucas-pc"},
)
```

## Cuando usarla

Cuando necesites un snapshot completo de salud del host en formato Prometheus
para hacer push a un backend remoto (VictoriaMetrics, Mimir, etc.) en lugar de
exponer un endpoint /metrics para scraping. Es el colector base del capability
group `fleet-metrics`: combinala con `format_prom_exposition_go_infra` y
`push_prom_remote_go_infra` para un agente de monitorizacion push estilo
node_exporter. Llamala periodicamente (cron, timer, loop) en cada nodo de la
flota.

## Gotchas

- **Bloquea ~400ms**: hace dos llamadas a `cpu.Percent` con intervalo de 200ms
  cada una (global + por nucleo). No la llames en hot paths ni con periodo < 1s.
- **Temperaturas best-effort**: usa `sensors.SensorsTemperatures` (movido del
  paquete `host` al paquete `sensors` en gopsutil v4). Si no hay sensores
  (tipico en Android/Termux y muchos VPS) el grupo `node_temp_celsius` se omite
  sin error.
- **Particiones pseudo ignoradas**: tmpfs, devtmpfs, overlay, squashfs, proc,
  sysfs y similares se filtran. Solo reporta particiones de almacenamiento real.
- **Loopback excluido**: la interfaz `lo` no genera metricas de red.
- **CPU por proceso necesita dos lecturas**: `CPUPercent()` de gopsutil sobre un
  proceso recien obtenido puede devolver un valor calculado desde el arranque
  del proceso, no un delta. Util para ranking relativo del top 5, no como medida
  instantanea precisa.
- **No incluye la label `instance`**: los samples no llevan instance; esa la
  añade `push_prom_remote_go_infra` via extra_label en el push.
- **Permisos**: algunos contadores (procesos de otros usuarios, ciertos sensores)
  pueden requerir privilegios; los fallos parciales se omiten silenciosamente.
