Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Prometheus — un serveur, deux cibles de scrape

Cet exemple compile une petite stack réelle — un serveur de métriques Prometheus qui effectue le scrape de deux serveurs de tableaux de bord Grafana — à partir d’un seul Aggregate écrit par le développeur vers deux cibles :

  • Docker Compose pour le développement local, et
  • Kubernetes via la synthèse de Workload sur l’image officielle prom/prometheus.

Le même aggregate.yaml pilote les deux. Seule la couche de Recipe sélectionnée par le Manifest change d’une cible à l’autre.

Grafana expose ses propres métriques au format texte de Prometheus sur /metrics sur son port web, et le fait par défaut, si bien que chaque Grafana est une véritable cible de scrape. Les deux sont le même type de Component câblé deux fois, si bien que tout ce qui diffère entre les deux jobs de scrape provient de ce qui est écrit sur chaque connexion et de l’endroit où chaque Grafana indique exposer ses métriques.

Fichiers

FichierRôle
aggregate.yamlIntention du développeur : deux Grafana, team-dashboards et ops-dashboards (tous deux core/observability/grafana), et un serveur metrics (core/observability/prometheus) qui déclare une utilisation scrape_target de chacun.
manifest-compose.yamlAssocie le type Prometheus à la Recipe Compose (compose/prometheus) et le type Grafana à la Recipe Compose de Grafana (compose/grafana).
manifest-helm-synth.yamlAssocie le type Prometheus à la Recipe helm synthétisée (helm/prometheus) et le type Grafana à la Recipe helm synthétisée de Grafana (helm/grafana). Aucune ne récupère de chart.
release-compose.yaml / release-helm-synth.yamlDocuments de l’opérateur pour les deux cibles.

Câbler deux cibles sur un socket

scrape_target est un socket portant deux connexions, et chaque connexion devient un job de scrape :

metrics:
type: core/observability/prometheus
uses:
scrape_target:
team-dashboards:
target: team-dashboards
ops-dashboards:
target: ops-dashboards
values:
job_name: ops-grafana
scrape_interval: 30s

La connexion team-dashboards n’écrit aucun values, si bien que son job prend ce que le socket déclare. La connexion ops-dashboards définit deux clés, et chaque clé qu’elle définit ne façonne que ce job — le job team-dashboards n’est pas touché par elles.

La cible indique où elle expose ses métriques

Une connexion indique à quelle fréquence Prometheus effectue le scrape et sous quel nom de job ; elle n’indique jamais où. C’est un fait propre à la cible, et c’est la cible qui le publie : chaque Recipe Grafana publie metrics_endpoint, l’adresse complète de ses métriques — schéma, hôte, port et chemin, comme http://team-dashboards:3000/metrics sur Compose. Prometheus construit le job de scrape à partir de cette adresse : son schéma, son chemin, et son hôte et son port comme cible du job.

Ainsi, une cible qui n’expose aucune métrique ne publie aucune adresse, et la câbler à scrape_target arrête le build, en la nommant, plutôt que de compiler un job qui n’effectuerait le scrape de rien. Un produit dont les métriques sont désactivées jusqu’à ce qu’une valeur les active — beaucoup dans le catalogue acceptent metrics_enabled — publie son adresse tant qu’elles sont activées. Sur Kubernetes, une cible peut plutôt publier ce par quoi Prometheus découvre ses métriques, un Service ou un sélecteur de pods, lorsqu’aucune adresse unique ne les atteint toutes ; la réalisation Compose n’a aucun cluster dans lequel effectuer cette découverte et s’arrête sur une telle cible.

Le socket admet aussi bien les serveurs, les serveurs avec état que les workers, si bien qu’une base de données, un magasin de journaux ou un opérateur se câble de la même façon ; c’est ce qu’il publie qui décide s’il peut faire l’objet d’un scrape.

