Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Pemantauan berbasis anotasi — satu anotasi, banyak komponen

Contoh ini memasang sebuah Feature pemantauan ke enam layanan di seluruh topologi bersarang tanpa menulis satu pun blok features: per komponen. Satu anotasi operator pada batas teratas, yang disempurnakan oleh dua penimpaan subpohon, diperluas — melalui pengikatan features.annotations milik Manifest — menjadi pemasangan core/prometheus-exporter pada setiap komponen yang tercakup, dan masing-masing merender ServiceMonitor Prometheus-nya sendiri.

Inilah permukaan ekspansi Feature berbasis anotasi: pola untuk memadatkan pemasangan Feature per komponen yang berulang menjadi satu anotasi yang menurun ke bawah pohon batas.

Bentuknya

  • Maksud pengembang (aggregate.yaml) hanya mendeklarasikan enam komponen example/compute/service — gateway, serta api/worker/ledger/etl/reconcile. Tidak ada komponen yang membawa blok features: pemantauan.
  • Manifest (manifest.yaml) mengikat anotasi ke 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) menetapkan anotasi sekali pada batas platform dan menyempurnakannya per subpohon:
    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 beserta FeatureRecipe ServiceMonitor lingkup komponen-nya diambil dari katalog standar (contoh ini tidak mendeklarasikan salinan lokal). Chart milik resep tersebut menghasilkan satu ServiceMonitor monitoring.coreos.com/v1 per komponen yang dilampiri, dengan men-template interval/port/path dari anotasi yang telah diresolusi — ketiganya merupakan kenop scrape operator dalam infra milik fitur tersebut. (Ini adalah pembuatan sumber daya FeatureRecipe — source: + valuesMapping: yang dirender oleh provider helm — bukan mutator Wasm atau langkah pipeline.)

Membuat contoh

Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.

Tulis contoh ke folder baru yang dinamai sesuai contoh itu:

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

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd annotation-driven-monitoring

Build

Pull me-resolve lockfile dan build membacanya:

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

Dengan asisten AI

Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.

Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `annotation-driven-monitoring`, panggil tool `scaffold` sekali dengan `example` diatur ke `annotation-driven-monitoring` dan tanpa `dir`: tool itu menulis contoh ke folder baru `annotation-driven-monitoring`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `annotation-driven-monitoring`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `annotation-driven-monitoring/dist/`.

Apa yang dibuktikan oleh keluaran hasil render

Resolusikan lockfile, lakukan build, lalu periksa 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

Nama file itu layak diurai, karena tidak ada seorang pun yang mengetiknya. Target ini hanya membaca file yang berada langsung di dalam sebuah direktori, sehingga file sebuah pemasangan ditempatkan di samping file milik komponen itu sendiri dan membawa dua koordinatnya di nama file, bukan di segmen direktori: komponen tempat Feature dipasang, lalu nama yang digunakan untuk memasangnya. Di sini koordinat kedua bukanlah nama yang ditulis seseorang — anotasi yang membuatnya, dan nama itu adalah kunci anotasi itu sendiri, feature.aggrega.ai/monitoring. Titik dan garis miring tidak dapat dimasukkan ke nama file apa adanya, sehingga masing-masing menjadi -z diikuti sebuah huruf: -zd untuk titik, -zs untuk garis miring. Untuk komponen api di batas payments, build menulis

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

Pengodean inilah yang membuat garis miring dalam kunci tersebut tidak membuka direktori tersendiri — dan itulah tujuannya, karena file yang berada satu tingkat di bawah adalah file yang tidak akan diambil oleh konsumen konfigurasi scrape yang membaca direktori batas.

Contoh ini menggunakan core/prometheus-exporter beserta FeatureRecipe ServiceMonitor-nya (ditambah provider helm) dari pustaka standar. Komponen demo example/compute/service beserta resepnya berada di katalog bersama di bawah penerbit example/, berdampingan dengan entitas pustaka standar tersebut. .aggrega-config.yaml miliknya mendeklarasikan hub.aggrega.ai sebagai registri bawaan, sehingga entitas diresolusi dari hub — kedua perintah tidak memerlukan flag --catalog.

ComponentBatasintervalportpath
gatewayplatform30s (bawaan platform)metrics/metrics
api / worker / ledgerpayments15s (penimpaan)metrics/metrics
etl / reconcilebatch120s (penimpaan)metrics/metrics

Tiga fakta yang diperjelas oleh tabel:

  1. Berbasis anotasi, bukan dideklarasikan penulis. Aggregate tidak memiliki features: pemantauan di mana pun, namun enam ServiceMonitor dirender. ServiceMonitor tersebut ada hanya karena anotasi memperluas core/prometheus-exporter ke setiap komponen (origin lampiran tersebut dalam graf build adalah annotation, bukan explicit).
  2. Penggabungan mendalam per subkunci. payments dan batch hanya menetapkan interval, namun ServiceMonitor keduanya membawa port: metrics dan path: /metrics — diwarisi dari nilai terstruktur anotasi platform, digabungkan per subkunci. Sebuah subpohon menimpa satu field sambil mewarisi field saudaranya.
  3. Fan-out. Enam komponen dipantau dari satu anotasi platform ditambah dua penimpaan satu baris — tanpa blok features: yang diulang per komponen.

ServiceMonitor melakukan scrape pada port metrics bernama milik Service (Service hasil sintesis mengekspos metrics: 9090), sehingga port: metrics pada pengikatan teresolusi ke endpoint yang nyata.

Waktu kompilasi vs waktu jalan

Ini adalah contoh Kubernetes/Helm; buktinya adalah manifest hasil render di dist/. port ServiceMonitor merujuk ke port bernama milik Service, sehingga selector dan endpoint cocok secara konstruksi — tidak diperlukan kluster untuk memverifikasi pengkabelannya. Prometheus Operator yang aktif akan menggunakan ServiceMonitor hasil render pada waktu deploy; tugas kompiler (anotasi → ServiceMonitor per komponen dengan profil yang diresolusi secara kaskade) selesai dan dapat diperiksa sebelumnya.

Build bersifat deterministik — jalankan ulang dan keluarannya identik byte demi byte.