Monitoramento orientado por anotações — uma anotação, muitos componentes
Este exemplo vincula uma Feature de monitoramento a seis serviços em uma topologia aninhada sem escrever um único bloco features: por componente. Uma única anotação do operador na fronteira de nível mais alto, refinada por duas sobrescritas de subárvore, se expande — por meio do vínculo features.annotations do Manifest — em uma vinculação de core/prometheus-exporter em cada componente contido, e cada um renderiza o seu próprio ServiceMonitor do Prometheus.
Esta é a superfície de expansão de Feature orientada por anotações: o padrão para comprimir vinculações de Feature repetitivas por componente em uma única anotação que se propaga em cascata pela árvore de fronteiras.
A estrutura
- A intenção do desenvolvedor (
aggregate.yaml) declara apenas seis componentesexample/compute/service—gateway, eapi/worker/ledger/etl/reconcile. Nenhum componente traz um blocofeatures:de monitoramento. - O Manifest (
manifest.yaml) vincula a anotação à 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 - A Release (
release.yaml) define a anotação uma única vez na fronteiraplatforme a refina por subárvore: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 e a sua FeatureRecipe de ServiceMonitor com escopo de componente são consumidos do catálogo padrão (este exemplo não declara nenhuma cópia local). O chart da receita emite um ServiceMonitor monitoring.coreos.com/v1 por componente vinculado, gerando por template interval/port/path a partir da anotação resolvida — os três são configurações de scrape do operador no infra da funcionalidade. (É a geração de recursos de FeatureRecipe — source: + valuesMapping: renderizados pelo provedor helm —, não um mutador Wasm nem uma etapa de pipeline.)
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example annotation-driven-monitoringEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd annotation-driven-monitoringBuild
O pull resolve o lockfile e o build o lê:
aggrega pull --release release.yamlaggrega build --release release.yamlCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `annotation-driven-monitoring`, chame a ferramenta `scaffold` uma única vez com `example` definido como `annotation-driven-monitoring` e sem `dir`: ela escreve o exemplo em uma nova pasta `annotation-driven-monitoring`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `annotation-driven-monitoring`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `annotation-driven-monitoring/dist/`.O que a saída renderizada comprova
Resolva o lockfile, faça o build e examine dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml:
aggrega pull --release release.yamlaggrega build --release release.yamlVale a pena decifrar esse nome de arquivo, porque ninguém aqui o digitou. Este destino lê apenas os arquivos que ficam diretamente em um diretório, então os arquivos de uma vinculação ficam ao lado dos do próprio componente e trazem as suas duas coordenadas no nome do arquivo em vez de em segmentos de diretório: o componente ao qual a Feature está vinculada e, depois, o nome sob o qual ela está vinculada. Aqui a segunda coordenada não é um nome que alguém tenha escrito — a anotação o cunha, e ele é a própria chave da anotação, feature.aggrega.ai/monitoring. Um ponto e uma barra não podem entrar em um nome de arquivo como estão escritos, então cada um vira -z seguido de uma letra: -zd para o ponto, -zs para a barra. Para o componente api na fronteira payments, o build escreve
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlA codificação é o motivo pelo qual a barra nessa chave não abre um diretório próprio — e é justamente essa a ideia, já que um arquivo um nível abaixo é um arquivo que um consumidor de scrape-config que lê o diretório da fronteira não pegaria.
Este exemplo consome core/prometheus-exporter e a sua FeatureRecipe de ServiceMonitor (além do provedor helm) da biblioteca padrão. O componente de demonstração example/compute/service e a sua receita ficam no catálogo compartilhado sob o publicador example/, ao lado dessas entidades da biblioteca padrão. O seu .aggrega-config.yaml declara hub.aggrega.ai como registro padrão, então as entidades são resolvidas a partir do hub — nenhum dos dois comandos precisa de uma flag --catalog.
| Component | Fronteira | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (padrão de platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (sobrescrita) | metrics | /metrics |
etl / reconcile | batch | 120s (sobrescrita) | metrics | /metrics |
Três fatos que a tabela torna concretos:
- Orientado por anotações, não declarado pelo autor. O Aggregate não tem
features:de monitoramento em lugar nenhum, e mesmo assim seis ServiceMonitors são renderizados. Eles existem apenas porque a anotação expandiucore/prometheus-exporterem cada componente (ooriginda vinculação no grafo de build éannotation, nãoexplicit). - Deep merge por subchave.
paymentsebatchdefinem apenasinterval, e mesmo assim os seus ServiceMonitors trazemport: metricsepath: /metrics— herdados do valor estruturado da anotação de platform, mesclados subchave por subchave. Uma subárvore sobrescreve um campo enquanto herda os campos irmãos. - Fan-out. Seis componentes são monitorados a partir de uma anotação de platform mais duas sobrescritas de uma linha — nenhum bloco
features:repetido por componente.
O ServiceMonitor faz scrape da porta nomeada metrics do Service (o Service sintetizado expõe metrics: 9090), então o port: metrics do vínculo se resolve em um endpoint real.
Tempo de compilação vs. tempo de execução
Este é um exemplo de Kubernetes/Helm; a prova são os manifestos renderizados em dist/. O port do ServiceMonitor referencia a porta nomeada do Service, então o seletor e o endpoint correspondem por construção — nenhum cluster é necessário para verificar a ligação. Um Prometheus Operator em execução consumiria os ServiceMonitors renderizados no momento da implantação; o trabalho do compilador (anotação → ServiceMonitor por componente com o perfil resolvido em cascata) está completo e pode ser inspecionado antecipadamente.
O build é determinístico — execute-o de novo e a saída é idêntica byte a byte.