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 komponenexample/compute/service—gateway, sertaapi/worker/ledger/etl/reconcile. Tidak ada komponen yang membawa blokfeatures:pemantauan. - Manifest (
manifest.yaml) mengikat anotasi ke 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) menetapkan anotasi sekali pada batasplatformdan menyempurnakannya per subpohon: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 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:
aggrega scaffold --example annotation-driven-monitoringKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd annotation-driven-monitoringBuild
Pull me-resolve lockfile dan build membacanya:
aggrega pull --release release.yamlaggrega build --release release.yamlDengan 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:
aggrega pull --release release.yamlaggrega build --release release.yamlNama 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.yamlPengodean 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.
| Component | Batas | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (bawaan platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (penimpaan) | metrics | /metrics |
etl / reconcile | batch | 120s (penimpaan) | metrics | /metrics |
Tiga fakta yang diperjelas oleh tabel:
- Berbasis anotasi, bukan dideklarasikan penulis. Aggregate tidak memiliki
features:pemantauan di mana pun, namun enam ServiceMonitor dirender. ServiceMonitor tersebut ada hanya karena anotasi memperluascore/prometheus-exporterke setiap komponen (originlampiran tersebut dalam graf build adalahannotation, bukanexplicit). - Penggabungan mendalam per subkunci.
paymentsdanbatchhanya menetapkaninterval, namun ServiceMonitor keduanya membawaport: metricsdanpath: /metrics— diwarisi dari nilai terstruktur anotasi platform, digabungkan per subkunci. Sebuah subpohon menimpa satu field sambil mewarisi field saudaranya. - 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.