Variables et Fonctions

3. Variables et Fonctions #

Types, sources de valeurs, fonctions intégrées et cinq exemples concrets pour rendre une configuration Alloy dynamique et réutilisable.

Les types de valeurs #

Une configuration Alloy manipule des valeurs typées : nombres, chaînes, booléens, null, tableaux [ ] et objets { }. S'y ajoutent deux types propres à Alloy : secret, pour les mots de passe et jetons, et capsule, pour les valeurs internes comme les récepteurs ou les cibles.

// Nombres, chaînes, booléens, null
scrape_interval = "30s"
sample_limit    = 5000
enabled         = true

// Tableau : virgule finale recommandée
enable_collectors = ["cpu", "meminfo", "filesystem",]

// Objet : clés en identifiant ou en chaîne
targets = [
  { "__address__" = "app-1:8080", env = "prod" },
  { "__address__" = "app-2:8080", env = "prod" },
]

// Référence à la valeur exportée par un autre composant
forward_to = [prometheus.remote_write.mimir.receiver]

Une erreur de type est détectée au chargement : par exemple une chaîne passée là où un nombre est attendu. Le message indique le fichier, la ligne et l'attribut fautif.

D'où viennent les « variables » ? #

Il n'existe pas de bloc variable ou locals comme en Terraform. Une valeur réutilisable provient toujours de l'une de ces sources :

Les sources local.* et remote.* sont elles-mêmes des composants. Quand leur contenu change, tous les composants qui les lisent sont réévalués automatiquement.

Pour le détail de ce qu'Alloy lit dans l'environnement, et notamment OTEL_RESOURCE_ATTRIBUTES, voyez la leçon Variables d'environnement et OpenTelemetry.

Opérateurs et fonctions intégrées #

Les expressions acceptent les opérateurs arithmétiques (+ - * / % ^), de comparaison (== != < <= > >=) et logiques (&& || !). L'opérateur + concatène aussi les chaînes. Les fonctions de la bibliothèque standard sont rangées par espace de noms :

Anciens noms : dans Grafana Agent Flow (River), ces fonctions s'appelaient env(), format(), join(), concat(), json_decode() ou nonsensitive(). Si un exemple trouvé en ligne échoue avec « unknown function », renommez-les avec leur espace de noms.

Exemple 1 : une configuration par environnement #

Le même fichier config.alloy est déployé partout ; les valeurs propres à chaque environnement sont passées par des variables d'environnement (Docker, Helm, systemd).

// Même fichier pour la préproduction et la production :
// seules les variables d'environnement changent.
prometheus.remote_write "mimir" {
  endpoint {
    // coalesce : première valeur non vide (valeur par défaut si la variable est absente)
    url = coalesce(sys.env("MIMIR_URL"), "http://mimir:9009/api/v1/push")

    headers = {
      "X-Scope-OrgID" = coalesce(sys.env("MIMIR_TENANT"), "anonymous"),
    }
  }

  external_labels = {
    cluster     = coalesce(sys.env("CLUSTER_NAME"), "local"),
    environment = string.to_lower(coalesce(sys.env("ENV"), "DEV")),
    host        = constants.hostname,
  }
}

# Préproduction
MIMIR_URL=https://mimir-preprod.example.com/api/v1/push CLUSTER_NAME=preprod ENV=PREPROD alloy run config.alloy

# Docker Compose
services:
  alloy:
    image: grafana/alloy:latest
    environment:
      MIMIR_URL: https://mimir.example.com/api/v1/push
      CLUSTER_NAME: prod-eu
      ENV: PROD

Exemple 2 : un secret lu dans un fichier #

// Le mot de passe est lu dans un fichier monté (secret Kubernetes, Vault agent…)
local.file "mimir_password" {
  filename  = "/var/run/secrets/mimir/password"
  is_secret = true              // la valeur est de type secret : jamais affichée dans l'UI
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "https://mimir.example.com/api/v1/push"
    basic_auth {
      username = sys.env("MIMIR_USER")
      password = local.file.mimir_password.content
    }
  }
}

