Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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 componentes example/compute/service — gateway, y api/worker/ledger/etl/reconcile. Ningún componente lleva un bloque features: 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 binding
    annotations:
    feature.aggrega.ai/monitoring:
    feature: core/prometheus-exporter
    maps:
    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ímite platform y la refina por subárbol:
    platform:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits this
    boundaries:
    payments:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledger
    batch:
    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:

Terminal window
aggrega scaffold --example annotation-driven-monitoring

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd annotation-driven-monitoring

Compilación

El pull resuelve el lockfile y el build lo lee:

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

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 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:

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

Vale 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.yaml

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

ComponentLímiteintervalportpath
gatewayplatform30s (predeterminado de platform)metrics/metrics
api / worker / ledgerpayments15s (sobrescritura)metrics/metrics
etl / reconcilebatch120s (sobrescritura)metrics/metrics

Tres hechos que la tabla hace concretos:

  1. 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-exporter a cada componente (el origin de la vinculación en el grafo de compilación es annotation, no explicit).
  2. Fusión profunda por subclave. payments y batch solo establecen interval y, aun así, sus ServiceMonitors llevan port: metrics y path: /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.
  3. 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.