Grafana Alloy sur VPS : installer et migrer depuis Promtail

Pourquoi remplacer Promtail par Alloy maintenant

Ce qu'un agent unique change sur votre serveur

• Un seul service à surveiller — logs et métriques passent par le même processus alloy, avec un seul journal à lire en cas de panne.
• Des mises à jour qui arrivent encore — Alloy est publié dans les dépôts apt et rpm de Grafana : un apt upgrade le maintient à jour comme le reste du système.
• Une migration outillée — la commande alloy convert traduit une configuration Promtail existante et produit un rapport de ce qu'elle n'a pas su convertir.
• Les métriques système intégrées — le composant prometheus.exporter.unix remplace node_exporter sans binaire supplémentaire ni port à ouvrir.
• Une interface de débogage locale — l'UI sur le port 12345 montre le graphe des composants et leurs valeurs, accessible par tunnel SSH.
• Une sortie vers votre pile ou vers Grafana Cloud — le même fichier envoie vers un Loki auto-hébergé ou vers un service managé, en changeant une URL.

Prérequis chiffrés pour Alloy sur un VPS

Installer Alloy et brancher logs et métriques

1. 01

   Ajouter le dépôt Grafana sur Debian ou 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

   Ou l'installer sur AlmaLinux et Rocky Linux

   Importez la clé avec wget -q -O gpg.key https://rpm.grafana.com/gpg.key puis sudo rpm --import gpg.key. Créez /etc/yum.repos.d/grafana.repo avec baseurl=https://rpm.grafana.com, repo_gpgcheck=1, gpgcheck=1 et enabled=1, comme l'indique la page d'installation Linux d'Alloy, puis lancez sudo dnf install alloy.

3. 03

   Démarrer le service et vérifier son utilisateur

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

   La dernière commande doit afficher User=alloy. Le paquet ne fixe pas de Group= : les droits de lecture viennent donc des groupes secondaires de cet utilisateur, point essentiel pour la suite.

4. 04

   Déclarer la destination des logs

   Ouvrez /etc/alloy/config.alloy et ajoutez le point d'envoi vers Loki :

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

   Remplacez l'adresse par celle de votre Loki. Si elle est distante, passez par HTTPS et un bloc basic_auth.

5. 05

   Collecter journald et les fichiers de logs

   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]
}

   Par défaut, la source journal lit /var/log/journal et /run/log/journal, et ne remonte que sept heures en arrière au premier démarrage.

6. 06

   Collecter les métriques système

   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 tournait déjà sur la machine, arrêtez-le après la bascule pour ne pas collecter deux fois les mêmes séries.

7. 07

   Valider avant de recharger

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

   Une erreur de syntaxe ou un composant mal référencé est signalé par validate avant que le service ne charge la configuration.

8. 08

   Accorder les droits de lecture

   id alloy doit lister les groupes adm et systemd-journal. Le paquet les ajoute quand ils existent ; après une installation par binaire ou un groupe supprimé, rétablissez-les avec sudo usermod -aG adm,systemd-journal alloy puis sudo systemctl restart alloy. Pour un dossier applicatif détenu par un autre utilisateur, la documentation préfère une ACL à un groupe de plus : sudo setfacl -R -m u:alloy:rx /var/log/monapp et sudo setfacl -R -d -m u:alloy:rx /var/log/monapp.

9. 09

   Vérifier de bout en bout, puis brancher vos tableaux de bord

   Écrivez une ligne témoin avec logger -t alloy-test "ligne de test alloy", puis cherchez-la dans Grafana, onglet Explore, avec la requête {job="systemd-journal"} |= "ligne de test alloy". Côté métriques, la requête node_load1 doit renvoyer une série pour votre VPS. Les deux répondent : reprenez les tableaux de bord de notre guide Grafana et Prometheus, qui lisent les mêmes séries node_*.

Alloy et Docker : lire les conteneurs sans tout ouvrir

