Prometheus — một máy chủ, hai mục tiêu thu thập
Ví dụ này biên dịch một stack nhỏ, có thật — một máy chủ số liệu Prometheus
thu thập số liệu từ hai máy chủ bảng điều khiển Grafana — từ một
Aggregate do Developer soạn ra hai đích:
- Docker Compose cho phát triển cục bộ, và
- Kubernetes thông qua việc tổng hợp Workload trên image chính thức
prom/prometheus.
Cùng một aggregate.yaml điều khiển cả hai. Chỉ có lớp Recipe được Manifest
chọn là thay đổi theo từng đích.
Grafana cung cấp số liệu của chính nó ở định dạng văn bản Prometheus tại /metrics trên
cổng web của nó, và làm vậy theo mặc định, nên mỗi Grafana là một mục tiêu thu thập
thật. Cả hai là cùng một kiểu Component được nối hai lần, nên mọi điểm
khác nhau giữa hai job thu thập đều đến từ những gì được soạn trên mỗi
kết nối và từ nơi mỗi Grafana cho biết nó cung cấp số liệu của mình.
Các tệp
| Tệp | Vai trò |
|---|---|
aggregate.yaml | Ý định của Developer: hai Grafana, team-dashboards và ops-dashboards (cả hai đều là core/observability/grafana), và một máy chủ metrics (core/observability/prometheus) khai báo một lần sử dụng scrape_target cho mỗi Grafana. |
manifest-compose.yaml | Ánh xạ kiểu Prometheus tới Recipe Compose (compose/prometheus) và kiểu Grafana tới Recipe Compose của Grafana (compose/grafana). |
manifest-helm-synth.yaml | Ánh xạ kiểu Prometheus tới Recipe helm được tổng hợp (helm/prometheus) và kiểu Grafana tới Recipe helm được tổng hợp của Grafana (helm/grafana). Không Recipe nào tải về chart. |
release-compose.yaml / release-helm-synth.yaml | Bản ghi của Operator cho hai đích. |
Nối hai mục tiêu trên một socket
scrape_target là một socket mang hai kết nối, và mỗi kết nối trở thành một scrape job:
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: 30sKết nối team-dashboards không khai báo values nào, nên job của nó nhận những gì socket khai báo. Kết nối ops-dashboards đặt hai khóa, và mỗi khóa nó đặt chỉ định hình riêng job đó — job team-dashboards không bị chúng tác động.
Đích cho biết nơi nó phục vụ metrics
Một kết nối cho biết Prometheus scrape bao lâu một lần và dưới tên job nào;
nó không bao giờ cho biết ở đâu. Đó là thông tin riêng của đích, và đích công bố nó:
mỗi Grafana Recipe công bố metrics_endpoint, địa chỉ đầy đủ của metrics của nó
— scheme, host, cổng và đường dẫn, chẳng hạn
http://team-dashboards:3000/metrics trên Compose. Prometheus xây dựng scrape
job từ địa chỉ đó: scheme của nó, đường dẫn của nó, và host cùng cổng của nó làm
đích của job.
Vì vậy, một đích không phục vụ metrics thì không công bố địa chỉ nào, và việc nối một đích như vậy vào
scrape_target sẽ dừng quá trình build và nêu tên đích đó, thay vì biên dịch một job
không scrape được gì. Một sản phẩm có metrics tắt cho đến khi một giá trị bật chúng
lên — nhiều sản phẩm trong catalog nhận metrics_enabled — sẽ công bố địa chỉ của nó khi
metrics được bật. Trên Kubernetes, thay vào đó một đích có thể công bố thứ mà Prometheus
dùng để khám phá metrics của nó, một Service hoặc một pod selector, khi không có địa chỉ duy nhất nào
vươn tới tất cả chúng; bản hiện thực Compose không có cluster nào để khám phá
và sẽ dừng lại trước một đích như vậy.
Socket chấp nhận cả server, stateful server lẫn worker, nên một cơ sở dữ liệu, một kho log hay một operator cũng được nối theo cùng cách; việc nó có thể được scrape hay không được quyết định bởi những gì nó công bố.
Ví dụ này minh họa điều gì
- Một bề mặt soạn thảo, nhiều đích. Một Aggregate duy nhất là nguồn chân lý cho việc stack là gì. Mỗi Manifest cho biết cách hiện thực nó.
- Một socket, nhiều kết nối. Prometheus scrape bao nhiêu đích tùy theo số đích mà
Aggregate nối vào
scrape_target. Recipe phát ra một scrape job cho mỗi kết nối, nên số job đi theo topo chứ không theo Recipe. - Cấu hình theo từng kết nối.
job_namevàscrape_intervalđược khai báo trênvalueSchemacủa socket, khiến chúng trở thành thuộc tính của một kết nối chứ không phải của server. Một Prometheus scrape nhiều đích không thể biểu diễn nhiều nhịp độ trong một giá trị duy nhất áp dụng cho toàn Component. - Giá trị mặc định được khai báo lấp các khóa mà một kết nối bỏ qua.
scrape_intervalmang một giá trị mặc định trênvalueSchemacủa socket. Một kết nối bỏ qua nó — ở đây làteam-dashboards— sẽ nhận giá trị đó, còn một kết nối đặt nó —ops-dashboards— chỉ ghi đè những gì nó đã đặt. - Nối scrape qua String Pipe.
metrics_endpointcủa mỗi Grafana Recipe được dẫn vào Prometheus và được render vào job của Grafana đó: scheme, path và mụctargetscủa nó. Trình biên dịch định tuyến chuỗi mà không diễn giải nó: mỗi Recipe tự quyết định địa chỉ mà đích của chính nó công bố, và trình biên dịch dẫn nó đi qua mà không thay đổi. - Cấu hình đúng phong cách của Provider. Trên cả hai đích, server ghi một
prometheus.ymltối giản khi khởi động, với các scrape job trỏ tới các Grafana được nối, rồi exec Prometheus với tệp đó. Trên Compose, nó chạy như một service; trên Kubernetes, cùng container đó được render thành một StatefulSet. - Trạng thái bền vững. Prometheus lưu các mẫu của nó trên một data volume để chúng
tồn tại qua các lần khởi động lại — một named volume của Compose khi chạy cục bộ, và một
PersistentVolumeClaim cho mỗi replica với dung lượng lấy từ
infra.storagetrên Kubernetes. Mỗi Grafana giữ người dùng và dashboard của nó trên một volume riêng. - Image có thể tái lập. Mọi Recipe ở đây đều ghim tag image của nó từ
infra.engine_version, nên các workload được render tham chiếu tới các image cố định. - Hình dạng gọn, một mục đích. Trên Kubernetes, component Prometheus được render thành StatefulSet, các Service ClusterIP và Headless, và claim cho data volume của nó — không gì khác. Mỗi Grafana được render thành Deployment, Service và claim cho data volume riêng của nó.
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 prometheus-scrapeSau đó 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 prometheus-scrapeBuild
Workspace này không có .aggrega-config.yaml, nên các thực thể thư viện chuẩn được phân giải từ registry hub, hub.aggrega.ai, và không cần cờ catalog:
# 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-pullCác artifact được render nằm trong dist/. --auto-pull phân giải các phụ thuộc của mỗi Release vào lockfile của nó trong quá trình build; chạy aggrega pull --release release-compose.yaml một lần từ trước cũng làm điều tương tự và cho phép các lần build sau chạy
mà không cần cờ này. Đích được tổng hợp không cần tải chart từ bên ngoài — cả hai
Recipes đều render trực tiếp các image chính thức thành tài nguyên Kubernetes.
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 `prometheus-scrape`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `prometheus-scrape` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `prometheus-scrape` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-compose.yaml` và `release-helm-synth.yaml` — mỗi lần với `workspace_root` đặt thành `prometheus-scrape`, `release` đặt thành tệp đó, `auto_pull` đặt thành true và `write` đặt thành true. Cho tôi biết mỗi bản dựng đã ghi những tệp nào; chúng nằm trong `prometheus-scrape/dist/`.Cấu hình scrape sau khi biên dịch trông như thế nào
Trên Compose, server ghi ra một tệp prometheus.yml chứa một job cho mỗi
Grafana được nối dây, mỗi job trỏ tới metrics_endpoint mà Grafana đó công bố — tên
compose service và cổng của nó:
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"Trên Kubernetes, cùng hai job đó được ghi bởi lệnh khởi động của StatefulSet
được tổng hợp, mỗi job trỏ tới Service của Grafana tương ứng, mà helm
provider đặt tên theo component và khóa service default của nó:
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"Cả hai target đều biên dịch ra cùng hai job từ cùng hai cạnh của Aggregate:
metrics_endpoint của mỗi Grafana đi qua kết nối scrape_target
riêng của nó, và trình biên dịch chuyển chuỗi đó vào job mà không
diễn giải nó. Điều khác nhau giữa các target là địa chỉ mà mỗi Grafana
công bố — một tên compose service ở target này, một tên Service ở target kia — và
workload mà cấu hình được ghi vào — một Compose service ở target này, một
StatefulSet ở target kia. Ở đây cả hai Grafana nằm trong cùng phạm vi với
Prometheus; trên Kubernetes, một Grafana mà Release đặt trong namespace khác
được trỏ tới bằng tên Service của nó kèm theo namespace đó.
Hãy đối chiếu job team-dashboards với job ops-grafana để thấy mỗi
giá trị đến từ đâu. Job ops-grafana mang ops-grafana và 30s vì
kết nối của nó khai báo cả hai. Job team-dashboards mang
team-dashboards làm job_name vì Aggregate không khai báo tên nào và
Recipe dùng dự phòng là bí danh kết nối — tên mà Aggregate này đặt cho
kết nối — và nó mang 15s vì đó là giá trị mặc định mà socket scrape_target
của Component khai báo cho khóa mà kết nối đó bỏ qua. Scheme, metrics_path và target của cả hai job đến từ địa chỉ
mà mỗi Grafana công bố, tức là nơi Grafana phục vụ metrics của nó, nên không
kết nối nào nói gì về chúng. Đặt một khóa trên một kết nối sẽ ghi đè nó
cho job đó và không ảnh hưởng đến job còn lại.
Tất cả điều này diễn ra ở phía tiêu thụ. Cấu hình theo từng kết nối chỉ xuất hiện trong ngữ cảnh render của node đã khai báo kết nối, không bao giờ trong ngữ cảnh của target, nên việc nối dây hay tinh chỉnh một kết nối tới một Grafana không bao giờ làm xáo trộn những gì chính Grafana đó render — Deployment và Service của nó vẫn giống hệt nhau từng byte trong cả hai trường hợp.
Grafana trả metrics cho bất kỳ bên gọi nào, nên không kết nối nào mang
thông tin xác thực. Với một target mà metrics cần thông tin xác thực, kết nối mang nó trong
slot credential của nó, và Prometheus trình nó dưới dạng bearer token đọc từ một
tệp; một target công bố metrics_credential_required là true sẽ dừng
bản build khi kết nối của nó không mang thông tin xác thực nào.
Chạy thử (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dRelease cấp cho mỗi Grafana một cổng riêng — team-dashboards trên cổng 3000 và
ops-dashboards trên cổng 3001 — để cả hai chạy song song trên máy cục bộ. Mỗi Grafana
lắng nghe trên cổng mà Release của nó cấp, và mỗi cổng đi theo địa chỉ
mà Grafana đó công bố vào target của scrape job riêng của nó.
Mở http://127.0.0.1:9090 — trình duyệt biểu thức của Prometheus, mà
Compose Recipe chỉ công bố trên địa chỉ loopback của máy chủ. Trong
Status → Targets, hai job được liệt kê dưới các tên mà cấu hình đã biên dịch
đặt cho chúng, ops-grafana và team-dashboards, mỗi job trỏ tới
/metrics của Grafana tương ứng. Một truy vấn grafana_build_info, gauge mà mọi
Grafana đặt bằng 1 và gắn nhãn phiên bản của nó, trả về một series cho mỗi job. Dọn dẹp
bằng docker compose -f dist/app/compose/docker-compose.yaml down.