Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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 componentes example/compute/service — gateway, e api/worker/ledger/etl/reconcile. Nenhum componente traz um bloco features: 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 binding
    annotations:
    feature.aggrega.ai/monitoring:
    feature: core/prometheus-exporter
    maps:
    infra: [interval, port, path] # structured-value subkeys → the feature's infra
  • A Release (release.yaml) define a anotação uma única vez na fronteira platform e a refina por subárvore:
    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 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:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd annotation-driven-monitoring

Build

O pull resolve o lockfile e o build o lê:

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

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

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

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

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

ComponentFronteiraintervalportpath
gatewayplatform30s (padrão de platform)metrics/metrics
api / worker / ledgerpayments15s (sobrescrita)metrics/metrics
etl / reconcilebatch120s (sobrescrita)metrics/metrics

Três fatos que a tabela torna concretos:

  1. 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 expandiu core/prometheus-exporter em cada componente (o origin da vinculação no grafo de build é annotation, não explicit).
  2. Deep merge por subchave. payments e batch definem apenas interval, e mesmo assim os seus ServiceMonitors trazem port: metrics e path: /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.
  3. 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.