Grafana Alloy en un VPS: instalar y migrar desde Promtail

Por qué sustituir Promtail por Alloy ahora

Lo que cambia un agente único en su servidor

• Un solo servicio que vigilar — logs y métricas pasan por el mismo proceso alloy, con un único registro que leer cuando algo falla.
• Actualizaciones que siguen llegando — Alloy se publica en los repositorios apt y rpm de Grafana: un apt upgrade lo mantiene al día como el resto del sistema.
• Una migración con herramientas — el comando alloy convert traduce una configuración de Promtail existente y genera un informe de lo que no ha podido convertir.
• Métricas del sistema integradas — el componente prometheus.exporter.unix sustituye a node_exporter sin binario adicional ni puerto que abrir.
• Una interfaz de depuración local — la UI en el puerto 12345 muestra el grafo de componentes y sus valores, accesible mediante un túnel SSH.
• Salida hacia su propia pila o hacia Grafana Cloud — el mismo archivo envía a un Loki autoalojado o a un servicio gestionado cambiando una URL.

Requisitos cuantificados para Alloy en un VPS

Instalar Alloy y conectar logs y métricas

1. 01

   Añadir el repositorio de Grafana en Debian o Ubuntu

   sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install alloy

2. 02

   O instalarlo en AlmaLinux y Rocky Linux

   Importe la clave con wget -q -O gpg.key https://rpm.grafana.com/gpg.key y después sudo rpm --import gpg.key. Cree /etc/yum.repos.d/grafana.repo con baseurl=https://rpm.grafana.com, repo_gpgcheck=1, gpgcheck=1 y enabled=1, como indica la página de instalación de Alloy para Linux, y ejecute sudo dnf install alloy.

3. 03

   Iniciar el servicio y comprobar su usuario

   sudo systemctl enable --now alloy
sudo systemctl status alloy
systemctl cat alloy | grep User

   El último comando debe mostrar User=alloy. El paquete no fija ningún Group=: los permisos de lectura vienen, por tanto, de los grupos secundarios de ese usuario, un punto clave para lo que sigue.

4. 04

   Declarar el destino de los logs

   Abra /etc/alloy/config.alloy y añada el envío hacia Loki:

   loki.write "default" {
endpoint {
url = "http://127.0.0.1:3100/loki/api/v1/push"
}
}

   Sustituya la dirección por la de su Loki. Si es remoto, use HTTPS y un bloque basic_auth.

5. 05

   Recoger journald y los archivos de log

   loki.source.journal "system" {
forward_to = [loki.write.default.receiver]
labels = {"job" = "systemd-journal"}
}
local.file_match "nginx" {
path_targets = [{"__path__" = "/var/log/nginx/*.log", "job" = "nginx"}]
}
loki.source.file "nginx" {
targets = local.file_match.nginx.targets
forward_to = [loki.write.default.receiver]
}

   Por defecto, la fuente journal lee /var/log/journal y /run/log/journal, y solo retrocede siete horas en el primer arranque.

6. 06

   Recoger las métricas del sistema

   prometheus.exporter.unix "node" { }
prometheus.scrape "node" {
targets = prometheus.exporter.unix.node.targets
forward_to = [prometheus.remote_write.default.receiver]
}
prometheus.remote_write "default" {
endpoint {
url = "http://127.0.0.1:9090/api/v1/write"
}
}

   Si node_exporter ya funcionaba en la máquina, deténgalo tras el cambio para no recoger dos veces las mismas series.

7. 07

   Validar antes de recargar

   sudo alloy validate /etc/alloy/config.alloy
sudo systemctl reload alloy
sudo journalctl -u alloy -f

   validate señala un error de sintaxis o un componente mal referenciado antes de que el servicio cargue la configuración.

8. 08

   Conceder permisos de lectura

   id alloy debe listar los grupos adm y systemd-journal. El paquete los añade cuando existen; tras una instalación por binario o un grupo eliminado, restablézcalos con sudo usermod -aG adm,systemd-journal alloy y después sudo systemctl restart alloy. Para una carpeta de aplicación propiedad de otro usuario, la documentación prefiere una ACL a un grupo más: sudo setfacl -R -m u:alloy:rx /var/log/monapp y sudo setfacl -R -d -m u:alloy:rx /var/log/monapp.

