Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Мониторинг на основе аннотаций — одна аннотация, много компонентов

В этом примере Feature мониторинга подключается к шести сервисам во вложенной топологии без единого блока features: на уровне компонента. Одна аннотация оператора на верхней границе, уточнённая двумя переопределениями для поддеревьев, разворачивается — через привязку features.annotations в Manifest — в подключение core/prometheus-exporter к каждому вложенному компоненту, и каждый из них формирует свой Prometheus ServiceMonitor.

Это механизм развёртывания Feature на основе аннотаций: шаблон для сжатия повторяющихся подключений Feature к отдельным компонентам в одну аннотацию, которая каскадно распространяется вниз по дереву границ.

Структура

  • Намерение разработчика (aggregate.yaml) объявляет только шесть компонентов example/compute/service — gateway и api/worker/ledger/etl/reconcile. Ни один компонент не содержит блока мониторинга features:.
  • Сущность Manifest (manifest.yaml) привязывает аннотацию к 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
  • Сущность Release (release.yaml) задаёт аннотацию один раз на границе platform и уточняет её для поддеревьев:
    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 и его FeatureRecipe ServiceMonitor уровня компонента берутся из стандартного каталога (в этом примере нет локальной копии). Чарт рецепта выдаёт по одному ServiceMonitor monitoring.coreos.com/v1 на каждый подключённый компонент, подставляя interval/port/path из разрешённой аннотации — все три являются параметрами сбора метрик оператора в infra этой фичи. (Это генерация ресурсов FeatureRecipe — source: + valuesMapping:, отрисовываемые провайдером helm, — а не мутатор Wasm и не шаг конвейера.)

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd annotation-driven-monitoring

Сборка

Pull разрешает lockfile, а сборка его читает:

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

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки сами. Если в папке рабочего пространства ещё нет папки `annotation-driven-monitoring`, вызовите один раз инструмент `scaffold`, задав для `example` значение `annotation-driven-monitoring` и не задавая `dir`: он запишет пример в новую папку `annotation-driven-monitoring`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `annotation-driven-monitoring`, для `release` — `release.yaml`, для `auto_pull` — true и для `write` — true. Сообщите мне, какие файлы записала сборка; они находятся в `annotation-driven-monitoring/dist/`.

Что доказывает сформированный результат

Разрешите lock-файл, выполните сборку и изучите 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

Это имя файла стоит расшифровать, потому что никто его здесь не набирал. Эта цель читает только файлы, лежащие непосредственно в каталоге, поэтому файлы подключения попадают рядом с собственными файлами компонента и несут две координаты в имени файла, а не в сегментах каталогов: компонент, к которому подключена Feature, а затем имя, под которым она подключена. Здесь вторая координата — не имя, которое кто-то написал: её порождает аннотация, и это сам ключ аннотации, feature.aggrega.ai/monitoring. Точка и косая черта не могут входить в имя файла как есть, поэтому каждая заменяется на -z и букву: -zd для точки, -zs для косой черты. Для компонента api в границе payments сборка записывает

dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yaml

Благодаря кодированию косая черта в этом ключе не создаёт отдельного каталога — в этом и смысл, поскольку файл уровнем ниже не подхватит потребитель конфигурации сбора, читающий каталог границы.

Этот пример использует core/prometheus-exporter и его FeatureRecipe ServiceMonitor (а также провайдер helm) из стандартной библиотеки. Демонстрационный компонент example/compute/service и его рецепт находятся в общем каталоге под издателем example/, рядом с этими сущностями стандартной библиотеки. Его .aggrega-config.yaml объявляет hub.aggrega.ai реестром по умолчанию, поэтому сущности разрешаются из хаба — ни одной из команд не нужен флаг --catalog.

ComponentГраницаintervalportpath
gatewayplatform30s (значение platform по умолчанию)metrics/metrics
api / worker / ledgerpayments15s (переопределение)metrics/metrics
etl / reconcilebatch120s (переопределение)metrics/metrics

Три факта, которые наглядно показывает таблица:

  1. На основе аннотаций, а не объявлено автором. В Aggregate нигде нет features: для мониторинга, и всё же формируются шесть ServiceMonitor. Они существуют только потому, что аннотация развернула core/prometheus-exporter на каждый компонент (origin присоединения в графе сборки — annotation, а не explicit).
  2. Глубокое слияние по подключам. payments и batch задают только interval, но их ServiceMonitor содержат port: metrics и path: /metrics — унаследованные из структурированного значения аннотации platform и слитые по подключам. Поддерево переопределяет одно поле и наследует соседние.
  3. Разветвление. Шесть компонентов отслеживаются с помощью одной аннотации platform и двух однострочных переопределений — без блока features:, повторяемого для каждого компонента.

ServiceMonitor собирает метрики с именованного порта metrics объекта Service (синтезированный Service открывает metrics: 9090), поэтому port: metrics в привязке разрешается в реальную конечную точку.

Время компиляции и время выполнения

Это пример для Kubernetes/Helm; доказательство — сформированные манифесты в dist/. port в ServiceMonitor ссылается на именованный порт Service, поэтому селектор и конечная точка совпадают по построению — для проверки связей кластер не нужен. Работающий Prometheus Operator использовал бы сформированные ServiceMonitor при развёртывании; работа компилятора (аннотация → ServiceMonitor для каждого компонента с профилем, разрешённым каскадом) завершена и доступна для проверки заранее.

Сборка детерминирована — запустите её повторно, и результат будет побайтово идентичен.