Migrer depuis Promtail : le vrai risque, ce sont les positions

Migrer une configuration Promtail sans perte ni doublon

1. 10

   Repérer la configuration et le fichier de positions

   Ouvrez la configuration de Promtail, souvent /etc/promtail/config.yml, et notez la valeur de positions.filename. Dans une installation Docker Compose, ce fichier vit dans un volume : relevez son chemin réel sur l'hôte.

2. 11

   Convertir avec un rapport

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

   Lisez le rapport avant tout. L'option --bypass-errors force une conversion partielle, mais la documentation prévient que le comportement peut alors différer de l'original.

3. 12

   Vérifier que l'utilisateur alloy lit l'ancien fichier

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

   Adaptez le chemin à celui relevé plus haut. Si la seconde commande échoue, copiez le fichier dans un dossier lisible par alloy et corrigez le chemin dans la configuration convertie.

4. 13

   Arrêter Promtail avant de démarrer Alloy

   sudo systemctl stop promtail, ou docker compose stop promtail pour une pile en conteneurs. Promtail écrit alors ses dernières positions, et aucune ligne ne part en double pendant la bascule.

5. 14

   Basculer la configuration

   Reportez les blocs convertis dans /etc/alloy/config.alloy, lancez sudo alloy validate /etc/alloy/config.alloy, puis sudo systemctl restart alloy. Contrôlez aussitôt sudo journalctl -u alloy | grep -i positions : aucune ligne error reading legacy positions file ne doit apparaître.

6. 15

   Contrôler une semaine, puis désinstaller

   Comparez le volume de logs dans Grafana avant et après la bascule, et suivez le compteur loki_write_sent_entries_total d'Alloy. Gardez la configuration Promtail quelques jours, puis sudo systemctl disable promtail et retirez le paquet ou le service Compose.

Promtail et Alloy, côte à côte

Faites défiler le tableau

Configuration après installation : UI, secrets et stockage

Dépannage : les erreurs qu'Alloy ne crie pas

Messages d'erreur et remèdes

• La source journal démarre, mais aucune ligne n'arrive — la documentation de loki.source.journal le dit : sans les groupes adm et systemd-journal, le composant démarre sans erreur et ne collecte rien. Corrigez avec sudo usermod -aG adm,systemd-journal alloy, puis redémarrez le service, car un groupe ajouté n'est pris en compte qu'au lancement suivant.
• failed to tail the file: open /var/log/…: permission denied — le fichier existe mais alloy ne peut pas le lire. Accordez une ACL sur le dossier avec setfacl -R -m u:alloy:rx et sa variante -d pour les fichiers créés ensuite par la rotation.
• Aucun message, aucune ligne pour tout un dossier — l'issue grafana/alloy #6542 décrit des logs jamais transmis sans la moindre erreur. Un mainteneur y confirme qu'un fichier illisible est journalisé, mais qu'un dossier inaccessible ne l'est pas. Testez avec sudo -u alloy ls /var/log/monapp.
• error reading legacy positions file … permission denied — Alloy n'a pas lu les positions de Promtail et peut tout renvoyer depuis le début (issue #5493). Arrêtez le service, rendez le fichier lisible pour alloy, puis relancez.
• failed to identify the read-write layer ID … mount-id: permission denied — erreur du composant cAdvisor sous systemd (issue #4068). Le groupe docker n'y suffit pas ; des utilisateurs rapportent qu'un drop-in avec AmbientCapabilities=CAP_DAC_READ_SEARCH et CapabilityBoundingSet=CAP_DAC_READ_SEARCH règle le cas sans passer le service en root. C'est un contournement communautaire, à tester avant de le généraliser.
• L'UI est verte, mais Grafana reste vide — vérifiez loki_write_sent_entries_total et la ligne de test écrite par logger. Si le compteur stagne, la panne est en amont, du côté de la source.

Un agent tenu à jour sur un serveur qui vous appartient