Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Prometheus — один сервер, дві цілі збору

Цей приклад компілює невеликий реальний стек — сервер метрик Prometheus, який збирає метрики з двох серверів дашбордів Grafana, — з одного Aggregate, написаного розробником, для двох цільових платформ:

  • Docker Compose для локальної розробки та
  • Kubernetes через синтез Workload на основі офіційного образу prom/prometheus.

Той самий aggregate.yaml керує обома. Для кожної цілі змінюється лише шар Recipe, обраний сутністю Manifest.

Grafana віддає власні метрики в текстовому форматі Prometheus за шляхом /metrics на своєму вебпорту, і робить це за замовчуванням, тож кожна Grafana є реальною ціллю збору. Обидві — це той самий тип Component, підключений двічі, тож усе, чим відрізняються два завдання збору, походить з того, що задано на кожному з’єднанні, і з того, де кожна Grafana повідомляє, що віддає свої метрики.

Файли

ФайлРоль
aggregate.yamlНамір розробника: два екземпляри Grafana, team-dashboards і ops-dashboards (обидва core/observability/grafana), та сервер metrics (core/observability/prometheus), який оголошує використання scrape_target для кожного з них.
manifest-compose.yamlЗіставляє тип Prometheus із Compose-сутністю Recipe (compose/prometheus), а тип Grafana — із Compose-сутністю Recipe для Grafana (compose/grafana).
manifest-helm-synth.yamlЗіставляє тип Prometheus із синтезованою helm-сутністю Recipe (helm/prometheus), а тип Grafana — із синтезованою helm-сутністю Recipe для Grafana (helm/grafana). Жодна з них не завантажує chart.
release-compose.yaml / release-helm-synth.yamlЗаписи оператора для двох цілей.

Підключення двох цілей до одного сокета

scrape_target — це один сокет, що несе два з’єднання, і кожне з’єднання стає одним завданням збирання:

metrics:
type: core/observability/prometheus
uses:
scrape_target:
team-dashboards:
target: team-dashboards
ops-dashboards:
target: ops-dashboards
values:
job_name: ops-grafana
scrape_interval: 30s

З’єднання team-dashboards не задає жодних values, тож його завдання бере те, що оголошує сокет. З’єднання ops-dashboards задає два ключі, і кожен заданий ним ключ формує лише це завдання — завдання team-dashboards вони не зачіпають.

Ціль повідомляє, де вона віддає метрики

З’єднання визначає, як часто Prometheus збирає метрики і під якою назвою завдання; воно ніколи не визначає, звідки. Це власний факт цілі, і ціль його публікує: кожен Grafana Recipe публікує metrics_endpoint, повну адресу своїх метрик — схему, хост, порт і шлях, наприклад http://team-dashboards:3000/metrics у Compose. Prometheus будує завдання збору з цієї адреси: її схеми, її шляху, а також хоста й порту як цілі завдання.

Отже, ціль, яка не віддає метрик, не публікує адреси, і під’єднання такої цілі до scrape_target зупиняє збірку з її назвою, замість того щоб скомпілювати завдання, яке нічого б не збирало. Продукт, метрики якого вимкнені, доки їх не ввімкне значення, — багато продуктів у каталозі приймають metrics_enabled, — публікує свою адресу, поки метрики ввімкнені. У Kubernetes ціль може натомість публікувати те, за чим Prometheus виявляє її метрики, — Service або селектор подів, коли жодна окрема адреса не охоплює їх усіх; реалізація для Compose не має кластера, у якому можна виявляти, і зупиняється на такій цілі.

Сокет однаково приймає сервери, сервери зі станом і робочі процеси, тож база даних, сховище журналів або оператор під’єднуються так само; чи можна з них збирати метрики, визначає те, що вони публікують.

