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

Prometheus — 一个服务器,两个抓取目标

本示例将一个小型的真实技术栈——一个 Prometheus 指标服务器 抓取两个 Grafana 仪表盘服务器——从一个由 Developer 编写的 Aggregate 编译到两个目标:

  • 用于本地开发的 Docker Compose,以及
  • 通过基于官方 prom/prometheus 镜像的 Workload 合成生成的 Kubernetes。

同一个 aggregate.yaml 驱动两者。每个目标之间唯一变化的是 Manifest 所选的 Recipe 层。

Grafana 在其 Web 端口的 /metrics 上以 Prometheus 文本格式提供自身指标, 并且默认如此,因此每个 Grafana 都是真实的抓取 目标。两者是同一 Component 类型连接了两次,因此两个抓取作业之间 的所有差异,都来自每个连接上编写的内容, 以及每个 Grafana 声明的指标提供位置。

文件

文件角色
aggregate.yamlDeveloper 的意图:两个 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: 30s

team-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 助手替你构建。

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

Terminal window
aggrega scaffold --example prometheus-scrape

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

Terminal window
cd prometheus-scrape

构建

此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志:

Terminal window
# 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)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker 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 进行清理。