Prometheus — un servidor, dos destinos de scrape
Este ejemplo compila un stack pequeño y real — un servidor de métricas Prometheus que hace scrape de dos servidores de paneles de Grafana — a partir de un único Aggregate escrito por el desarrollador a dos destinos:
- Docker Compose para el desarrollo local, y
- Kubernetes mediante la síntesis de Workload sobre la imagen oficial
prom/prometheus.
El mismo aggregate.yaml impulsa ambos. Solo cambia por destino la capa de Recipe que selecciona el Manifest.
Grafana sirve sus propias métricas en el formato de texto de Prometheus en /metrics en su puerto web, y lo hace por defecto, así que cada Grafana es un destino de scrape real. Ambos son el mismo tipo de Component conectado dos veces, así que todo lo que difiere entre los dos jobs de scrape proviene de lo que se escribe en cada conexión y de dónde dice cada Grafana que sirve sus métricas.
Archivos
| Archivo | Rol |
|---|---|
aggregate.yaml | Intención del desarrollador: dos Grafana, team-dashboards y ops-dashboards (ambos core/observability/grafana), y un servidor metrics (core/observability/prometheus) que declara un uso scrape_target de cada uno. |
manifest-compose.yaml | Asigna el tipo Prometheus a la Recipe de Compose (compose/prometheus) y el tipo Grafana a la Recipe de Compose de Grafana (compose/grafana). |
manifest-helm-synth.yaml | Asigna el tipo Prometheus a la Recipe helm sintetizada (helm/prometheus) y el tipo Grafana a la Recipe helm sintetizada de Grafana (helm/grafana). Ninguna descarga un chart. |
release-compose.yaml / release-helm-synth.yaml | Documentos del operador para los dos destinos. |
Conectar dos destinos en un socket
scrape_target es un socket que lleva dos conexiones, y cada conexión se convierte en 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: 30sLa conexión team-dashboards no escribe ningún values, así que su job toma lo que declara el socket. La conexión ops-dashboards establece dos claves, y cada clave que establece da forma solo a ese job — el job team-dashboards no se ve afectado por ellas.
El destino indica dónde sirve las métricas
Una conexión indica con qué frecuencia hace scrape Prometheus y bajo qué nombre de job; nunca indica dónde. Ese es un dato propio del destino, y es el destino quien lo publica: cada Recipe de Grafana publica metrics_endpoint, la dirección completa de sus métricas — esquema, host, puerto y ruta, como http://team-dashboards:3000/metrics en Compose. Prometheus construye el job de scrape a partir de esa dirección: su esquema, su ruta, y su host y su puerto como destino del job.
Así, un destino que no sirve métricas no publica ninguna dirección, y conectarlo a scrape_target detiene la compilación, nombrándolo, en lugar de compilar un job que no haría scrape de nada. Un producto cuyas métricas están desactivadas hasta que un valor las activa — muchos en el catálogo aceptan metrics_enabled — publica su dirección mientras están activadas. En Kubernetes, un destino puede publicar en su lugar aquello mediante lo cual Prometheus descubre sus métricas, un Service o un selector de pods, cuando ninguna dirección única las alcanza todas; la realización de Compose no tiene ningún clúster en el que descubrir y se detiene ante un destino así.
El socket admite por igual servidores, servidores con estado y workers, así que una base de datos, un almacén de registros o un operador se conecta de la misma manera; si se puede hacer scrape de él lo decide lo que publica.
Lo que demuestra
- Una única superficie de autoría, muchos destinos. Un único Aggregate es la fuente de verdad sobre qué es el stack. Cada Manifest dice cómo realizarlo.
- Un socket, muchas conexiones. Prometheus hace scrape de tantos destinos como el Aggregate conecte a
scrape_target. La Recipe emite un job de scrape por conexión, así que el número de jobs sigue la topología y no la Recipe. - Configuración por conexión.
job_nameyscrape_intervalse declaran en elvalueSchemadel socket, lo que los convierte en propiedades de una conexión y no del servidor. Un único Prometheus que hace scrape de varios destinos no puede expresar varias cadencias en un solo valor para todo el Component. - Los valores predeterminados declarados rellenan las claves que una conexión omite.
scrape_intervallleva un valor predeterminado en elvalueSchemadel socket. Una conexión que lo omite — aquíteam-dashboards— lo recibe, y una conexión que lo establece —ops-dashboards— sobrescribe solo lo que estableció. - Conexión del scrape a través de la String Pipe. El
metrics_endpointde cada Recipe de Grafana se canaliza hacia Prometheus y se renderiza en el job de ese Grafana: su esquema, su ruta y su entrada detargets. El compilador enruta la cadena sin interpretarla: cada Recipe decide qué dirección publica su propio destino, y el compilador la canaliza sin cambios. - Configuración idiomática para el Provider. En ambos destinos, el servidor escribe al arrancar un
prometheus.ymlmínimo cuyos jobs de scrape apuntan a los Grafana conectados, y luego ejecuta Prometheus con él. En Compose esto se ejecuta como un servicio; en Kubernetes el mismo contenedor se renderiza en un StatefulSet. - Estado persistente. Prometheus almacena sus muestras en un volumen de datos para que sobrevivan a los reinicios — un volumen de Compose con nombre en local, y un PersistentVolumeClaim por réplica dimensionado a partir de
infra.storageen Kubernetes. Cada Grafana guarda sus usuarios y paneles en un volumen propio. - Imágenes reproducibles. Cada Recipe aquí fija el tag de su imagen a partir de
infra.engine_version, así que las cargas de trabajo renderizadas hacen referencia a imágenes fijas. - Estructura ligera de propósito único. En Kubernetes, el componente Prometheus se renderiza como su StatefulSet, sus Services ClusterIP y Headless y su solicitud de volumen de datos — nada más. Cada Grafana se renderiza como su propio Deployment, su Service y su solicitud de volumen de datos.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example prometheus-scrapeDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd prometheus-scrapeCompilación
Este espacio de trabajo no contiene ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no hace falta ningún flag de catálogo:
# 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-pullLos artefactos renderizados quedan en dist/. --auto-pull resuelve las dependencias de cada Release en su archivo de bloqueo durante la compilación; ejecutar aggrega pull --release release-compose.yaml una vez al principio hace lo mismo y permite que las compilaciones posteriores se ejecuten sin el flag. El destino sintetizado no necesita descargar ningún chart externo — ambas Recipes renderizan las imágenes oficiales directamente en recursos de Kubernetes.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `prometheus-scrape`, llama una vez a la herramienta `scaffold` con `example` establecido en `prometheus-scrape` y sin `dir`: escribe el ejemplo en una nueva carpeta `prometheus-scrape`. Luego llama a la herramienta `build` una vez por cada Release, en este orden — `release-compose.yaml` y `release-helm-synth.yaml` — cada vez con `workspace_root` establecido en `prometheus-scrape`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `prometheus-scrape/dist/`.Cómo es la configuración de scrape compilada
En Compose, el servidor escribe un prometheus.yml que contiene un job por cada Grafana conectado, cada uno apuntando al metrics_endpoint que publica ese Grafana — su nombre de servicio de compose y su puerto:
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"En Kubernetes, los mismos dos jobs los escribe el comando de arranque del StatefulSet sintetizado, cada uno apuntando al Service de ese Grafana, que el proveedor helm nombra según el componente y su clave de servicio 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"Ambos destinos compilan los mismos dos jobs a partir de las mismas dos aristas del Aggregate: el metrics_endpoint de cada Grafana viaja por su propia conexión scrape_target, y el compilador canaliza esa cadena al job sin interpretarla. Lo que difiere entre los destinos es la dirección que publica cada Grafana — un nombre de servicio de compose en uno, un nombre de Service en el otro — y la carga de trabajo en la que se escribe la configuración — un servicio de Compose en uno, un StatefulSet en el otro. Aquí ambos Grafana están en el mismo ámbito que Prometheus; en Kubernetes, un Grafana que la Release coloca en otro namespace se direcciona por su nombre de Service calificado con ese namespace.
Lee el job team-dashboards frente al job ops-grafana para ver de dónde viene cada valor. El job ops-grafana lleva ops-grafana y 30s porque su conexión escribe ambos. El job team-dashboards lleva team-dashboards como su job_name porque el Aggregate no declara ninguno y la Recipe recurre al alias de la conexión — el nombre que este Aggregate dio a la conexión — y lleva 15s porque ese es el valor predeterminado que el socket scrape_target del Component declara para la clave que esa conexión omitió. El esquema, el metrics_path y el destino de ambos jobs provienen de la dirección que publica cada Grafana, que es donde Grafana sirve sus métricas, así que ninguna de las dos conexiones dice nada sobre ellos. Establecer una clave en una conexión la sobrescribe para ese job y deja el otro job intacto.
Todo esto sucede en el lado consumidor. La configuración por conexión aparece solo en el contexto de renderizado del nodo que escribió la conexión, nunca en el del destino, así que conectar o ajustar una conexión hacia un Grafana nunca perturba lo que ese Grafana renderiza por sí mismo — su Deployment y su Service son los mismos bytes en ambos casos.
Grafana entrega sus métricas a cualquier llamador, así que ninguna de las dos conexiones lleva una credencial. Para un destino cuyas métricas requieren una, la conexión la lleva en su ranura credential, y Prometheus la presenta como un bearer token leído de un archivo; un destino que publica metrics_credential_required como true detiene la compilación mientras su conexión no lleve ninguna.
Ejecutarlo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dLa Release da a cada Grafana su propio puerto — team-dashboards en el 3000 y ops-dashboards en el 3001 — así que ambos se ejecutan uno al lado del otro en local. Cada Grafana escucha en el puerto que le da su Release, y cada puerto viaja en la dirección que ese Grafana publica en el destino de su propio job de scrape.
Abre http://127.0.0.1:9090 — el navegador de expresiones de Prometheus, que la Recipe de Compose publica solo en la dirección de loopback del host. En Status → Targets los dos jobs aparecen con los nombres que les da la configuración compilada, ops-grafana y team-dashboards, cada uno apuntando al /metrics de su Grafana. Una consulta de grafana_build_info, el gauge que cada Grafana pone a 1 y etiqueta con su versión, devuelve una serie por job. Para desmontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down.