Ce qu’il démontre

  • Une seule surface de rédaction, plusieurs cibles. Un seul Aggregate est la source de vérité sur ce qu’est la stack. Chaque Manifest dit comment la réaliser.
  • Un socket, de nombreuses connexions. Prometheus effectue le scrape d’autant de cibles que l’Aggregate en câble dans scrape_target. La Recipe émet un job de scrape par connexion, si bien que le nombre de jobs suit la topologie plutôt que la Recipe.
  • Configuration par connexion. job_name et scrape_interval sont déclarés sur le valueSchema du socket, ce qui en fait des propriétés d’une connexion plutôt que du serveur. Un seul Prometheus effectuant le scrape de plusieurs cibles ne peut pas exprimer plusieurs cadences dans une seule valeur à l’échelle du Component.
  • Les valeurs par défaut déclarées remplissent les clés qu’une connexion omet. scrape_interval porte une valeur par défaut sur le valueSchema du socket. Une connexion qui l’omet — ici team-dashboards — la reçoit, et une connexion qui la définit — ops-dashboards — ne remplace que ce qu’elle a défini.
  • Câblage du scrape via la String Pipe. Le metrics_endpoint de chaque Recipe Grafana est acheminé vers Prometheus et rendu dans le job de ce Grafana : son schéma, son chemin et son entrée targets. Le compilateur achemine la chaîne sans l’interpréter : chaque Recipe décide de l’adresse que publie sa propre cible, et le compilateur la transmet inchangée.
  • Configuration idiomatique pour le Provider. Sur les deux cibles, le serveur écrit au démarrage un prometheus.yml minimal dont les jobs de scrape adressent les Grafana câblés, puis exécute Prometheus avec celui-ci. Sur Compose, cela s’exécute comme un service ; sur Kubernetes, le même conteneur est rendu dans un StatefulSet.
  • État persistant. Prometheus stocke ses échantillons sur un volume de données afin qu’ils survivent aux redémarrages — un volume Compose nommé en local, et un PersistentVolumeClaim par réplica dimensionné à partir de infra.storage sur Kubernetes. Chaque Grafana conserve ses utilisateurs et ses tableaux de bord sur un volume qui lui est propre.
  • Images reproductibles. Chaque Recipe ici épingle le tag de son image à partir de infra.engine_version, si bien que les charges de travail rendues référencent des images fixes.
  • Structure épurée à usage unique. Sur Kubernetes, le composant Prometheus est rendu sous la forme de son StatefulSet, de ses Services ClusterIP et Headless et de sa demande de volume de données — rien d’autre. Chaque Grafana est rendu sous la forme de son propre Deployment, de son Service et de sa demande de volume de données.

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example prometheus-scrape

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd prometheus-scrape

Build

Cet espace de travail ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard se résolvent depuis le registre du hub, hub.aggrega.ai, et qu’aucun flag de catalogue n’est nécessaire :

Terminal window
# Local development (Docker Compose)
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (Workload synthesis on prom/prometheus)
aggrega build --release release-helm-synth.yaml --auto-pull

Les artefacts rendus sont placés sous dist/. --auto-pull résout les dépendances de chaque Release dans son fichier de verrouillage pendant le build ; exécuter aggrega pull --release release-compose.yaml une fois au préalable fait la même chose et permet aux builds suivants de s’exécuter sans le flag. La cible synthétisée ne nécessite aucune récupération de chart externe — les deux Recipes rendent les images officielles directement en ressources Kubernetes.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `prometheus-scrape`, appelez une fois l’outil `scaffold` avec `example` défini sur `prometheus-scrape` et sans `dir` : il écrit l’exemple dans un nouveau dossier `prometheus-scrape`. Appelez ensuite l’outil `build` une fois pour chaque Release, dans cet ordre — `release-compose.yaml` et `release-helm-synth.yaml` — en définissant à chaque fois `workspace_root` sur `prometheus-scrape`, `release` sur ce fichier, `auto_pull` sur true et `write` sur true. Indiquez-moi quels fichiers chaque build a écrits ; ils se trouvent sous `prometheus-scrape/dist/`.

À quoi ressemble la configuration de scrape compilée

Sur Compose, le serveur écrit un prometheus.yml contenant un job par Grafana câblé, chacun adressant le metrics_endpoint que ce Grafana publie — son nom de service compose et son port :

