Prometheus — 一个服务器,两个抓取目标
本示例将一个小型的真实技术栈——一个 Prometheus 指标服务器
抓取两个 Grafana 仪表盘服务器——从一个由 Developer 编写的
Aggregate 编译到两个目标:
- 用于本地开发的 Docker Compose,以及
- 通过基于官方
prom/prometheus镜像的 Workload 合成生成的 Kubernetes。
同一个 aggregate.yaml 驱动两者。每个目标之间唯一变化的是
Manifest 所选的 Recipe 层。
Grafana 在其 Web 端口的 /metrics 上以 Prometheus 文本格式提供自身指标,
并且默认如此,因此每个 Grafana 都是真实的抓取
目标。两者是同一 Component 类型连接了两次,因此两个抓取作业之间
的所有差异,都来自每个连接上编写的内容,
以及每个 Grafana 声明的指标提供位置。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | Developer 的意图:两个 Grafana,即 team-dashboards 和 ops-dashboards(均为 core/observability/grafana),以及一个 metrics 服务器(core/observability/prometheus),它对每个 Grafana 各声明一次 scrape_target 使用。 |
manifest-compose.yaml | 将 Prometheus 类型映射到 Compose Recipe(compose/prometheus),将 Grafana 类型映射到 Grafana Compose Recipe(compose/grafana)。 |
manifest-helm-synth.yaml | 将 Prometheus 类型映射到合成的 helm Recipe(helm/prometheus),将 Grafana 类型映射到合成的 Grafana helm Recipe(helm/grafana)。两者都不拉取 chart。 |
release-compose.yaml / release-helm-synth.yaml | 两个目标的 Operator 记录。 |
在一个 socket 上连接两个目标
scrape_target 是一个承载两个连接的 socket,每个连接
成为一个抓取作业:
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: 30steam-dashboards 连接没有编写 values,因此其作业采用该
socket 声明的内容。ops-dashboards 连接设置了两个键,它设置的每个键
只影响该作业——team-dashboards 作业不受它们影响。
目标说明它在哪里提供指标
连接说明 Prometheus 抓取的频率和使用的作业名称;它从不说明抓取的位置。那是目标自身的事实,由目标发布:
每个 Grafana Recipe 发布 metrics_endpoint,即其指标的完整地址——协议、主机、端口和路径,例如 Compose 上的
http://team-dashboards:3000/metrics。Prometheus 根据该地址构建抓取作业:使用其协议、其路径,并以其主机和端口作为该作业的目标。
因此,不提供指标的目标不发布地址,将这样的目标连接到
scrape_target 会使构建停止并指出该目标,而不是编译出一个什么都抓取不到的作业。指标默认关闭、需由某个值开启的产品——目录中许多产品接受 metrics_enabled——在指标开启时发布其地址。在 Kubernetes 上,当没有单个地址能覆盖其全部指标时,目标可以改为发布 Prometheus 用于发现其指标的依据,即一个 Service 或一个 pod 选择器;Compose 实现没有可供发现的集群,遇到这样的目标会停止。
该 socket 同时接受服务器、有状态服务器和工作进程,因此数据库、日志存储或 Operator 也以相同方式连接;能否被抓取取决于它发布的内容。
演示内容
- 一个编写界面,多个目标。 单个 Aggregate 是栈是什么的 唯一事实来源。每个 Manifest 说明如何实现它。
- 一个插座,多个连接。 Aggregate 向
scrape_target连接多少个目标,Prometheus 就 抓取多少个目标。该 Recipe 为每个连接生成一个抓取作业,因此作业数量取决于拓扑, 而不是 Recipe。 - 按连接配置。
job_name和scrape_interval声明在插座的valueSchema上,这使它们成为连接的属性,而不是服务器的属性。一个抓取多个 目标的 Prometheus 无法在单个 Component 范围的值中表达多种抓取频率。 - 声明的默认值填充连接省略的键。
scrape_interval在插座的valueSchema上带有默认值。省略它的连接(此处为team-dashboards)会获得该默认值,而设置了它的连接(ops-dashboards)只覆盖自己设置的内容。 - 通过 String Pipe 连接抓取。 每个 Grafana Recipe 的
metrics_endpoint被传入 Prometheus,并渲染到该 Grafana 的 作业中:其协议、路径以及targets条目。编译器传递该字符串而不解释它:每个 Recipe 决定自己的目标发布什么地址,编译器原样传递。 - 符合 Provider 惯用方式的配置。 在两个目标上,服务器都会在启动时写入一个
最小的
prometheus.yml,其中的抓取作业指向已连接的 Grafana 实例,然后以它为配置 exec Prometheus。在 Compose 上它作为一个 服务运行;在 Kubernetes 上,同一个容器渲染为一个 StatefulSet。 - 持久状态。 Prometheus 将样本存储在数据卷上,使其
在重启后保留:本地为一个命名的 Compose 卷,在 Kubernetes 上则为每个副本一个
按
infra.storage确定大小的 PersistentVolumeClaim。每个 Grafana 将其用户和仪表板保存在自己的卷上。 - 可复现的镜像。 此处的每个 Recipe 都从
infra.engine_version固定其镜像标签,因此渲染出的工作负载引用固定的镜像。 - 精简的单一用途形态。 在 Kubernetes 上,Prometheus 组件渲染为 其 StatefulSet、ClusterIP 和 Headless Service,以及其数据卷 声明,别无其他。每个 Grafana 渲染为各自的 Deployment、Service 和 数据卷声明。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example prometheus-scrape然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd prometheus-scrape构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志:
# 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-pull渲染产物位于 dist/ 下。--auto-pull 会在构建期间将每个 Release 的
依赖解析到其锁文件中;预先运行一次 aggrega pull --release release-compose.yaml 效果相同,并且之后的构建无需该标志即可运行。合成的目标无需获取外部 chart——两个
Recipes 都直接将官方镜像渲染为 Kubernetes 资源。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `prometheus-scrape` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `prometheus-scrape`,不设 `dir`:它会把示例写入新的 `prometheus-scrape` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-compose.yaml` 和 `release-helm-synth.yaml`——每次都将 `workspace_root` 设为 `prometheus-scrape`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `prometheus-scrape/dist/` 下。编译后的抓取配置是什么样子
在 Compose 上,服务器会写出一个 prometheus.yml,其中为每个已连接的
Grafana 保存一个作业,每个作业都指向该 Grafana 发布的 metrics_endpoint——即它的
compose 服务名和端口:
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"在 Kubernetes 上,同样的两个作业由合成的 StatefulSet 的
启动命令写出,每个作业都指向对应 Grafana 的 Service,helm
provider 以组件名及其 default 服务键为该 Service 命名:
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"两个目标都从同样的两条 Aggregate 边编译出同样的两个作业:每个
Grafana 的 metrics_endpoint 通过各自的 scrape_target
连接传递,编译器将该字符串直接传入作业,不对其
进行解释。两个目标之间的差异在于每个 Grafana
发布的地址——一个是 compose 服务名,另一个是 Service 名——以及
写入配置的工作负载——一个是 Compose 服务,另一个是
StatefulSet。这里两个 Grafana 与
Prometheus 位于同一作用域;在 Kubernetes 上,如果 Release 将某个 Grafana 放在另一个命名空间中,
则通过以该命名空间限定的 Service 名来访问它。
将 team-dashboards 作业与 ops-grafana 作业对照阅读,即可看出每个
值的来源。ops-grafana 作业带有 ops-grafana 和 30s,因为
它的连接同时编写了这两项。team-dashboards 作业以
team-dashboards 作为其 job_name,因为 Aggregate 没有声明该值,而
Recipe 回退到连接别名——即该 Aggregate 为
连接起的名称——它带有 15s,是因为这是 Component 的
scrape_target socket 为该连接省略的键所声明的默认值。两个作业的
scheme、metrics_path 和目标都来自每个 Grafana 发布的地址,
即 Grafana 提供其指标的位置,因此两个
连接都无需提及它们。在某个连接上设置一个键,会为该作业覆盖它,
而不影响另一个作业。
所有这些都发生在消费端。每个连接的配置只出现在 编写该连接的节点的渲染上下文中,绝不会出现在 目标的渲染上下文中,因此将连接接入某个 Grafana 或调整该连接,都不会扰动 该 Grafana 自身渲染的内容——无论哪种情况,它的 Deployment 和 Service 都是相同的 字节。
Grafana 会向任何调用方提供其指标,因此两个连接都不携带
凭据。对于指标需要凭据的目标,连接会在
其 credential 槽中携带凭据,Prometheus 将其作为从
文件读取的 bearer token 提交;如果目标将 metrics_credential_required 发布为 true,而其连接未携带凭据,
构建就会中止。
运行(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -d该 Release 为每个 Grafana 分配各自的端口——team-dashboards 使用 3000,
ops-dashboards 使用 3001——因此两者可以在本地并行运行。每个 Grafana
监听其 Release 分配给它的端口,而每个端口随该 Grafana 发布的地址
进入它自己的抓取作业的目标。
打开 http://127.0.0.1:9090——即 Prometheus 表达式浏览器,Compose Recipe
仅在主机的回环地址上发布它。在
Status → Targets 下,两个作业以编译后的配置赋予它们的名称列出,即 ops-grafana 和 team-dashboards,各自指向
其 Grafana 的 /metrics。查询 grafana_build_info(每个
Grafana 都将该 gauge 设为 1 并以其版本作为标签),每个作业返回一个序列。使用
docker compose -f dist/app/compose/docker-compose.yaml down 进行清理。