9. 09

   Comprobar de extremo a extremo y conectar sus paneles

   Escriba una línea de prueba con logger -t alloy-test "ligne de test alloy" y búsquela en Grafana, pestaña Explore, con la consulta {job="systemd-journal"} |= "ligne de test alloy". En cuanto a métricas, la consulta node_load1 debe devolver una serie para su VPS. Si ambas responden, reutilice los paneles de nuestra guía de Grafana y Prometheus, que leen las mismas series node_*.

Alloy y Docker: leer los contenedores sin abrirlo todo

Migrar desde Promtail: el riesgo real son las posiciones

Migrar una configuración de Promtail sin pérdidas ni duplicados

1. 10

   Localizar la configuración y el archivo de posiciones

   Abra la configuración de Promtail, a menudo /etc/promtail/config.yml, y anote el valor de positions.filename. En una instalación con Docker Compose, ese archivo vive en un volumen: anote su ruta real en el host.

2. 11

   Convertir con un informe

   alloy convert --source-format=promtail --report=/tmp/promtail-report.txt --output=/tmp/promtail.alloy /etc/promtail/config.yml

   Lea el informe antes que nada. La opción --bypass-errors fuerza una conversión parcial, pero la documentación advierte de que el comportamiento puede diferir entonces del original.

3. 12

   Comprobar que el usuario alloy lee el archivo antiguo

   grep legacy_positions_file /tmp/promtail.alloy
sudo -u alloy cat /var/lib/promtail/positions.yaml

   Adapte la ruta a la que anotó antes. Si el segundo comando falla, copie el archivo en una carpeta legible por alloy y corrija la ruta en la configuración convertida.

4. 13

   Detener Promtail antes de iniciar Alloy

   sudo systemctl stop promtail, o docker compose stop promtail para una pila en contenedores. Promtail escribe entonces sus últimas posiciones y ninguna línea se envía dos veces durante el cambio.

5. 14

   Cambiar la configuración

   Lleve los bloques convertidos a /etc/alloy/config.alloy, ejecute sudo alloy validate /etc/alloy/config.alloy y después sudo systemctl restart alloy. Compruebe enseguida sudo journalctl -u alloy | grep -i positions: no debe aparecer ninguna línea error reading legacy positions file.

6. 15

   Vigilar una semana y desinstalar

   Compare el volumen de logs en Grafana antes y después del cambio, y siga el contador loki_write_sent_entries_total de Alloy. Conserve la configuración de Promtail unos días, luego sudo systemctl disable promtail y retire el paquete o el servicio de Compose.

Promtail y Alloy, frente a frente

Desplace la tabla

Configuración tras la instalación: UI, secretos y almacenamiento

Resolución de problemas: los errores que Alloy no grita

Mensajes de error y soluciones

• La fuente journal arranca, pero no llega ninguna línea — la documentación de loki.source.journal lo dice: sin los grupos adm y systemd-journal, el componente arranca sin error y no recoge nada. Corríjalo con sudo usermod -aG adm,systemd-journal alloy y reinicie el servicio, porque un grupo añadido solo se aplica en el siguiente arranque.
• failed to tail the file: open /var/log/…: permission denied — el archivo existe, pero alloy no puede leerlo. Conceda una ACL en la carpeta con setfacl -R -m u:alloy:rx y su variante -d para los archivos que cree después la rotación.
• Ningún mensaje, ninguna línea de toda una carpeta — la issue grafana/alloy #6542 describe logs que nunca se envían sin el menor error. Un mantenedor confirma allí que un archivo ilegible se registra, pero una carpeta inaccesible no. Pruebe con sudo -u alloy ls /var/log/monapp.
• error reading legacy positions file … permission denied — Alloy no leyó las posiciones de Promtail y puede reenviarlo todo desde el principio (issue #5493). Detenga el servicio, haga el archivo legible para alloy y vuelva a iniciarlo.
• failed to identify the read-write layer ID … mount-id: permission denied — error del componente cAdvisor bajo systemd (issue #4068). El grupo docker no basta; algunos usuarios indican que un drop-in con AmbientCapabilities=CAP_DAC_READ_SEARCH y CapabilityBoundingSet=CAP_DAC_READ_SEARCH lo resuelve sin ejecutar el servicio como root. Es una solución de la comunidad, que conviene probar antes de generalizarla.
• La UI está en verde, pero Grafana sigue vacío — compruebe loki_write_sent_entries_total y la línea de prueba escrita con logger. Si el contador no avanza, el fallo está antes, en la fuente.

Un agente al día en un servidor que le pertenece