Мониторинг на основе аннотаций — одна аннотация, много компонентов
В этом примере 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 bindingannotations:feature.aggrega.ai/monitoring:feature: core/prometheus-exportermaps: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 thisboundaries:payments:annotations:feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledgerbatch: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 и не шаг конвейера.)
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example annotation-driven-monitoringЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd annotation-driven-monitoringСборка
Pull разрешает lockfile, а сборка его читает:
aggrega pull --release release.yamlaggrega 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:
aggrega pull --release release.yamlaggrega 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 | Граница | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (значение platform по умолчанию) | metrics | /metrics |
api / worker / ledger | payments | 15s (переопределение) | metrics | /metrics |
etl / reconcile | batch | 120s (переопределение) | metrics | /metrics |
Три факта, которые наглядно показывает таблица:
- На основе аннотаций, а не объявлено автором. В Aggregate нигде нет
features:для мониторинга, и всё же формируются шесть ServiceMonitor. Они существуют только потому, что аннотация развернулаcore/prometheus-exporterна каждый компонент (originприсоединения в графе сборки —annotation, а неexplicit). - Глубокое слияние по подключам.
paymentsиbatchзадают толькоinterval, но их ServiceMonitor содержатport: metricsиpath: /metrics— унаследованные из структурированного значения аннотации platform и слитые по подключам. Поддерево переопределяет одно поле и наследует соседние. - Разветвление. Шесть компонентов отслеживаются с помощью одной аннотации platform
и двух однострочных переопределений — без блока
features:, повторяемого для каждого компонента.
ServiceMonitor собирает метрики с именованного порта metrics объекта Service (синтезированный
Service открывает metrics: 9090), поэтому port: metrics в привязке разрешается в
реальную конечную точку.
Время компиляции и время выполнения
Это пример для Kubernetes/Helm; доказательство — сформированные манифесты в
dist/. port в ServiceMonitor ссылается на именованный порт Service, поэтому
селектор и конечная точка совпадают по построению — для проверки связей
кластер не нужен. Работающий Prometheus Operator использовал бы сформированные ServiceMonitor
при развёртывании; работа компилятора (аннотация → ServiceMonitor для каждого компонента
с профилем, разрешённым каскадом) завершена и доступна для проверки заранее.
Сборка детерминирована — запустите её повторно, и результат будет побайтово идентичен.