Prometheus — ein Server, zwei Scrape-Ziele
Dieses Beispiel kompiliert einen kleinen, echten Stack — einen Prometheus-Metrikserver, der zwei Grafana-Dashboard-Server scrapt — aus einem einzigen vom Entwickler verfassten Aggregate zu zwei Zielen:
- Docker Compose für die lokale Entwicklung und
- Kubernetes über Workload-Synthese auf dem offiziellen Image
prom/prometheus.
Dasselbe aggregate.yaml steuert beide. Pro Ziel ändert sich nur die vom Manifest ausgewählte Recipe-Schicht.
Grafana stellt seine eigenen Metriken im Prometheus-Textformat unter /metrics an seinem Web-Port bereit, und zwar standardmäßig, daher ist jedes Grafana ein echtes Scrape-Ziel. Beide sind derselbe Component-Typ, zweimal verdrahtet, daher stammt alles, was sich zwischen den beiden Scrape-Jobs unterscheidet, aus dem, was auf jeder Verbindung verfasst ist, und daraus, wo jedes Grafana angibt, seine Metriken bereitzustellen.
Dateien
| Datei | Rolle |
|---|---|
aggregate.yaml | Entwicklerabsicht: zwei Grafanas, team-dashboards und ops-dashboards (beide core/observability/grafana), und ein Server metrics (core/observability/prometheus), der eine Nutzung scrape_target von jedem deklariert. |
manifest-compose.yaml | Bildet den Prometheus-Typ auf das Compose-Recipe (compose/prometheus) und den Grafana-Typ auf das Grafana-Compose-Recipe (compose/grafana) ab. |
manifest-helm-synth.yaml | Bildet den Prometheus-Typ auf das synthetisierte helm-Recipe (helm/prometheus) und den Grafana-Typ auf das synthetisierte Grafana-helm-Recipe (helm/grafana) ab. Keines davon ruft ein Chart ab. |
release-compose.yaml / release-helm-synth.yaml | Dokumente des Operators für die beiden Ziele. |
Zwei Ziele an einem Socket verdrahten
scrape_target ist ein Socket mit zwei Verbindungen, und jede Verbindung wird zu einem Scrape-Job:
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: 30sDie Verbindung team-dashboards verfasst keine values, daher übernimmt ihr Job, was der Socket deklariert. Die Verbindung ops-dashboards setzt zwei Schlüssel, und jeder Schlüssel, den sie setzt, formt nur diesen Job — der Job team-dashboards bleibt davon unberührt.
Das Ziel gibt an, wo es Metriken bereitstellt
Eine Verbindung gibt an, wie oft Prometheus scrapt und unter welchem Job-Namen; sie gibt nie an, wo. Das ist eine eigene Angabe des Ziels, und das Ziel veröffentlicht sie: Jedes Grafana-Recipe veröffentlicht metrics_endpoint, die vollständige Adresse seiner Metriken — Schema, Host, Port und Pfad, etwa http://team-dashboards:3000/metrics auf Compose. Prometheus baut den Scrape-Job aus dieser Adresse: aus ihrem Schema, ihrem Pfad und ihrem Host und Port als Ziel des Jobs.
Ein Ziel, das keine Metriken bereitstellt, veröffentlicht also keine Adresse, und es an scrape_target zu verdrahten bricht den Build ab und nennt das Ziel, statt einen Job zu kompilieren, der nichts scrapen würde. Ein Produkt, dessen Metriken ausgeschaltet sind, bis ein Wert sie einschaltet — viele im Katalog nehmen metrics_enabled —, veröffentlicht seine Adresse, solange sie eingeschaltet sind. Auf Kubernetes kann ein Ziel stattdessen veröffentlichen, worüber Prometheus seine Metriken entdeckt, einen Service oder einen Pod-Selektor, wenn keine einzelne Adresse sie alle erreicht; die Compose-Realisierung hat keinen Cluster, in dem sie etwas entdecken könnte, und bricht bei einem solchen Ziel ab.
Der Socket nimmt Server, zustandsbehaftete Server und Worker gleichermaßen an, sodass eine Datenbank, ein Log-Store oder ein Operator auf dieselbe Weise verdrahtet wird; ob sie gescrapt werden können, entscheidet das, was sie veröffentlichen.
Was es zeigt
- Eine Authoring-Oberfläche, viele Ziele. Ein einziges Aggregate ist die maßgebliche Quelle dafür, was der Stack ist. Jedes Manifest sagt, wie er zu realisieren ist.
- Ein Socket, viele Verbindungen. Prometheus scrapt so viele Ziele, wie das Aggregate in
scrape_targetverdrahtet. Das Recipe erzeugt einen Scrape-Job pro Verbindung, sodass die Anzahl der Jobs der Topologie folgt statt dem Recipe. - Konfiguration pro Verbindung.
job_nameundscrape_intervalwerden imvalueSchemades Sockets deklariert, was sie zu Eigenschaften einer Verbindung statt des Servers macht. Ein einziger Prometheus, der mehrere Ziele scrapt, kann in einem einzigen Component-weiten Wert nicht mehrere Intervalle ausdrücken. - Deklarierte Standardwerte füllen die Schlüssel, die eine Verbindung weglässt.
scrape_intervalträgt imvalueSchemades Sockets einen Standardwert. Eine Verbindung, die ihn weglässt — hierteam-dashboards—, erhält ihn, und eine Verbindung, die ihn setzt —ops-dashboards—, überschreibt nur, was sie gesetzt hat. - Scrape-Verdrahtung über die String Pipe. Der
metrics_endpointjedes Grafana-Recipe wird in Prometheus geleitet und in den Job dieses Grafana gerendert: sein Schema, sein Pfad und sein Eintrag intargets. Der Compiler leitet den String weiter, ohne ihn zu interpretieren: Jedes Recipe entscheidet, welche Adresse sein eigenes Ziel veröffentlicht, und der Compiler leitet sie unverändert durch. - Provider-idiomatische Konfiguration. Auf beiden Zielen schreibt der Server beim Start eine minimale
prometheus.yml, deren Scrape-Jobs die verdrahteten Grafanas adressieren, und führt dann Prometheus damit aus. Auf Compose läuft dies als Service; auf Kubernetes wird derselbe Container in ein StatefulSet gerendert. - Persistenter Zustand. Prometheus speichert seine Samples auf einem Datenvolume, damit sie Neustarts überstehen — lokal ein benanntes Compose-Volume und auf Kubernetes ein PersistentVolumeClaim pro Replik, dimensioniert aus
infra.storage. Jedes Grafana behält seine Benutzer und Dashboards auf einem eigenen Volume. - Reproduzierbare Images. Jedes Recipe hier legt sein Image-Tag aus
infra.engine_versionfest, sodass die gerenderten Arbeitslasten auf feste Images verweisen. - Schlanke Struktur mit einem einzigen Zweck. Auf Kubernetes wird die Prometheus-Komponente als ihr StatefulSet, ihre ClusterIP- und Headless-Services und ihr Claim für das Datenvolume gerendert — nichts weiter. Jedes Grafana wird als sein eigenes Deployment, sein Service und sein Claim für das Datenvolume gerendert.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example prometheus-scrapeDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd prometheus-scrapeBuild
Dieser Workspace enthält keine .aggrega-config.yaml, daher werden die Entitäten der Standardbibliothek aus der Hub-Registry hub.aggrega.ai aufgelöst, und es ist kein Katalog-Flag nötig:
# 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-pullGerenderte Artefakte landen unter dist/. --auto-pull löst während des Builds die Abhängigkeiten jedes Release in seine Lockfile auf; aggrega pull --release release-compose.yaml einmal vorab auszuführen tut dasselbe und lässt spätere Builds ohne das Flag laufen. Das synthetisierte Ziel benötigt keinen Abruf eines externen Charts — beide Recipes rendern die offiziellen Images direkt in Kubernetes-Ressourcen.
Mit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `prometheus-scrape` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `prometheus-scrape` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `prometheus-scrape`. Rufen Sie dann das Tool `build` einmal für jedes Release auf, in dieser Reihenfolge — `release-compose.yaml` und `release-helm-synth.yaml` — jedes Mal mit `workspace_root` auf `prometheus-scrape`, `release` auf die jeweilige Datei, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `prometheus-scrape/dist/`.Wie die kompilierte Scrape-Konfiguration aussieht
Auf Compose schreibt der Server eine prometheus.yml mit einem Job pro verdrahtetem Grafana, der jeweils den metrics_endpoint adressiert, den dieses Grafana veröffentlicht — seinen Compose-Servicenamen und 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"Auf Kubernetes werden dieselben zwei Jobs vom Startbefehl des synthetisierten StatefulSet geschrieben, wobei jeder den Service dieses Grafana adressiert, den der helm-Provider nach der Komponente und ihrem Service-Schlüssel default benennt:
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"Beide Ziele kompilieren dieselben zwei Jobs aus denselben zwei Aggregate-Kanten: Der metrics_endpoint jedes Grafana wandert über seine eigene Verbindung scrape_target, und der Compiler leitet diesen String in den Job, ohne ihn zu interpretieren. Was sich zwischen den Zielen unterscheidet, ist die Adresse, die jedes Grafana veröffentlicht — auf dem einen ein Compose-Servicename, auf dem anderen ein Service-Name —, und die Arbeitslast, in die die Konfiguration geschrieben wird — auf dem einen ein Compose-Service, auf dem anderen ein StatefulSet. Hier liegen beide Grafanas im selben Geltungsbereich wie Prometheus; auf Kubernetes wird ein Grafana, das das Release in einem anderen Namespace platziert, über seinen Service-Namen adressiert, qualifiziert mit diesem Namespace.
Lesen Sie den Job team-dashboards neben dem Job ops-grafana, um zu sehen, woher jeder Wert stammt. Der Job ops-grafana trägt ops-grafana und 30s, weil seine Verbindung beide verfasst. Der Job team-dashboards trägt team-dashboards als seinen job_name, weil das Aggregate keinen deklariert und das Recipe auf den Alias der Verbindung zurückgreift — den Namen, den dieses Aggregate der Verbindung gegeben hat —, und er trägt 15s, weil das der Standardwert ist, den der Socket scrape_target der Component für den Schlüssel deklariert, den diese Verbindung weggelassen hat. Das Schema, der metrics_path und das Ziel beider Jobs stammen aus der Adresse, die jedes Grafana veröffentlicht, also von dort, wo Grafana seine Metriken bereitstellt, sodass keine der beiden Verbindungen etwas darüber sagt. Das Setzen eines Schlüssels auf einer Verbindung überschreibt ihn für diesen Job und lässt den anderen Job unberührt.
All dies geschieht auf der konsumierenden Seite. Konfiguration pro Verbindung erscheint nur im Render-Kontext des Knotens, der die Verbindung verfasst hat, nie in dem des Ziels, sodass das Verdrahten oder Abstimmen einer Verbindung zu einem Grafana nie stört, was dieses Grafana selbst rendert — sein Deployment und sein Service sind in beiden Fällen dieselben Bytes.
Grafana gibt seine Metriken jedem Aufrufer heraus, daher trägt keine der beiden Verbindungen Zugangsdaten. Für ein Ziel, dessen Metriken welche erfordern, trägt die Verbindung sie in ihrem Slot credential, und Prometheus legt sie als Bearer-Token vor, das aus einer Datei gelesen wird; ein Ziel, das metrics_credential_required als true veröffentlicht, bricht den Build ab, solange seine Verbindung keine trägt.
Ausführen (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dDas Release gibt jedem Grafana einen eigenen Port — team-dashboards auf 3000 und ops-dashboards auf 3001 —, sodass beide lokal nebeneinander laufen. Jedes Grafana lauscht auf dem Port, den sein Release ihm gibt, und jeder Port wandert in der Adresse mit, die dieses Grafana in das Ziel seines eigenen Scrape-Jobs veröffentlicht.
Öffnen Sie http://127.0.0.1:9090 — den Ausdrucks-Browser von Prometheus, den das Compose-Recipe nur auf der Loopback-Adresse des Hosts veröffentlicht. Unter Status → Targets sind die beiden Jobs unter den Namen aufgeführt, die die kompilierte Konfiguration ihnen gibt, ops-grafana und team-dashboards, wobei jeder den Pfad /metrics seines Grafana adressiert. Eine Abfrage nach grafana_build_info, dem Gauge, den jedes Grafana auf 1 setzt und mit seiner Version labelt, liefert eine Serie pro Job. Zum Abbauen: docker compose -f dist/app/compose/docker-compose.yaml down.