Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

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 component example/compute/service — gateway, và api/worker/ledger/etl/reconcile. Không component nào mang khối features: 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 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) đặt annotation một lần trên ranh giới platform và tinh chỉnh nó theo từng cây con:
    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 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ó:

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

Sau đó 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:

Terminal window
cd annotation-driven-monitoring

Build

Lệnh pull phân giải lockfile và bản build đọc nó:

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

Vớ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:

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

Tê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.yaml

Cá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.

ComponentRanh giớiintervalportpath
gatewayplatform30s (mặc định của platform)metrics/metrics
api / worker / ledgerpayments15s (ghi đè)metrics/metrics
etl / reconcilebatch120s (ghi đè)metrics/metrics

Ba điều mà bảng làm rõ:

  1. 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ộng core/prometheus-exporter lên từng component (origin của attachment trong đồ thị build là annotation, không phải explicit).
  2. Hợp nhất sâu theo từng khóa con. payments và batch chỉ đặt interval, vậy mà các ServiceMonitor của chúng vẫn mang port: metrics và 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.
  3. 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.