Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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

FileRuolo
aggregate.yamlIntento 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.yamlMappa il tipo Prometheus sulla Recipe Compose (compose/prometheus) e il tipo Grafana sulla Recipe Compose di Grafana (compose/grafana).
manifest-helm-synth.yamlMappa 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.yamlDocumenti 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: 30s

La 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_name e scrape_interval sono dichiarati sul valueSchema del 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_interval porta un valore predefinito sul valueSchema del socket. Una connessione che lo omette — qui team-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_endpoint di ciascuna Recipe di Grafana viene convogliato in Prometheus e renderizzato nel job di quel Grafana: il suo schema, il suo percorso e la sua voce targets. 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.yml minimo 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.storage su 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:

Terminal window
aggrega scaffold --example prometheus-scrape

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

Terminal window
cd prometheus-scrape

Build

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:

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

Gli 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)

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

La 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.