Giám sát dựa trên annotation — một annotation, nhiều component
Ví dụ này gắn một Feature giám sát vào sáu dịch vụ trải trên một
topology lồng nhau mà không cần viết một khối features: nào cho từng component. Một
annotation của người vận hành trên ranh giới cấp cao nhất, được tinh chỉnh bởi hai ghi đè cho cây con,
được mở rộng — thông qua liên kết features.annotations của Manifest — thành một
phần gắn core/prometheus-exporter trên mọi component được chứa bên trong, và mỗi component kết xuất
ServiceMonitor Prometheus riêng của nó.
Đây là bề mặt mở rộng Feature dựa trên annotation: mẫu dùng để nén các phần gắn Feature lặp lại cho từng component thành một annotation duy nhất lan truyền xuống cây ranh giới.
Hình dạng
- Ý định của nhà phát triển (
aggregate.yaml) chỉ khai báo sáu componentexample/compute/service—gateway, vàapi/worker/ledger/etl/reconcile. Không component nào mang khốifeatures:giám sát. - Manifest (
manifest.yaml) liên kết annotation với 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) đặt annotation một lần trên ranh giớiplatformvà tinh chỉnh nó theo từng cây con: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 và FeatureRecipe ServiceMonitor phạm vi component của nó được lấy từ catalog chuẩn (ví dụ này không khai báo bản sao cục bộ nào). Chart của recipe phát ra một ServiceMonitor monitoring.coreos.com/v1 cho mỗi component được gắn, tạo khuôn interval/port/path từ annotation đã được phân giải — cả ba đều là các tham số scrape của người vận hành trong infra của feature. (Đây là sinh tài nguyên bằng FeatureRecipe — source: + valuesMapping: do provider helm render — không phải một mutator Wasm hay một bước pipeline.)
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example annotation-driven-monitoringSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd annotation-driven-monitoringBuild
Lệnh pull phân giải lockfile và bản build đọc nó:
aggrega pull --release release.yamlaggrega build --release release.yamlVới trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `annotation-driven-monitoring`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `annotation-driven-monitoring` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `annotation-driven-monitoring` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `annotation-driven-monitoring`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `annotation-driven-monitoring/dist/`.Đầu ra được kết xuất chứng minh điều gì
Hãy phân giải lockfile, build và kiểm tra dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml:
aggrega pull --release release.yamlaggrega build --release release.yamlTên tệp đó đáng để giải mã, vì không ai ở đây gõ nó. Target này
chỉ đọc các tệp nằm trực tiếp trong một thư mục, nên các tệp của một phần gắn
nằm cạnh tệp của chính component và mang hai tọa độ của chúng trong tên tệp
thay vì trong các phân đoạn thư mục: component mà Feature được gắn vào, rồi
đến tên mà nó được gắn dưới đó. Ở đây tọa độ thứ hai không phải là tên do ai
viết — annotation tạo ra nó, và đó chính là khóa annotation,
feature.aggrega.ai/monitoring. Dấu chấm và dấu gạch chéo không thể đưa nguyên
vào tên tệp, nên mỗi ký tự trở thành -z cộng một chữ cái: -zd cho dấu chấm, -zs cho
dấu gạch chéo. Với component api trong ranh giới payments, bản build ghi ra
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlCách mã hóa này là lý do dấu gạch chéo trong khóa đó không mở ra thư mục riêng — và đó chính là mục đích, vì một tệp nằm sâu hơn một cấp là tệp mà một bên tiêu thụ scrape-config đọc thư mục ranh giới sẽ không nhận.
Ví dụ này lấy core/prometheus-exporter và FeatureRecipe ServiceMonitor của nó (cùng provider helm) từ thư viện chuẩn. Component demo example/compute/service và recipe của nó nằm trong catalog dùng chung dưới publisher example/, bên cạnh các thực thể của thư viện chuẩn đó. Tệp .aggrega-config.yaml của nó khai báo hub.aggrega.ai là registry mặc định, nên các thực thể được phân giải từ hub — cả hai lệnh đều không cần cờ --catalog.
| Component | Ranh giới | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s (mặc định của platform) | metrics | /metrics |
api / worker / ledger | payments | 15s (ghi đè) | metrics | /metrics |
etl / reconcile | batch | 120s (ghi đè) | metrics | /metrics |
Ba điều mà bảng làm rõ:
- Dựa trên annotation, không do tác giả khai báo. Aggregate không có
features:giám sát ở đâu cả, vậy mà sáu ServiceMonitor vẫn được kết xuất. Chúng tồn tại chỉ vì annotation đã mở rộngcore/prometheus-exporterlên từng component (origincủa attachment trong đồ thị build làannotation, không phảiexplicit). - Hợp nhất sâu theo từng khóa con.
paymentsvàbatchchỉ đặtinterval, vậy mà các ServiceMonitor của chúng vẫn mangport: metricsvàpath: /metrics— kế thừa từ giá trị có cấu trúc của annotation platform, được hợp nhất theo từng khóa con. Một cây con ghi đè một trường trong khi kế thừa các trường anh em. - Fan-out. Sáu component được giám sát từ một annotation platform
cộng hai ghi đè một dòng — không có khối
features:nào lặp lại cho từng component.
ServiceMonitor scrape cổng metrics có tên của Service (Service được tổng hợp
phơi ra metrics: 9090), nên port: metrics của liên kết phân giải tới một
endpoint thực.
Thời điểm biên dịch và thời điểm chạy
Đây là một ví dụ Kubernetes/Helm; bằng chứng là các manifest được kết xuất trong
dist/. port của ServiceMonitor tham chiếu cổng có tên của Service, nên
selector và endpoint khớp nhau theo cách xây dựng — không cần cluster để kiểm chứng
việc kết nối. Một Prometheus Operator đang chạy sẽ tiêu thụ các ServiceMonitor đã kết xuất vào
lúc triển khai; công việc của trình biên dịch (annotation → ServiceMonitor cho từng component với
profile được phân giải theo cascade) đã hoàn tất và có thể kiểm tra trước.
Bản build có tính tất định — chạy lại và đầu ra giống hệt từng byte.