Що демонструє приклад

  • Одна поверхня написання, багато цілей. Єдиний Aggregate є джерелом істини щодо того, що являє собою стек. Кожен Manifest визначає, як його реалізувати.
  • Один сокет, багато з’єднань. Prometheus збирає метрики з такої кількості цілей, скільки їх Aggregate під’єднує до scrape_target. Recipe генерує одне завдання збору на кожне з’єднання, тож кількість завдань визначається топологією, а не Recipe.
  • Конфігурація для кожного з’єднання. job_name і scrape_interval оголошено у valueSchema сокета, що робить їх властивостями з’єднання, а не сервера. Один Prometheus, що збирає метрики з кількох цілей, не може виразити кілька періодичностей одним значенням на рівні всього Component.
  • Оголошені значення за замовчуванням заповнюють ключі, які з’єднання пропускає. scrape_interval має значення за замовчуванням у valueSchema сокета. З’єднання, яке його пропускає, — тут team-dashboards — отримує це значення, а з’єднання, яке його задає, — ops-dashboards — перевизначає лише те, що задало.
  • Під’єднання збору метрик через String Pipe. metrics_endpoint кожного Grafana Recipe передається в Prometheus і рендериться в завдання відповідного Grafana: його схему, шлях і запис targets. Компілятор маршрутизує рядок, не інтерпретуючи його: кожен Recipe вирішує, яку адресу публікує його власна ціль, а компілятор передає її без змін.
  • Конфігурація, природна для Provider. На обох цілях сервер під час запуску записує мінімальний prometheus.yml, завдання збору в якому адресують під’єднані екземпляри Grafana, а потім запускає з ним Prometheus через exec. У Compose це працює як сервіс; у Kubernetes той самий контейнер рендериться в StatefulSet.
  • Постійний стан. Prometheus зберігає свої вибірки на томі даних, тож вони переживають перезапуски: локально це іменований том Compose, а в Kubernetes — PersistentVolumeClaim для кожної репліки з розміром із infra.storage. Кожен Grafana зберігає своїх користувачів і дашборди на власному томі.
  • Відтворювані образи. Кожен Recipe тут фіксує тег свого образу з infra.engine_version, тож відрендерені робочі навантаження посилаються на фіксовані образи.
  • Компактна форма з єдиним призначенням. У Kubernetes компонент Prometheus рендериться як його StatefulSet, його сервіси ClusterIP і Headless та запит тому даних — і нічого більше. Кожен Grafana рендериться як власні Deployment, Service і запит тому даних.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example prometheus-scrape

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd prometheus-scrape

Збирання

Цей робочий простір не містить .aggrega-config.yaml, тож сутності стандартної бібліотеки розв’язуються з реєстру hub, hub.aggrega.ai, і прапорець каталогу не потрібен:

Terminal window
# Local development (Docker Compose)
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (Workload synthesis on prom/prometheus)
aggrega build --release release-helm-synth.yaml --auto-pull

Згенеровані артефакти потрапляють до dist/. --auto-pull під час збирання розв’язує залежності кожної сутності Release у її lock-файл; одноразовий запуск aggrega pull --release release-compose.yaml заздалегідь робить те саме й дає змогу подальшим збиранням виконуватися без цього прапорця. Синтезована ціль не потребує завантаження зовнішнього чарту — обидві сутності Recipes рендерять офіційні образи безпосередньо в ресурси Kubernetes.

З ШІ-асистентом

ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.

Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека Workspace ще не містить теки `prometheus-scrape`, викличте один раз інструмент `scaffold`, задавши для `example` значення `prometheus-scrape` і не задаючи `dir`: він запише приклад у нову теку `prometheus-scrape`. Потім викличте інструмент `build` один раз для кожної сутності Release у такому порядку — `release-compose.yaml` і `release-helm-synth.yaml` — щоразу задаючи для `workspace_root` значення `prometheus-scrape`, для `release` — цей файл, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала кожна збірка; вони розташовані в `prometheus-scrape/dist/`.

Як виглядає скомпільована конфігурація збирання метрик

На Compose сервер записує prometheus.yml, що містить одне завдання для кожної підключеної Grafana, і кожне звертається до metrics_endpoint, який публікує ця Grafana, — її ім’я сервісу compose та порт:

