跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

注解驱动的监控——一个注解,多个组件

本示例将一个监控 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 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)**在 platform 边界上设置一次注解,并按子树细化:
    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 及其组件作用域的 ServiceMonitor FeatureRecipe 来自标准目录(本示例没有声明本地副本)。该 recipe 的 chart 为每个附加的组件生成一个 monitoring.coreos.com/v1 ServiceMonitor,并根据解析后的注解模板化 interval/port/path——这三者都是该 feature 的 infra 中的运维抓取参数。(这是 FeatureRecipe 资源生成——由 helm provider 渲染的 source: + valuesMapping:——而不是 Wasm 变更器或流水线步骤。)

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

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

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd annotation-driven-monitoring

构建

pull 会解析锁文件,构建随后读取它:

Terminal window
aggrega pull --release release.yaml
aggrega 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:

Terminal window
aggrega pull --release release.yaml
aggrega 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边界intervalportpath
gatewayplatform30s(平台默认值)metrics/metrics
api / worker / ledgerpayments15s(覆盖)metrics/metrics
etl / reconcilebatch120s(覆盖)metrics/metrics

该表具体说明了三个事实:

  1. **由注解驱动,而非由作者声明。**Aggregate 中任何地方都没有监控 features:,却渲染出了六个 ServiceMonitor。它们仅仅因为注解将 core/prometheus-exporter 展开到每个组件上而存在(该附加项在构建图中的 origin 是 annotation,而不是 explicit)。
  2. 按子键深度合并。payments 和 batch 只设置了 interval,但 它们的 ServiceMonitor 带有 port: metrics 和 path: /metrics——继承自平台注解的结构化值,按子键合并。子树可以覆盖一个字段,同时继承其同级字段。
  3. 扇出。六个组件的监控来自一个平台注解 加两个单行覆盖——无需为每个组件重复 features: 块。

ServiceMonitor 抓取 Service 的具名 metrics 端口(合成的 Service 暴露 metrics: 9090),因此绑定中的 port: metrics 会解析到一个真实的端点。

编译时与运行时

这是一个 Kubernetes/Helm 示例;证据是 dist/ 中渲染出的 manifest。ServiceMonitor 的 port 引用 Service 的具名端口,因此选择器和端点在构造上就是匹配的——无需集群即可验证这一连接。运行中的 Prometheus Operator 会在部署时使用渲染出的 ServiceMonitor;编译器的工作(注解 → 带有级联解析配置的逐组件 ServiceMonitor)已提前完成,并且可以检查。

构建是确定性的——重新运行,输出逐字节相同。