River vs HCL

2. River vs HCL #

Ce que la syntaxe Alloy (ex-River) emprunte à HCL, ce qui l'en distingue et pourquoi elle est évaluée en continu.

De River à la « syntaxe Alloy » #

Le langage s'appelait River dans Grafana Agent Flow. Depuis Grafana Alloy 1.0, Grafana parle simplement de syntaxe de configuration Alloy et les fichiers portent l'extension .alloy. Le mot « River » reste très présent dans la documentation ancienne, les articles et les recherches : c'est le même langage.

Sa syntaxe est volontairement proche du HCL (HashiCorp Configuration Language) de Terraform : un ingénieur qui écrit du Terraform lit une configuration Alloy sans effort. Mais les deux langages ne servent pas le même but. HCL décrit un état cible à atteindre une fois ; Alloy décrit un pipeline de télémétrie qui tourne en permanence.

Ce que la syntaxe Alloy emprunte à HCL #

Dans les deux langages, une référence crée une dépendance : le composant qui lit une valeur dépend du composant qui l'exporte. C'est ce qui permet de construire le graphe sans indiquer d'ordre d'exécution.

Ce qui les distingue #

Exemple côte à côte #

Le même besoin, une valeur qui dépend de la région, exprimé dans les deux langages :

# Terraform (HCL) : évalué une fois, au plan / apply
variable "region" {
  default = "eu-west-3"
}

locals {
  bucket_name = "logs-${var.region}"   # interpolation ${...}
}

resource "aws_s3_bucket" "logs" {
  count  = 2                           # méta-argument
  bucket = "${local.bucket_name}-${count.index}"
}

// Alloy : réévalué en continu, à chaque changement d'une valeur exportée
local.file "region" {
  filename = "/etc/alloy/region"
}

prometheus.remote_write "mimir" {
  endpoint {
    // pas d'interpolation : string.format() ou l'opérateur +
    url = string.format("https://mimir-%s.example.com/api/v1/push", local.file.region.content)
  }
  external_labels = {
    region = local.file.region.content,
    host   = constants.hostname,
  }
}

Côté Terraform, si la région change, il faut relancer terraform apply. Côté Alloy, il suffit de modifier le fichier /etc/alloy/region : local.file le relit, exporte la nouvelle valeur, et prometheus.remote_write se reconfigure tout seul.

L'évaluation continue : le graphe de composants #

Au démarrage, Alloy construit un graphe orienté acyclique (DAG) à partir des références entre composants. Chaque fois qu'un composant exporte une nouvelle valeur, seuls ses dépendants sont réévalués. C'est indispensable pour l'observabilité, où les cibles apparaissent et disparaissent en permanence (pods Kubernetes, instances cloud).

// 1. Découverte : la liste des pods change en permanence
discovery.kubernetes "pods" {
  role = "pod"
}

// 2. Filtrage : ne garder que les pods annotés
discovery.relabel "annotated" {
  targets = discovery.kubernetes.pods.targets
  rule {
    source_labels = ["__meta_kubernetes_pod_annotation_prometheus_io_scrape"]
    regex         = "true"
    action        = "keep"
  }
}

// 3. Collecte : ses cibles suivent automatiquement les étapes 1 et 2
prometheus.scrape "pods" {
  targets    = discovery.relabel.annotated.output
  forward_to = [prometheus.remote_write.mimir.receiver]
}

Quand un pod est créé, discovery.kubernetes exporte une nouvelle liste ; discovery.relabel est réévalué, puis prometheus.scrape reçoit ses nouvelles cibles. Aucun redémarrage, aucune action manuelle. L'interface d'Alloy (port 12345) affiche ce graphe et l'état de chaque composant.

Piège classique : une référence circulaire (A lit B qui lit A) est refusée au chargement. Le message d'erreur indique les composants concernés ; découpez alors le traitement en deux composants distincts.

Outils et commandes à connaître #

# Vérifier et formater la syntaxe (comme terraform fmt)
alloy fmt config.alloy
alloy fmt --write config.alloy

# Lancer Alloy avec l'interface de débogage (graphe des composants)
alloy run config.alloy --server.http.listen-addr=0.0.0.0:12345

# Recharger la configuration sans redémarrer
curl -X POST http://localhost:12345/-/reload

# Convertir une configuration existante vers la syntaxe Alloy
alloy convert --source-format=prometheus --output=config.alloy prometheus.yml
alloy convert --source-format=promtail   --output=logs.alloy   promtail.yml

Migration : alloy convert accepte aussi --source-format=static (Grafana Agent Static) et --source-format=otelcol (OpenTelemetry Collector). Relisez toujours le résultat : les commentaires et certaines options peu courantes ne sont pas repris.