scrape_configs:
- job_name: ops-grafana
scrape_interval: 30s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "ops-dashboards:3001"
- job_name: team-dashboards
scrape_interval: 15s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "team-dashboards:3000"

На Kubernetes ті самі два завдання записує команда запуску синтезованого StatefulSet, і кожне звертається до Service відповідної Grafana, який провайдер helm називає за компонентом і його ключем сервісу default:

scrape_configs:
- job_name: ops-grafana
scrape_interval: 30s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "ops-dashboards-default:3001"
- job_name: team-dashboards
scrape_interval: 15s
scheme: http
metrics_path: "/metrics"
static_configs:
- targets:
- "team-dashboards-default:3000"

Обидві цільові платформи компілюють ті самі два завдання з тих самих двох ребер сутності Aggregate: metrics_endpoint кожної Grafana проходить через її власне з’єднання scrape_target, і компілятор передає цей рядок у завдання, не інтерпретуючи його. Між платформами відрізняється адреса, яку публікує кожна Grafana, — ім’я сервісу compose на одній, ім’я Service на іншій — і робоче навантаження, у яке записується конфігурація, — сервіс Compose на одній, StatefulSet на іншій. Тут обидві Grafana перебувають в одній області видимості з Prometheus; на Kubernetes до Grafana, яку сутність Release розміщує в іншому просторі імен, звертаються за ім’ям її Service, уточненим цим простором імен.

Порівняйте завдання team-dashboards із завданням ops-grafana, щоб побачити, звідки береться кожне значення. Завдання ops-grafana містить ops-grafana і 30s, тому що його з’єднання задає обидва. Завдання team-dashboards містить team-dashboards як свій job_name, тому що сутність Aggregate його не оголошує, а сутність Recipe використовує як запасне значення псевдонім з’єднання — ім’я, яке ця сутність Aggregate дала з’єднанню, — і воно містить 15s, тому що це типове значення, яке сокет scrape_target сутності Component оголошує для ключа, пропущеного цим з’єднанням. Схема, metrics_path і ціль обох завдань походять з адреси, яку публікує кожна Grafana, тобто з місця, де Grafana віддає свої метрики, тож жодне з’єднання нічого про них не каже. Задання ключа на з’єднанні перевизначає його для цього завдання й не зачіпає іншого.

Усе це відбувається на стороні споживача. Конфігурація окремого з’єднання з’являється лише в контексті рендерингу вузла, який створив з’єднання, і ніколи — в контексті цілі, тож підключення чи налаштування з’єднання до Grafana ніколи не змінює того, що рендерить сама ця Grafana, — її Deployment і її Service залишаються тими самими байтами в будь-якому разі.

Grafana віддає свої метрики будь-якому клієнту, тож жодне з’єднання не містить облікових даних. Для цілі, чиї метрики їх потребують, з’єднання передає їх у своєму слоті credential, а Prometheus пред’являє їх як bearer-токен, прочитаний із файлу; ціль, яка публікує metrics_credential_required зі значенням true, зупиняє збирання, доки її з’єднання не містить облікових даних.

Запуск (Compose)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker compose -f dist/app/compose/docker-compose.yaml up -d

Сутність Release призначає кожному Grafana власний порт — team-dashboards на 3000 і ops-dashboards на 3001, — тож обидва працюють поруч локально. Кожен Grafana слухає порт, який йому призначає його Release, і кожен порт передається в адресі, яку цей Grafana публікує в ціль власного завдання збирання.

Відкрийте http://127.0.0.1:9090 — браузер виразів Prometheus, який Recipe для Compose публікує лише на loopback-адресі хоста. У розділі Status → Targets обидва завдання наведено під іменами, які їм дає скомпільована конфігурація, ops-grafana і team-dashboards, кожне з адресою /metrics свого Grafana. Запит grafana_build_info — датчика, який кожен Grafana встановлює в 1 і позначає своєю версією, — повертає по одному ряду на завдання. Зупиніть і видаліть усе командою docker compose -f dist/app/compose/docker-compose.yaml down.