Avec is_secret = true, la valeur exportée est de type secret : elle n'apparaît ni dans l'interface d'Alloy ni dans les journaux. Si le fichier est mis à jour (rotation du mot de passe), Alloy le relit et reconfigure l'envoi sans redémarrage.

N'écrivez jamais un mot de passe en clair dans config.alloy : le fichier finit presque toujours dans un dépôt Git. Préférez local.file, remote.kubernetes.secret ou remote.vault.

Exemple 3 : des cibles décrites dans un fichier JSON #

// targets.json, maintenu par un autre outil (CMDB, script, Ansible…) :
// [{"__address__": "db-1:9187", "role": "primary"}, {"__address__": "db-2:9187", "role": "replica"}]
local.file "targets" {
  filename = "/etc/alloy/targets.json"
}

prometheus.scrape "postgres" {
  // encoding.from_json transforme le contenu du fichier en tableau d'objets
  targets    = encoding.from_json(local.file.targets.content)
  forward_to = [prometheus.remote_write.mimir.receiver]
}
// Le fichier modifié est relu automatiquement : les nouvelles cibles sont collectées sans redémarrage.

Ce modèle permet à une équipe de déclarer ses cibles dans un fichier simple, sans toucher à la configuration d'Alloy. Les champs autres que __address__ (ici role) deviennent des étiquettes des métriques collectées.

Exemple 4 : construire des chaînes et des étiquettes #

loki.process "normalize" {
  forward_to = [loki.write.default.receiver]

  stage.static_labels {
    values = {
      // Concaténation avec +
      service = "checkout-" + coalesce(sys.env("REGION"), "eu"),
      // Mise en forme
      team    = string.to_upper("payments"),
      // Assemblage d'une liste
      zones   = string.join(["eu-west-3a", "eu-west-3b"], ","),
    }
  }
}

Il n'y a pas d'interpolation ${...} comme en HCL : la concaténation avec + suffit pour les cas simples, string.format devient plus lisible dès qu'il y a plusieurs valeurs.

Exemple 5 : factoriser avec declare et import #

Pour éviter de copier-coller le même bloc, Alloy propose les composants personnalisés avec declare. Ce sont l'équivalent des modules Terraform : des paramètres d'entrée (argument), des composants internes et des valeurs exportées (export).

// Composant personnalisé réutilisable : l'équivalent d'un module Terraform
declare "mimir_writer" {
  argument "url" {}
  argument "tenant" {
    optional = true
    default  = "anonymous"
  }

  prometheus.remote_write "default" {
    endpoint {
      url     = argument.url.value
      headers = { "X-Scope-OrgID" = argument.tenant.value }
    }
  }

  export "receiver" {
    value = prometheus.remote_write.default.receiver
  }
}

// Deux instances, deux tenants, sans dupliquer la configuration
mimir_writer "prod" {
  url    = "https://mimir.example.com/api/v1/push"
  tenant = "prod"
}
mimir_writer "audit" {
  url    = "https://mimir.example.com/api/v1/push"
  tenant = "audit"
}

prometheus.scrape "app" {
  targets    = [{ "__address__" = "app:8080" }]
  forward_to = [mimir_writer.prod.receiver, mimir_writer.audit.receiver]
}

Pour partager ces composants entre plusieurs équipes ou serveurs, placez-les dans un fichier séparé et chargez-les avec import.file, import.http ou import.git :

// Charger des composants partagés depuis un dépôt Git (relu toutes les 5 minutes)
import.git "shared" {
  repository     = "https://github.com/acme/alloy-modules.git"
  revision       = "main"
  path           = "modules/mimir.alloy"
  pull_frequency = "5m"
}

shared.mimir_writer "prod" {
  url = sys.env("MIMIR_URL")
}

Bonnes pratiques : un fichier par rôle (collecte, traitement, envoi) ; des valeurs par défaut avec coalesce ; les secrets dans local.file ou un coffre-fort ; alloy fmt dans la CI ; et un coup d'œil au graphe de l'interface après chaque modification.