Prometheus — un server, due target di scrape
Questo esempio compila uno stack piccolo ma reale — un server di metriche Prometheus che esegue lo scrape di due server di dashboard Grafana — a partire da un unico Aggregate scritto dallo sviluppatore in due target:
- Docker Compose per lo sviluppo locale, e
- Kubernetes tramite la sintesi del Workload sull’immagine ufficiale
prom/prometheus.
Lo stesso aggregate.yaml guida entrambi. Per ogni target cambia solo il livello di Recipe selezionato dal Manifest.
Grafana espone le proprie metriche nel formato testuale di Prometheus su /metrics sulla sua porta web, e lo fa per impostazione predefinita, quindi ciascun Grafana è un vero target di scrape. Entrambi sono lo stesso tipo di Component cablato due volte, quindi tutto ciò che differisce tra i due job di scrape deriva da ciò che è scritto su ciascuna connessione e da dove ciascun Grafana dice di esporre le proprie metriche.
File
| File | Ruolo |
|---|---|
aggregate.yaml | Intento dello sviluppatore: due Grafana, team-dashboards e ops-dashboards (entrambi core/observability/grafana), e un server metrics (core/observability/prometheus) che dichiara un uso scrape_target di ciascuno. |
manifest-compose.yaml | Mappa il tipo Prometheus sulla Recipe Compose (compose/prometheus) e il tipo Grafana sulla Recipe Compose di Grafana (compose/grafana). |
manifest-helm-synth.yaml | Mappa il tipo Prometheus sulla Recipe helm sintetizzata (helm/prometheus) e il tipo Grafana sulla Recipe helm sintetizzata di Grafana (helm/grafana). Nessuna delle due scarica un chart. |
release-compose.yaml / release-helm-synth.yaml | Documenti dell’operatore per i due target. |
Cablare due target su un socket
scrape_target è un socket che porta due connessioni, e ciascuna connessione diventa un job di 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: 30sLa connessione team-dashboards non scrive alcun values, quindi il suo job prende ciò che il socket dichiara. La connessione ops-dashboards imposta due chiavi, e ciascuna chiave che imposta determina soltanto quel job — il job team-dashboards non viene toccato da esse.
Il target dice dove espone le metriche
Una connessione dice con quale frequenza Prometheus esegue lo scrape e con quale nome di job; non dice mai dove. Questo è un dato proprio del target, ed è il target a pubblicarlo: ciascuna Recipe di Grafana pubblica metrics_endpoint, l’indirizzo completo delle sue metriche — schema, host, porta e percorso, come http://team-dashboards:3000/metrics su Compose. Prometheus costruisce il job di scrape a partire da quell’indirizzo: il suo schema, il suo percorso, e il suo host e la sua porta come target del job.
Quindi un target che non espone metriche non pubblica alcun indirizzo, e cablarne uno a scrape_target arresta la build, nominandolo, anziché compilare un job che non eseguirebbe lo scrape di nulla. Un prodotto le cui metriche sono disattivate finché un valore non le attiva — molti nel catalogo accettano metrics_enabled — pubblica il proprio indirizzo mentre sono attive. Su Kubernetes un target può invece pubblicare ciò attraverso cui Prometheus scopre le sue metriche, un Service o un selettore di pod, quando nessun indirizzo singolo le raggiunge tutte; la realizzazione Compose non ha alcun cluster in cui eseguire la scoperta e si arresta su un target di questo tipo.
Il socket accetta allo stesso modo server, server con stato e worker, quindi un database, uno store di log o un operator si cablano nello stesso modo; se possano essere oggetto di scrape lo decide ciò che pubblicano.
Che cosa dimostra
- Un’unica superficie di authoring, molti target. Un unico Aggregate è la fonte di verità su che cosa è lo stack. Ogni Manifest dice come realizzarlo.
- Un socket, molte connessioni. Prometheus esegue lo scrape di tanti target quanti l’Aggregate ne cabla in
scrape_target. La Recipe emette un job di scrape per connessione, quindi il numero di job segue la topologia anziché la Recipe. - Configurazione per connessione.
job_nameescrape_intervalsono dichiarati sulvalueSchemadel socket, il che li rende proprietà di una connessione anziché del server. Un unico Prometheus che esegue lo scrape di più target non può esprimere più cadenze in un singolo valore valido per tutto il Component. - I valori predefiniti dichiarati riempiono le chiavi che una connessione omette.
scrape_intervalporta un valore predefinito sulvalueSchemadel socket. Una connessione che lo omette — quiteam-dashboards— lo riceve, e una connessione che lo imposta —ops-dashboards— sovrascrive solo ciò che ha impostato. - Cablaggio dello scrape attraverso la String Pipe. Il
metrics_endpointdi ciascuna Recipe di Grafana viene convogliato in Prometheus e renderizzato nel job di quel Grafana: il suo schema, il suo percorso e la sua vocetargets. Il compilatore instrada la stringa senza interpretarla: ciascuna Recipe decide quale indirizzo pubblica il proprio target, e il compilatore lo convoglia invariato. - Configurazione idiomatica per il Provider. Su entrambi i target il server scrive all’avvio un
prometheus.ymlminimo i cui job di scrape indirizzano i Grafana cablati, poi esegue Prometheus su di esso. Su Compose questo gira come un servizio; su Kubernetes lo stesso container viene renderizzato in uno StatefulSet. - Stato persistente. Prometheus conserva i propri campioni su un volume di dati così che sopravvivano ai riavvii — un volume Compose con nome in locale, e un PersistentVolumeClaim per replica dimensionato a partire da
infra.storagesu Kubernetes. Ciascun Grafana conserva i propri utenti e dashboard su un volume proprio. - Immagini riproducibili. Ogni Recipe qui fissa il tag della propria immagine a partire da
infra.engine_version, così i carichi di lavoro renderizzati fanno riferimento a immagini fisse. - Struttura snella a scopo singolo. Su Kubernetes il componente Prometheus viene renderizzato come il suo StatefulSet, i suoi Service ClusterIP e Headless e la claim del suo volume di dati — nient’altro. Ciascun Grafana viene renderizzato come il proprio Deployment, il proprio Service e la claim del proprio volume di dati.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example prometheus-scrapePoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd prometheus-scrapeBuild
Questo workspace non contiene alcun .aggrega-config.yaml, quindi le entità della libreria standard si risolvono dal registry dell’hub, hub.aggrega.ai, e non serve alcun flag di catalogo:
# 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-pullGli artefatti renderizzati finiscono in dist/. --auto-pull risolve le dipendenze di ciascuna Release nel suo lockfile durante la build; eseguire aggrega pull --release release-compose.yaml una volta all’inizio fa lo stesso e permette alle build successive di essere eseguite senza il flag. Il target sintetizzato non ha bisogno di recuperare alcun chart esterno — entrambe le Recipes renderizzano le immagini ufficiali direttamente in risorse Kubernetes.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `prometheus-scrape`, chiama una volta lo strumento `scaffold` con `example` impostato a `prometheus-scrape` e senza `dir`: scrive l’esempio in una nuova cartella `prometheus-scrape`. Poi chiama lo strumento `build` una volta per ogni Release, in quest’ordine — `release-compose.yaml` e `release-helm-synth.yaml` — ogni volta con `workspace_root` impostato a `prometheus-scrape`, `release` impostato a quel file, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto ogni build; si trovano in `prometheus-scrape/dist/`.Com’è fatta la configurazione di scrape compilata
Su Compose, il server scrive un prometheus.yml che contiene un job per ciascun Grafana cablato, ciascuno dei quali indirizza il metrics_endpoint che quel Grafana pubblica — il nome del suo servizio compose e la sua porta:
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"Su Kubernetes, gli stessi due job sono scritti dal comando di avvio dello StatefulSet sintetizzato, ciascuno dei quali indirizza il Service di quel Grafana, che il provider helm nomina in base al componente e alla sua chiave di servizio 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"Entrambi i target compilano gli stessi due job a partire dagli stessi due archi dell’Aggregate: il metrics_endpoint di ciascun Grafana viaggia attraverso la propria connessione scrape_target, e il compilatore convoglia quella stringa nel job senza interpretarla. Ciò che differisce tra i target è l’indirizzo che ciascun Grafana pubblica — un nome di servizio compose nell’uno, un nome di Service nell’altro — e il carico di lavoro in cui viene scritta la configurazione — un servizio Compose nell’uno, uno StatefulSet nell’altro. Qui entrambi i Grafana si trovano nello stesso ambito di Prometheus; su Kubernetes, un Grafana che la Release colloca in un altro namespace viene indirizzato con il nome del suo Service qualificato con quel namespace.
Confronta il job team-dashboards con il job ops-grafana per vedere da dove proviene ogni valore. Il job ops-grafana porta ops-grafana e 30s perché la sua connessione li scrive entrambi. Il job team-dashboards porta team-dashboards come suo job_name perché l’Aggregate non ne dichiara alcuno e la Recipe ricorre all’alias della connessione — il nome che questo Aggregate ha dato alla connessione — e porta 15s perché è il valore predefinito che il socket scrape_target del Component dichiara per la chiave che quella connessione ha omesso. Lo schema, il metrics_path e il target di entrambi i job provengono dall’indirizzo che ciascun Grafana pubblica, che è dove Grafana espone le proprie metriche, quindi nessuna delle due connessioni dice nulla al riguardo. Impostare una chiave su una connessione la sovrascrive per quel job e lascia stare l’altro job.
Tutto questo avviene sul lato consumatore. La configurazione per connessione emerge solo nel contesto di rendering del nodo che ha scritto la connessione, mai in quello del target, quindi cablare o regolare una connessione verso un Grafana non perturba mai ciò che quel Grafana stesso renderizza — il suo Deployment e il suo Service sono gli stessi byte in entrambi i casi.
Grafana fornisce le proprie metriche a qualsiasi chiamante, quindi nessuna delle due connessioni porta una credenziale. Per un target le cui metriche ne richiedono una, la connessione la porta nel suo slot credential, e Prometheus la presenta come bearer token letto da un file; un target che pubblica metrics_credential_required a true arresta la build finché la sua connessione non ne porta alcuna.
Eseguirlo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dLa Release assegna a ciascun Grafana una porta propria — team-dashboards sulla 3000 e ops-dashboards sulla 3001 — così entrambi girano fianco a fianco in locale. Ciascun Grafana è in ascolto sulla porta che la sua Release gli assegna, e ciascuna porta viaggia nell’indirizzo che quel Grafana pubblica nel target del proprio job di scrape.
Apri http://127.0.0.1:9090 — il browser delle espressioni di Prometheus, che la Recipe Compose pubblica solo sull’indirizzo di loopback dell’host. In Status → Targets i due job sono elencati con i nomi che la configurazione compilata assegna loro, ops-grafana e team-dashboards, ciascuno dei quali indirizza il /metrics del proprio Grafana. Una query per grafana_build_info, il gauge che ogni Grafana imposta a 1 ed etichetta con la propria versione, restituisce una serie per job. Per smontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down.