Monitorização orientada por anotações — uma anotação, muitos componentes
Este exemplo anexa uma Feature de monitorização a seis serviços numa topologia aninhada sem escrever um único bloco features: por componente. Uma única anotação do operador na fronteira de topo, refinada por duas substituições de subárvore, expande-se — através do vínculo features.annotations do Manifest — num anexo 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 anexos de Feature repetitivos por componente numa única anotação que se propaga em cascata pela árvore de fronteiras.
A estrutura
- A intenção do programador (
aggregate.yaml) declara apenas seis componentesexample/compute/service—gateway, eapi/worker/ledger/etl/reconcile. Nenhum componente tem um blocofeatures:de monitorização. - 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 refina-a 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 âmbito de componente são consumidos a partir do catálogo standard (este exemplo não declara nenhuma cópia local). O chart da receita emite um ServiceMonitor monitoring.coreos.com/v1 por cada componente anexado, gerando por template interval/port/path a partir da anotação resolvida — os três são definições de scrape do operador no infra da funcionalidade. (Trata-se da geração de recursos de FeatureRecipe — source: + valuesMapping: renderizados pelo fornecedor helm —, e não de um mutador Wasm nem de um passo de pipeline.)
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example annotation-driven-monitoringDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd annotation-driven-monitoringCompilação
O pull resolve o lockfile e o build lê-o:
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-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho 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`: esta escreve o exemplo numa 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 que ficheiros a compilação escreveu; encontram-se em `annotation-driven-monitoring/dist/`.O que a saída renderizada comprova
Resolva o lockfile, compile 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 descodificar esse nome de ficheiro, porque ninguém aqui o escreveu. Este destino lê apenas os ficheiros que estão diretamente num diretório, pelo que os ficheiros de um anexo ficam ao lado dos do próprio componente e trazem as suas duas coordenadas no nome do ficheiro em vez de em segmentos de diretório: o componente ao qual a Feature está anexada e, depois, o nome sob o qual está anexada. Aqui a segunda coordenada não é um nome que alguém tenha escrito — é a anotação que o cria, e é a própria chave da anotação, feature.aggrega.ai/monitoring. Um ponto e uma barra não podem entrar num nome de ficheiro tal como estão escritos, pelo que cada um passa a -z seguido de uma letra: -zd para o ponto, -zs para a barra. Para o componente api na fronteira payments, a compilação escreve
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlA codificação é a razão pela qual a barra nessa chave não abre um diretório próprio — e é precisamente esse o objetivo, já que um ficheiro um nível abaixo é um ficheiro que um consumidor de scrape-config que leia o diretório da fronteira não recolheria.
Este exemplo consome core/prometheus-exporter e a sua FeatureRecipe de ServiceMonitor (além do fornecedor helm) a partir da biblioteca standard. O componente de demonstração example/compute/service e a sua receita encontram-se no catálogo partilhado sob o editor example/, ao lado dessas entidades da biblioteca standard. O seu .aggrega-config.yaml declara hub.aggrega.ai como registo predefinido, pelo que 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 (predefinição de platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (substituição) | metrics | /metrics |
etl / reconcile | batch | 120s (substituição) | metrics | /metrics |
Três factos que a tabela torna concretos:
- Orientado por anotações, não declarado pelo autor. O Aggregate não tem
features:de monitorização em lado nenhum e, mesmo assim, são renderizados seis ServiceMonitors. Existem apenas porque a anotação expandiucore/prometheus-exporterpara cada componente (oorigindo anexo no grafo de compilação éannotation, nãoexplicit). - Deep merge por subchave.
paymentsebatchdefinem apenasintervale, mesmo assim, os seus ServiceMonitors trazemport: metricsepath: /metrics— herdados do valor estruturado da anotação de platform, fundidos subchave a subchave. Uma subárvore substitui um campo e herda os campos irmãos. - Fan-out. Seis componentes são monitorizados a partir de uma anotação de platform mais duas substituições de uma linha — nenhum bloco
features:repetido por componente.
O ServiceMonitor faz scrape da porta com nome metrics do Service (o Service sintetizado expõe metrics: 9090), pelo que o port: metrics do vínculo se resolve num 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 com nome do Service, pelo que o seletor e o endpoint correspondem por construção — não é necessário nenhum cluster para verificar a cablagem. Um Prometheus Operator em execução consumiria os ServiceMonitors renderizados no momento da implementação; o trabalho do compilador (anotação → ServiceMonitor por componente com o perfil resolvido em cascata) está completo e pode ser inspecionado antecipadamente.
A compilação é determinística — ao executá-la de novo, a saída é idêntica byte a byte.