Monitoreo guiado por anotaciones — una anotación, muchos componentes
Este ejemplo vincula una Feature de monitoreo a seis servicios repartidos en una topología anidada sin escribir un solo bloque features: por componente. Una única anotación del operador en el límite superior, refinada por dos sobrescrituras de subárbol, se expande — mediante el enlace features.annotations del Manifest — en una vinculación de core/prometheus-exporter en cada componente contenido, y cada uno renderiza su propio ServiceMonitor de Prometheus.
Esta es la superficie de expansión de Feature guiada por anotaciones: el patrón para comprimir vinculaciones de Feature repetitivas por componente en una única anotación que se propaga en cascada por el árbol de límites.
La estructura
- La intención del desarrollador (
aggregate.yaml) declara solo seis componentesexample/compute/service—gateway, yapi/worker/ledger/etl/reconcile. Ningún componente lleva un bloquefeatures:de monitoreo. - El Manifest (
manifest.yaml) vincula la anotación a la Feature:features:type:core/prometheus-exporter: helm/prometheus-exporter:1.0.0 # the FeatureRecipe version bindingannotations:feature.aggrega.ai/monitoring:feature: core/prometheus-exportermaps:infra: [interval, port, path] # structured-value subkeys → the feature's infra - La Release (
release.yaml) establece la anotación una sola vez en el límiteplatformy la refina por subárbol:platform:annotations:feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits thisboundaries:payments:annotations:feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledgerbatch:annotations:feature.aggrega.ai/monitoring: {interval: 120s} # etl/reconcile
core/prometheus-exporter y su FeatureRecipe de ServiceMonitor de ámbito de componente se consumen desde el catálogo estándar (este ejemplo no declara ninguna copia local). El chart de la receta emite un ServiceMonitor monitoring.coreos.com/v1 por cada componente vinculado, generando con plantillas interval/port/path a partir de la anotación resuelta — los tres son ajustes de scrape del operador en el infra de la funcionalidad. (Es la generación de recursos de FeatureRecipe — source: + valuesMapping: renderizados por el proveedor helm —, no un mutador Wasm ni un paso de pipeline.)
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 annotation-driven-monitoringDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd annotation-driven-monitoringCompilación
El pull resuelve el lockfile y el build lo lee:
aggrega pull --release release.yamlaggrega build --release release.yamlCon 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 tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `annotation-driven-monitoring`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `annotation-driven-monitoring` y sin `dir`: escribe el ejemplo en una nueva carpeta `annotation-driven-monitoring`. Después llama a la herramienta `build` con `workspace_root` establecido en `annotation-driven-monitoring`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `annotation-driven-monitoring/dist/`.Lo que demuestra la salida renderizada
Resuelve el lockfile, compila y examina dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml:
aggrega pull --release release.yamlaggrega build --release release.yamlVale la pena descifrar ese nombre de archivo, porque aquí nadie lo escribió. Este destino solo lee los archivos que están directamente en un directorio, así que los archivos de una vinculación quedan junto a los del propio componente y llevan sus dos coordenadas en el nombre del archivo en lugar de en segmentos de directorio: el componente al que está vinculada la Feature y, después, el nombre con el que está vinculada. Aquí la segunda coordenada no es un nombre que alguien escribiera — la acuña la anotación, y es la propia clave de la anotación, feature.aggrega.ai/monitoring. Un punto y una barra no pueden entrar en un nombre de archivo tal como se escriben, así que cada uno se convierte en -z seguido de una letra: -zd para el punto, -zs para la barra. Para el componente api en el límite payments, la compilación escribe
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlLa codificación es la razón por la que la barra de esa clave no abre un directorio propio — que es justamente lo que se busca, ya que un archivo un nivel más abajo es un archivo que un consumidor de scrape-config que lea el directorio del límite no recogería.
Este ejemplo consume core/prometheus-exporter y su FeatureRecipe de ServiceMonitor (además del proveedor helm) desde la biblioteca estándar. El componente de demostración example/compute/service y su receta están en el catálogo compartido bajo el editor example/, junto a esas entidades de la biblioteca estándar. Su .aggrega-config.yaml declara hub.aggrega.ai como registro predeterminado, así que las entidades se resuelven desde el hub — ninguno de los dos comandos necesita un flag --catalog.
| Component | Límite | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (predeterminado de platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (sobrescritura) | metrics | /metrics |
etl / reconcile | batch | 120s (sobrescritura) | metrics | /metrics |
Tres hechos que la tabla hace concretos:
- Guiado por anotaciones, no declarado por el autor. El Aggregate no tiene
features:de monitoreo en ninguna parte y, aun así, se renderizan seis ServiceMonitors. Existen solo porque la anotación expandiócore/prometheus-exportera cada componente (eloriginde la vinculación en el grafo de compilación esannotation, noexplicit). - Fusión profunda por subclave.
paymentsybatchsolo establecenintervaly, aun así, sus ServiceMonitors llevanport: metricsypath: /metrics— heredados del valor estructurado de la anotación de platform, fusionados subclave a subclave. Un subárbol sobrescribe un campo y hereda los campos hermanos. - Fan-out. Seis componentes se monitorean a partir de una anotación de platform más dos sobrescrituras de una línea — ningún bloque
features:repetido por componente.
El ServiceMonitor hace scrape del puerto con nombre metrics del Service (el Service sintetizado expone metrics: 9090), así que el port: metrics del enlace se resuelve en un endpoint real.
Tiempo de compilación frente a tiempo de ejecución
Este es un ejemplo de Kubernetes/Helm; la prueba son los manifiestos renderizados en dist/. El port del ServiceMonitor hace referencia al puerto con nombre del Service, así que el selector y el endpoint coinciden por construcción — no se necesita ningún clúster para verificar el cableado. Un Prometheus Operator en funcionamiento consumiría los ServiceMonitors renderizados en el momento del despliegue; el trabajo del compilador (anotación → ServiceMonitor por componente con el perfil resuelto en cascada) está completo y puede inspeccionarse de antemano.
La compilación es determinista — vuelve a ejecutarla y la salida es idéntica byte a byte.