scrape_configs:
- job_name: ops-grafana
scrape_interval: 30s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "ops-dashboards:3001"
- job_name: team-dashboards
scrape_interval: 15s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "team-dashboards:3000"

Sur Kubernetes, les deux mêmes jobs sont écrits par la commande de démarrage du StatefulSet synthétisé, chacun adressant le Service de ce Grafana, que le fournisseur helm nomme d’après le composant et sa clé de service default :

scrape_configs:
- job_name: ops-grafana
scrape_interval: 30s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "ops-dashboards-default:3001"
- job_name: team-dashboards
scrape_interval: 15s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "team-dashboards-default:3000"

Les deux cibles compilent les deux mêmes jobs à partir des deux mêmes arêtes de l’Aggregate : le metrics_endpoint de chaque Grafana transite par sa propre connexion scrape_target, et le compilateur achemine cette chaîne dans le job sans l’interpréter. Ce qui diffère entre les cibles, c’est l’adresse que publie chaque Grafana — un nom de service compose sur l’une, un nom de Service sur l’autre — et la charge de travail dans laquelle la configuration est écrite — un service Compose sur l’une, un StatefulSet sur l’autre. Ici, les deux Grafana se trouvent dans la même portée que Prometheus ; sur Kubernetes, un Grafana que la Release place dans un autre namespace est adressé par son nom de Service qualifié par ce namespace.

Lisez le job team-dashboards en regard du job ops-grafana pour voir d’où vient chaque valeur. Le job ops-grafana porte ops-grafana et 30s parce que sa connexion écrit les deux. Le job team-dashboards porte team-dashboards comme job_name parce que l’Aggregate n’en déclare aucun et que la Recipe se replie sur l’alias de la connexion — le nom que cet Aggregate a donné à la connexion — et il porte 15s parce que c’est la valeur par défaut que le socket scrape_target du Component déclare pour la clé que cette connexion a omise. Le schéma, le metrics_path et la cible des deux jobs proviennent de l’adresse que publie chaque Grafana, qui est l’endroit où Grafana expose ses métriques, si bien qu’aucune des deux connexions n’en dit quoi que ce soit. Définir une clé sur une connexion la remplace pour ce job et laisse l’autre job intact.

Tout cela se passe du côté consommateur. La configuration par connexion n’apparaît que dans le contexte de rendu du nœud qui a écrit la connexion, jamais dans celui de la cible, si bien que câbler ou ajuster une connexion vers un Grafana ne perturbe jamais ce que ce Grafana rend lui-même — son Deployment et son Service sont les mêmes octets dans les deux cas.

Grafana fournit ses métriques à n’importe quel appelant, si bien qu’aucune des deux connexions ne porte d’informations d’identification. Pour une cible dont les métriques en exigent, la connexion les porte dans son emplacement credential, et Prometheus les présente comme un bearer token lu depuis un fichier ; une cible qui publie metrics_credential_required à true arrête le build tant que sa connexion n’en porte aucune.

L’exécuter (Compose)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker compose -f dist/app/compose/docker-compose.yaml up -d

La Release attribue à chaque Grafana son propre port — team-dashboards sur 3000 et ops-dashboards sur 3001 — si bien que les deux s’exécutent côte à côte en local. Chaque Grafana écoute sur le port que sa Release lui attribue, et chaque port transite dans l’adresse que ce Grafana publie dans la cible de son propre job de scrape.

Ouvrez http://127.0.0.1:9090 — le navigateur d’expressions de Prometheus, que la Recipe Compose publie uniquement sur l’adresse de loopback de l’hôte. Sous Status → Targets, les deux jobs sont listés sous les noms que leur donne la configuration compilée, ops-grafana et team-dashboards, chacun adressant le /metrics de son Grafana. Une requête sur grafana_build_info, la jauge que chaque Grafana met à 1 et étiquette avec sa version, renvoie une série par job. Pour tout arrêter, utilisez docker compose -f dist/app/compose/docker-compose.yaml down.