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

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 componentes example/compute/service — gateway, e api/worker/ledger/etl/reconcile. Nenhum componente tem um bloco features: 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 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 refina-a 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 â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:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd annotation-driven-monitoring

Compilação

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

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

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

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

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

ComponentFronteiraintervalportpath
gatewayplatform30s (predefinição de platform)metrics/metrics
api / worker / ledgerpayments15s (substituição)metrics/metrics
etl / reconcilebatch120s (substituição)metrics/metrics

Três factos que a tabela torna concretos:

  1. 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 expandiu core/prometheus-exporter para cada componente (o origin do anexo no grafo de compilação é 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, fundidos subchave a subchave. Uma subárvore substitui um campo e herda os campos irmãos.
  3. 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.