注解驱动的监控——一个注解,多个组件
本示例将一个监控 Feature 附加到嵌套拓扑中的六个服务上,而无需编写任何逐组件的 features: 块。顶层边界上的一个运维注解,经两个子树覆盖细化后,
通过 Manifest 的 features.annotations 绑定展开为每个所含组件上的
core/prometheus-exporter 附加,每个组件都渲染出自己的 Prometheus ServiceMonitor。
这就是注解驱动的 Feature 展开机制:一种将重复的逐组件 Feature 附加压缩为单个注解、并沿边界树向下级联的模式。
结构
- **开发者意图(
aggregate.yaml)**只声明了六个example/compute/service组件——gateway,以及api/worker/ledger/etl/reconcile。没有任何 组件带有监控features:块。 - **Manifest(
manifest.yaml)**将注解绑定到 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)**在platform边界上设置一次注解,并按子树细化: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 及其组件作用域的 ServiceMonitor FeatureRecipe 来自标准目录(本示例没有声明本地副本)。该 recipe 的 chart 为每个附加的组件生成一个 monitoring.coreos.com/v1 ServiceMonitor,并根据解析后的注解模板化 interval/port/path——这三者都是该 feature 的 infra 中的运维抓取参数。(这是 FeatureRecipe 资源生成——由 helm provider 渲染的 source: + valuesMapping:——而不是 Wasm 变更器或流水线步骤。)
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example annotation-driven-monitoring然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd annotation-driven-monitoring构建
pull 会解析锁文件,构建随后读取它:
aggrega pull --release release.yamlaggrega build --release release.yaml借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `annotation-driven-monitoring` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `annotation-driven-monitoring`,且不提供 `dir`:它会把示例写入一个新的 `annotation-driven-monitoring` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `annotation-driven-monitoring`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `annotation-driven-monitoring/dist/` 下。渲染输出证明了什么
解析锁文件并构建,然后查看 dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml:
aggrega pull --release release.yamlaggrega build --release release.yaml**这个文件名值得解读,因为它并非由任何人键入。**该目标只读取直接位于目录中的文件,因此附加的文件与组件自身的文件放在一起,并将两个坐标写在文件名中而不是目录层级中:先是 Feature 所附加的组件,然后是附加时使用的名称。这里第二个坐标并非任何人编写的名称——它由注解生成,就是注解键本身,
feature.aggrega.ai/monitoring。点和斜杠不能原样放入文件名,因此各自变为 -z 加一个字母:点为 -zd,斜杠为 -zs。对于 payments 边界中的 api 组件,构建写出
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yaml正是这种编码使该键中的斜杠不会单独开一层目录——这正是目的所在,因为下一层的文件不会被读取边界目录的抓取配置使用方拾取。
本示例从标准库使用 core/prometheus-exporter 及其 ServiceMonitor FeatureRecipe(以及 helm provider)。example/compute/service 演示组件及其 recipe 位于共享目录中的 example/ 发布者下,与这些标准库实体并列。其 .aggrega-config.yaml 将 hub.aggrega.ai 声明为默认注册表,因此这些实体从 hub 解析——两条命令都无需 --catalog 标志。
| Component | 边界 | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s(平台默认值) | metrics | /metrics |
api / worker / ledger | payments | 15s(覆盖) | metrics | /metrics |
etl / reconcile | batch | 120s(覆盖) | metrics | /metrics |
该表具体说明了三个事实:
- **由注解驱动,而非由作者声明。**Aggregate 中任何地方都没有监控
features:,却渲染出了六个 ServiceMonitor。它们仅仅因为注解将core/prometheus-exporter展开到每个组件上而存在(该附加项在构建图中的origin是annotation,而不是explicit)。 - 按子键深度合并。
payments和batch只设置了interval,但 它们的 ServiceMonitor 带有port: metrics和path: /metrics——继承自平台注解的结构化值,按子键合并。子树可以覆盖一个字段,同时继承其同级字段。 - 扇出。六个组件的监控来自一个平台注解
加两个单行覆盖——无需为每个组件重复
features:块。
ServiceMonitor 抓取 Service 的具名 metrics 端口(合成的
Service 暴露 metrics: 9090),因此绑定中的 port: metrics 会解析到一个真实的端点。
编译时与运行时
这是一个 Kubernetes/Helm 示例;证据是 dist/ 中渲染出的 manifest。ServiceMonitor 的 port 引用 Service 的具名端口,因此选择器和端点在构造上就是匹配的——无需集群即可验证这一连接。运行中的 Prometheus Operator 会在部署时使用渲染出的 ServiceMonitor;编译器的工作(注解 → 带有级联解析配置的逐组件 ServiceMonitor)已提前完成,并且可以检查。
构建是确定性的——重新运行,输出逐字节相同。